Begin a chat session with an agent.

You can use the cursor field to continue a multi-turn conversation:

• Start a new conversation by omitting cursor.
• Continue a conversation by passing the cursor from the previous response.

When a cursor is provided, there is no need to include previous message history in the messages field.

Tool confirmation flow

Integration tools — Call Function, Run Python code, and Call REST API — require explicit user confirmation before execution. When the agent wants to run one of these tools, the response includes a toolConfirmation action instead of the final result.

To continue, send a follow-up request with the same cursor and a message of type toolConfirmation in the messages array:

{
  "agentExternalId": "my_agent",
  "cursor": "<cursor from previous response>",
  "messages": [
    {
      "role": "action",
      "type": "toolConfirmation",
      "actionId": "<actionId from the toolConfirmation action>",
      "status": "ALLOW"
    }
  ]
}

Set status to "ALLOW" to let the agent execute the tool, or "DENY" to cancel it.

Streaming

Set stream to true in the request to receive Server-Sent Events (SSE) as the agent works. Each event is an AgentSessionResponse whose response.type discriminator indicates the kind of event:

• progress — status updates while the agent is working (e.g. "Searching knowledge graph…"). Useful for showing a spinner or activity indicator.
• responseChunk — incremental content fragments of the agent's reply. Concatenate these to build the full response as it streams in.
• result — the final complete response, including messages, cursor, and any actions. Always the last event in the stream.

When stream is false (the default), only a single result response is returned.