A conversation is the agent doing its job: a user says something, the agent decides what to do, and everything it did comes back as typed events.
Driving that from your own code is how you put the agent behind a different interface, or check how a change behaves before anyone else sees it. Conversation state sits alongside, so you can read what the agent currently believes, change a variable mid-turn, or start over.
Endpoints
Conversation
Conversation state
Knowledge base query
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.