Sessions

Agents keep internal state during a conversation, for example the results of tool calls. The service can store this state, so that the next request continues exactly where the last one ended. Without stored state, the service has to rebuild the context from the message history on every request.

Required fields

Field	Where	Description
id	On every message	A stable ID. Keep the same ID for a message in all later requests.
metadata.chat_id	Request	Identifies the conversation. Generate it once when the conversation starts.
metadata.message_id	Request	ID of the assistant answer that this request will produce. Generate a new one for every request.
metadata.user_id	Request	Identifies the user. If missing, the user from the access token is used.

Use UUIDs or another collision-resistant format for all IDs.

How it works

sequenceDiagram
    participant App as Your application
    participant RT as Agent Runtime
    App->>RT: messages [u1], message_id = a1
    RT-->>App: answer a1 (state stored under a1)
    App->>RT: messages [u1, a1, u2], message_id = a2
    Note over RT: Finds the last assistant message (a1)<br/>and loads its stored state
    RT-->>App: answer a2 (state stored under a2)

1. The service looks for the latest assistant message with an id in messages.
2. It loads the state stored for that message, conversation and user.
3. After answering, it stores the new state under metadata.message_id.

When you send the next request, include the previous answer as an assistant message whose id is the message_id you sent before.

Example

{
  "model": "support-assistant.agent.support-assistant-agent",
  "messages": [
    { "id": "msg-001", "role": "user", "content": "The packaging line camera is drifting." },
    { "id": "msg-002", "role": "assistant", "content": "Please confirm the camera model and when the drift started." },
    { "id": "msg-003", "role": "user", "content": "Model CAM-45, drift started after maintenance this morning." }
  ],
  "stream": true,
  "metadata": {
    "chat_id": "conv-abc-123",
    "message_id": "msg-004",
    "user_id": "john.doe"
  }
}

Without session fields

If the fields are missing, the conversation still works. The service then rebuilds the context from the full message history, which becomes less efficient as the conversation grows.

How long state is kept

Stored state expires 8 days after it was stored. After that, the service rebuilds the context from the message history.

Delete stored state

POST ${RUNTIME_BASE_URL}/clear_sessions
Content-Type: application/json

{
  "tenant_id": "${TENANT_ID}",
  "user_id": "${USER_ID}",
  "chat_id": "${CHAT_ID}"
}

• If chat_id is omitted, all stored state of the user is deleted.
• tenant_id must match the X-Tenant-ID header.
• The response contains success and deleted_count.

Call this endpoint when a user deletes a conversation in your application.