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.
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: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 toCovalTextClient, 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 readyTextConnection 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, andsend_message()returnsFalseinstead 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.
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:- Starts a session with a
GETrequest. - Needs a new access token on every request.
- Ends the session with a
DELETErequest.
get_access_token() with your API’s own:
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:
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():
Results and errors
Text results use the sameRunResult 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.