Skip to main content
Use CovalTextClient from coval-agent-sdk to run Coval text simulations against a chat agent that your application runs. Your handler receives each simulated-user message and sends the agent’s reply. Coval records and evaluates the conversation. The SDK opens an outbound WebSocket, so your agent does not need a public endpoint. The text client also fits chat backends that the standard chat connection cannot call directly, for example an API that needs a session setup request, a fresh credential for each request, or a cleanup call after the conversation. Your handler makes those calls itself. Text agents require coval-agent-sdk 0.2.0 or later and Python 3.10 or newer. See Install.

Before you run

Select these resources from the same Coval workspace:
  • An organization API key with the Agent SDK permissions.
  • The workspace ID.
  • An agent whose type is MODEL_TYPE_SDK_CHAT.
  • A persona and a test set containing your scenarios.
For a first run, one case and one iteration are enough.

Create an SDK chat agent

The Coval web app and CLI don’t create SDK chat agents yet. Create one with the Agents API. The agent needs no endpoint or metadata, because your application connects to Coval:
The response’s agent.id is the agent_id for RunConfig. Creating an agent requires the agents:write permission, which the SDK itself doesn’t need.

Check the connection

Pass your API key and workspace ID to CovalTextClient, and the agent, persona, and test-set IDs to RunConfig. This example reads those values from environment variables. The handler echoes each simulated-user message to check the connection:
run() creates a run, calls your handler for each conversation, and waits for the run to complete, including evaluation. RunConfig works as it does for voice agents.

How a text conversation works

The SDK calls your handler with a ready TextConnection for each conversation. In the handler:
  • Read simulated-user messages from receive_messages(). Each message is one user turn. Use one receive loop per connection.
  • Reply to each message with one send_message() call. Each call is one complete agent turn, so combine a multi-part backend response into one reply. A reply must be nonempty and at most 64 KiB when UTF-8 encoded.
  • If the persona’s Conversation Initiator setting is Persona waits to speak, send the agent’s greeting with send_message() before reading. Otherwise, wait for the first simulated-user message.
  • The simulated user ends the conversation. receive_messages() then stops, and send_message() returns False instead of sending. The SDK never resends a message.
  • Return from the handler after receive_messages() ends. Finish your own cleanup first. Returning earlier raises an SDK error.
Reply promptly. At most 64 unread messages can wait in the connection, and the session fails if no simulated-user message arrives for 600 seconds, which bounds how long your agent can take to answer one turn. Handlers for different conversations may run concurrently, so keep conversation state inside the handler.

Text connection reference

Wrap an existing HTTP chat backend

The handler can call any API your agent already exposes. This example uses HTTPX with a chat API that:
  1. Starts a session with a GET request.
  2. Needs a new access token on every request.
  3. Ends the session with a DELETE request.
Replace the URLs, payload fields, and get_access_token() with your API’s own:
Pass this handler to client.run(config, on_connection=on_connection) as in Check the connection. The finally block runs after the simulated user ends the conversation and also when a request or the connection fails, so the backend session is released either way. An exception in the handler propagates from run() after the SDK cleans up the connection.

Connect to one conversation or serve your own run

client.connect(simulation_id) attaches the text client to one existing simulation without launching a run:
To choose metrics, test cases, or run metadata that RunConfig doesn’t cover, launch the run through the API yourself and pass its ID to attach(). attach() serves every conversation in that run and returns the same results as run():
Connecting the text client to a simulation whose agent isn’t an SDK chat agent fails before your handler runs.

Results and errors

Text results use the same RunResult and ConversationResult types as voice. For text conversations, ConversationResult.received_messages and sent_messages count the messages exchanged, and the audio byte counts are zero. Errors, partial results, and local timeouts work as they do for voice. See Results and errors. To send OpenTelemetry traces, pass a CovalTraceExporter to CovalTextClient(trace_exporter=...) and follow Optional OpenTelemetry traces.

Source and support

See the SDK repository for the implementation and API contracts. For integration help, contact Coval support.