chat_with_agent
Conduct a scripted text conversation with a published agent, wait for each turn to settle, and obtain the full transcript for automated testing and prompt refinement.
Instructions
Hold a TEXT conversation with a published agent over the realtime chat WebSocket (mode=chat) — no audio, no phone, just text in / text out. Sends each message in messages in order, waiting for each agent turn to FULLY settle before sending the next — a turn can be several messages (a filler while a tool runs, then the answer), so tool-using flows (auth, lookups) complete instead of being cut off. Returns the full transcript. Use this to test an agent's prompt/behaviour programmatically (e.g. an automated build → test → evaluate → refine loop): run a scripted conversation, read the transcript, then adjust the prompt with update_agent and run again. This places a real (chargeable) chat session on the agent. Note: the agent must be published; to chat with unpublished draft changes use test_agent (mode=chat, include_draft=true).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | The agent ID to chat with (must be a published agent) | |
| messages | Yes | User turns to send, in order. Each is sent only after the previous turn's reply arrives. For realistic tests, write messages a real caller would send. | |
| settle_ms | No | Silence after a SUBSTANTIVE agent message before the turn counts as finished. Fillers (messages ending in '…', spoken while a tool runs) are waited on much longer automatically, so this can stay small; raise it only if the agent sends its answer in several slow bursts. | |
| variables | No | Per-call values for {{key}} placeholders in the agent prompt | |
| greeting_wait_ms | No | Time to wait after connecting for the agent's opening message (0 if it waits for the user first) | |
| reply_timeout_ms | No | Hard cap on how long to wait for a single agent turn before giving up on it |