Skip to main content
The conversation endpoints run the agent. You send what the user did, and you get back everything the agent did in response, one turn at a time.

​
A conversation is a userID

There is no session to create. The userID in the path is the conversation: call the same path again and the agent continues where it left off, call it with a new userID and you get a fresh one.
That returns an array of traces describing everything the agent did in response.

​
The two fields that matter

action is what the user did. launch starts the agent from its entry point; text sends something they typed:
version chooses which build answers. published runs the live version of the environment; draft runs what you are currently editing, which is what you want while testing a change.

​
Reading the response

The agent’s output is a list of traces, not a single message. A chat agent’s words arrive as text traces; a voice agent answers with speak. Buttons, cards, carousels and debug output each have their own type, and the trace reference documents every one. Two things worth handling from the start:
  • Iterate the traces rather than taking the first. A single turn routinely returns a message, then buttons, then debug output.
  • Strip control characters before parsing. The runtime can emit raw control characters inside trace payload strings, which strict JSON parsers reject.

​
Conversation state

The state endpoints let you inspect what the agent currently believes, change a variable mid-conversation, or delete the state to start over without changing the userID.

​
Where to go next

The first conversation turn recipe is this flow as a script you can run, verified against a live agent.