SSE & WebSocket Integrations

Lamdis supports three protocols for communicating with assistant APIs:

1. HTTP Chat (default) - Standard HTTP POST requests with JSON responses
2. Server-Sent Events (SSE) - Streaming responses over HTTP
3. WebSocket - Bidirectional real-time communication

When to Use Each Protocol

Configuring SSE Connections

SSE (Server-Sent Events) is ideal for APIs that stream responses token-by-token, like OpenAI’s chat completions endpoint.

Organization Connection Configuration

Add SSE configuration to your organization’s connection:

{
  "connections": {
    "openai-streaming": {
      "base_url": "https://api.openai.com/v1/chat/completions",
      "protocol": "sse",
      "headers": {
        "Authorization": "Bearer sk-..."
      },
      "responseFieldPath": "choices[0].message.content",
      "sse": {
        "contentPath": "choices[0].delta.content",
        "finishPath": "choices[0].finish_reason",
        "finishValue": ["stop", "length"]
      }
    }
  }
}

SSE Configuration Options

Example: OpenAI-Compatible API

{
  "protocol": "sse",
  "sse": {
    "contentPath": "choices[0].delta.content",
    "finishPath": "choices[0].finish_reason", 
    "finishValue": ["stop", "length", "content_filter"]
  }
}

Example: Claude API (Anthropic)

{
  "protocol": "sse",
  "sse": {
    "contentPath": "delta.text",
    "finishPath": "type",
    "finishValue": "message_stop"
  }
}

Configuring WebSocket Connections

WebSocket connections are ideal for real-time bidirectional communication, such as voice assistants or live agent interfaces.

Organization Connection Configuration

{
  "connections": {
    "realtime-assistant": {
      "base_url": "wss://api.example.com/ws/chat",
      "protocol": "websocket",
      "websocket": {
        "messageFormat": "json",
        "messageField": "content",
        "contentPath": "response.text",
        "finishPath": "type",
        "finishValue": "done"
      }
    }
  }
}

WebSocket Configuration Options

Example: Custom WebSocket API

{
  "protocol": "websocket",
  "websocket": {
    "messageFormat": "json",
    "messageField": "userMessage",
    "contentPath": "assistantResponse.content",
    "finishPath": "status",
    "finishValue": "complete"
  }
}

Using Protocols in Tests

When running tests, Lamdis will automatically use the configured protocol for the selected connection. The protocol configuration flows through:

1. Organization Connection → Protocol config stored with the connection
2. Test Run → Connection selected when starting a run
3. Engine → Uses appropriate client (HTTP, SSE, or WebSocket)

Live Progress with Streaming

For SSE and WebSocket connections, Lamdis provides real-time progress updates:

• Stream chunks are logged as they arrive
• firstTokenMs shows time to first token (TTFT)
• streamChunks count shows total chunks received

Example Test Log Entry

{
  "type": "assistant_reply",
  "content": "The full assembled response...",
  "latencyMs": 2500,
  "protocol": "sse",
  "streamChunks": 45,
  "firstTokenMs": 150
}

Troubleshooting

SSE Connection Issues

1. No content received: Verify contentPath matches your API’s event structure
2. Stream never ends: Check finishPath and finishValue configuration
3. Timeout errors: Increase timeoutMs for slow-streaming responses

WebSocket Connection Issues

1. Connection refused: Verify the URL uses wss:// for secure WebSocket
2. Message format errors: Ensure messageFormat matches your API expectations
3. Authentication failed: Check that auth headers are properly configured

Debug Tips

1. Enable verbose logging to see raw SSE events or WebSocket messages
2. Test your connection configuration with a simple message first
3. Check the run logs for stream_chunk entries to verify streaming is working

Migration from HTTP Chat

To migrate an existing HTTP connection to SSE:

1. Update the protocol field to "sse"
2. Add sse configuration with appropriate paths
3. Test with a simple message to verify streaming works

{
  "connections": {
    "my-assistant": {
      "base_url": "https://api.example.com/chat",
+     "protocol": "sse",
+     "sse": {
+       "contentPath": "delta.content",
+       "finishPath": "done",
+       "finishValue": true
+     }
    }
  }
}