Skip to main content

​
Overview

WebSocket connections enable real-time, bidirectional communication with your AI agents. This connection type is ideal for chat-based agents, real-time assistants, or any application that requires persistent, low-latency message exchange. When you connect a WebSocket agent, Coval establishes a secure connection to your endpoint and handles the full conversation flow—sending messages, receiving responses, and evaluating performance.

​
Configuration Requirements

​
WebSocket Endpoint

  • Field: endpoint
  • Type: String (required)
  • Purpose: The WebSocket URL that Coval connects to for simulations
  • Format: Must start with wss:// (secure WebSocket)
  • Example: wss://your-api.com/ws/chat
Only secure WebSocket connections (wss://) are supported. Plain ws:// endpoints will be rejected for security reasons.

​
Initialization JSON

  • Field: initialization_json
  • Type: JSON object (optional)
  • Purpose: Initial payload sent to your WebSocket endpoint when the connection is established
  • Format: Valid JSON object
  • Use Cases: Session initialization, authentication handshakes, context setup
Example: 
{
  "action": "start_session",
  "session_type": "simulation",
  "metadata": {
    "source": "coval",
    "test_mode": true
  }
}
The initialization JSON is sent immediately after the WebSocket connection is established. Use this to configure your agent’s behavior or authenticate the session.

​
Authorization Header

  • Field: authorization_header
  • Type: String (optional)
  • Purpose: Authentication value sent in the Authorization header during the WebSocket handshake
  • Format: Standard authorization header value
  • Security: Stored encrypted and handled securely
Common formats:
  • Bearer token: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  • API key: X-API-Key your-api-key-here
  • Basic auth: Basic base64-encoded-credentials

​
Custom Headers

  • Field: custom_headers
  • Type: JSON object (optional)
  • Purpose: Additional HTTP headers sent during the WebSocket handshake
  • Format: Valid JSON object with string key-value pairs
  • Use Cases: Custom authentication, routing headers, client identification
Example: 
{
  "X-Client-ID": "coval-simulation",
  "X-API-Version": "2024-01",
  "X-Environment": "production"
}

​
Setup Instructions

  1. Prepare your WebSocket endpoint
    • Ensure your endpoint accepts secure WebSocket connections (wss://)
    • Configure your server to handle the authorization header if authentication is required
    • Set up message handling for the conversation flow
  2. Create the agent in Coval
    • Navigate to app.coval.dev/agents/create
    • Select WebSocket as the connection type
    • Enter your WebSocket endpoint URL (must start with wss://)
    • Add authorization header if your endpoint requires authentication
    • Configure initialization JSON if you need to send a setup payload
    • Add any custom headers required by your endpoint
  3. Test the connection
    • Create a simple test set with a few scenarios
    • Launch a simulation to verify end-to-end connectivity
    • Check that messages are being sent and received correctly

​
How Simulations Work

When you launch a simulation with a WebSocket agent, Coval:
  1. Establishes the connection — Opens a secure WebSocket connection to your endpoint with the configured headers
  2. Sends initialization payload — If configured, sends the initialization JSON immediately after connection
  3. Starts the conversation — Sends the first message based on your test case configuration
  4. Exchanges messages — Receives agent responses and sends follow-up messages according to the persona behavior
  5. Records the transcript — Captures the full conversation for evaluation
  6. Runs metrics — Evaluates the conversation against your configured metrics
  7. Closes the connection — Cleanly terminates the WebSocket connection

​
Message Format

Coval sends and expects messages in JSON format with a content field containing the message text: Outgoing message (Coval → Your Agent): 
{
  "content": "Hello, I need help with my order"
}
Expected response (Your Agent → Coval): 
{
  "content": "Hi! I'd be happy to help you with your order. Could you please provide your order number?"
}
Your WebSocket endpoint should respond with JSON messages containing a content field. Coval extracts this field to build the conversation transcript.

​
Technical Requirements

​
Endpoint Requirements

RequirementDetails
Protocolwss:// (TLS-encrypted WebSocket)
AccessibilityMust be publicly accessible from Coval servers
Response formatJSON with content field
Connection timeoutConnections may be held open for the duration of the simulation

​
Running Locally

If your WebSocket server is running locally, you’ll need to expose it publicly for Coval to connect. Use a tunneling service like ngrok: 
ngrok http 8080
# Use the generated wss:// URL as your endpoint
# Note: ngrok provides wss:// automatically for HTTPS tunnels
Remember to update your agent configuration when your tunnel URL changes. Consider using ngrok’s reserved domains for persistent URLs.

​
Troubleshooting

​
Connection Failures

“Invalid WebSocket URL” error
  • Verify your endpoint starts with wss:// (not ws://, http://, or https://)
  • Check that the URL is properly formatted with no trailing spaces
“Connection refused” error
  • Ensure your WebSocket server is running and accessible
  • Check firewall rules allow inbound connections on the WebSocket port
  • Verify the endpoint URL is correct
“Authentication failed” error
  • Confirm your authorization header value is correct
  • Check that the header format matches what your server expects
  • Verify the API key or token hasn’t expired

​
Message Handling Issues

“No response received” error
  • Ensure your agent sends responses in JSON format with a content field
  • Check that your agent is processing and responding to incoming messages
  • Verify there are no errors in your agent’s logs
“Invalid JSON in response” error
  • Confirm your agent returns valid JSON
  • Check for proper encoding of special characters
  • Ensure the content field is a string

​
Timeout Issues

Simulation timeouts
  • Verify your agent responds within a reasonable time (< 30 seconds per message)
  • Check for any blocking operations in your agent’s message handler
  • Monitor your agent’s resource usage during simulations

​
Best Practices

  1. Use persistent connections — WebSocket agents should maintain the connection throughout the conversation
  2. Handle reconnection gracefully — If your agent supports it, configure automatic reconnection
  3. Log initialization payloads — Track the initialization JSON in your server logs for debugging
  4. Implement health checks — Add a ping/pong mechanism to detect connection issues early
  5. Secure your endpoint — Always use wss:// and implement proper authentication