Sessions API

Sessions represent conversations with agents. They store conversation history, resources, and variables.

Create Session

Create a new agent session.

text

Request Body

json

Field	Type	Required	Description
`agentId`	string	Yes	Agent ID (the `id` field, not `slug`)
`input`	object	No	Input variables for the agent

To get the agent ID, copy it from the platform URL, use Get Agent by slug (GET /api/agents/:slug?by=slug), or the SDK's agents.getBySlug() method.

Response

json

Example

bash

Get Session

Retrieve session state including UI-ready messages and resources.

text

Response

The response includes UIMessage objects that can be passed directly to the client SDK's initialMessages option:

json

UIMessage Parts

Messages contain typed parts that preserve content ordering:

Part Type	Description
`text`	Text content with `text` and `status` fields
`reasoning`	Extended reasoning with `text` and `status` fields
`tool-call`	Tool execution with `toolCallId`, `toolName`, `displayName`, `args`, `result`, `status`
`operation`	Internal operations with `operationId`, `name`, `operationType`, `status`

Example

bash

Trigger Session

Execute a trigger on a session. Returns a Server-Sent Events stream.

text

Request Body

json

Field	Type	Required	Description
`triggerName`	string	Yes	Name of the trigger to execute
`input`	object	No	Input variables for the trigger
`toolResults`	array	No	Tool results for continuation (handled by SDK)

Response

Returns text/event-stream with SSE events:

text

Event Types

Event	Description
`start`	Stream started
`finish`	Execution complete
`error`	Error occurred
`block-start`	Execution block started
`block-end`	Execution block completed
`text-start`	Text generation started
`text-delta`	Incremental text content
`text-end`	Text generation ended
`reasoning-start`	Extended reasoning started
`reasoning-delta`	Reasoning content
`reasoning-end`	Extended reasoning ended
`tool-input-start`	Tool call initiated
`tool-input-delta`	Tool arguments streaming
`tool-input-end`	Tool arguments streaming ended
`tool-input-available`	Tool input complete
`tool-output-available`	Tool completed with result
`tool-output-error`	Tool failed
`tool-request`	Platform requesting tool execution
`resource-update`	Resource value changed

Example

bash

Tool Continuation

When the agent calls external tools, you'll receive a tool-request event. Execute the tools and send results back:

json

The Server SDK handles this continuation pattern automatically.