Sessions
MCP tools for the Sessions module. See the Sessions module docs for permissions and data model.
create-session
Create a session
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
agent_id | string | yes | Agent this session belongs to. With a credential scoped to a project, it may also be an agent another project shares with that project; the session is then that project's. |
name | string | no | Optional session name |
tags | any | no | Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with 400 VALIDATION_FAILED, never coerced. Keys are opaque and stored verbatim, so cost_center and costCenter are two different tags. Matched by JSONB containment wherever tags are read: the ?tags= filter, knowledge search, and the IAM soat:ResourceTag/<key> condition. Keys beginning system. are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with 400 RESERVED_TAG_KEY. They are read and filtered like any other tag. The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is 400 VALIDATION_FAILED with meta.limit naming the bound it crossed. system.* keys are the platform's and do not count against the 50. |
actor_id | string | no | Optional public ID of an existing actor to use as the user actor. Actors are created separately (POST /actors); this field only links one. Omit it and the session has no end user, so its generations match no actor-scoped quota. |
auto_generate | boolean | no | When true, automatically triggers generation after each user message. |
tool_context | object | null | no | Key-value pairs forwarded as X-Soat-Context-<key> headers on every http, mcp and builtin tool call in this session. The header name is the deployment's configured context prefix (X-Soat-Context- by default) plus the key verbatim — no character is re-cased. Keys are stored exactly as sent and never case-converted. A key that is not a valid HTTP header name, or two keys that map to the same header, are rejected with 400 INVALID_TOOL_CONTEXT_KEY. session_id, actor_id and actor_external_id are server-derived and dropped from the stored bag, in any casing. Write-only: no read of a session returns it. It also does not outlive the session: closing or expiring it clears the bag. |
inactivity_ttl_seconds | number | no | Number of seconds of inactivity after which the session expires. 0 means the session never expires. |
message_delay_seconds | number | null | no | Number of seconds to wait after the last user message before sending to the LLM. Acts as a debounce: each new message resets the timer. null or absent means no delay (immediate processing). |
list-sessions
List sessions
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
project_id | string | no | Filter by project public ID. Required for soat:ResourceTag policy conditions to narrow the listing: a policy is read per project, so without it the listing is scoped to the projects the caller can access and nothing further. |
agent_id | string | no | Filter by agent public ID |
actor_id | string | no | Filter by actor public ID |
status | string | no | Filter by session status (open, closed, or expired) |
tags | array | no | Filter by tag pairs, written key:value (split on the first colon, so a value may contain colons). Repeat the parameter for several pairs; all must be present with exactly that value. |
limit | number | no | Results per page. Above the maximum it is clamped, and limit in the response reports the page served; below 1 or not an integer it is 400 VALIDATION_FAILED. |
offset | number | no | Results to skip. Negative or not an integer it is 400 VALIDATION_FAILED. |
get-session
Get a session
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
session_id | string | yes | Session public ID |
update-session
Update a session
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
session_id | string | yes | Session public ID |
name | string | null | no | Session name (set to null to clear) |
status | string | no | Session status |
auto_generate | boolean | no | Enable or disable automatic generation after user messages. |
tool_context | object | null | no | Key-value pairs forwarded as X-Soat-Context-<key> headers on every http, mcp and builtin tool call in this session. The header name is the deployment's configured context prefix (X-Soat-Context- by default) plus the key verbatim — no character is re-cased. Keys are stored exactly as sent and never case-converted. A key that is not a valid HTTP header name, or two keys that map to the same header, are rejected with 400 INVALID_TOOL_CONTEXT_KEY. session_id, actor_id and actor_external_id are server-derived and dropped from the stored bag, in any casing. Write-only: no read of a session returns it. It also does not outlive the session: closing or expiring it clears the bag. |
inactivity_ttl_seconds | number | no | Number of seconds of inactivity after which the session expires. 0 means the session never expires. Updates the stored TTL; the inactivity clock continues from the last activity timestamp. |
message_delay_seconds | number | null | no | Number of seconds to wait after the last user message before sending to the LLM. Acts as a debounce: each new message resets the timer. Set to null to disable the delay. |
delete-session
Delete a session
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
session_id | string | yes | Session public ID |
add-session-message
Add a user message
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
session_id | string | yes | Session public ID |
message | string | no | User message text |
tool_context | object | null | no | Key-value pairs forwarded as X-Soat-Context-<key> headers on every http, mcp and builtin tool call in this generation. The header name is the deployment's configured context prefix (X-Soat-Context- by default) plus the key verbatim — no character is re-cased. Keys are never case-converted — they round-trip exactly as sent. An invalid or colliding key is rejected with 400 INVALID_TOOL_CONTEXT_KEY. |
idempotency_key | string | no | Optional deduplication key scoped to this session. If a message with the same key already exists in the session, the original message is returned with HTTP 200 and no new message or generation is triggered. Reusing the key with a different message, document_id or tool_context is 409 IDEMPOTENCY_KEY_REUSED. |
document_id | string | no | Public ID of a document used as the user message content. |
generate-session-response
Trigger agent generation
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
session_id | string | yes | Session public ID |
model | string | no | Optional model override |
tool_context | object | null | no | Key-value pairs forwarded as X-Soat-Context-<key> headers on every http, mcp and builtin tool call in this generation. The header name is the deployment's configured context prefix (X-Soat-Context- by default) plus the key verbatim — no character is re-cased. Keys are never case-converted — they round-trip exactly as sent. An invalid or colliding key is rejected with 400 INVALID_TOOL_CONTEXT_KEY. |
submit-session-tool-outputs
Submit tool outputs
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
session_id | string | yes | Session public ID |
generation_id | string | yes | The generation ID from the requires_action response |
tool_outputs | array<object> | yes | — |
fork-session
Fork a session
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
session_id | string | yes | Session public ID |
fork_at_position | number | no | The parent conversation position to branch after. Messages at positions 0..N are carried into the fork. Omit it to branch at the tip (the whole history). |
agent_id | string | no | Agent the fork runs against. Defaults to the parent session's agent; overriding it is the point of forking — same context, a different agent or agent version. Must belong to the same project as the session being forked. |
name | string | no | Optional name for the forked session |
tags | any | no | Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with 400 VALIDATION_FAILED, never coerced. Keys are opaque and stored verbatim, so cost_center and costCenter are two different tags. Matched by JSONB containment wherever tags are read: the ?tags= filter, knowledge search, and the IAM soat:ResourceTag/<key> condition. Keys beginning system. are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with 400 RESERVED_TAG_KEY. They are read and filtered like any other tag. The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is 400 VALIDATION_FAILED with meta.limit naming the bound it crossed. system.* keys are the platform's and do not count against the 50. |
tool_context | object | null | no | Overrides the parent's tool_context on the fork. Omit it and the fork inherits the parent's, so the branch is faithful to the run it came from. |
list-session-forks
List a session's forks
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
session_id | string | yes | Session public ID |
limit | number | no | Results per page. Above the maximum it is clamped, and limit in the response reports the page served; below 1 or not an integer it is 400 VALIDATION_FAILED. |
offset | number | no | Results to skip. Negative or not an integer it is 400 VALIDATION_FAILED. |
get-session-tags
Get session tags
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
session_id | string | yes | Session public ID |
replace-session-tags
Replace session tags
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
session_id | string | yes | Session public ID |
merge-session-tags
Merge session tags
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
session_id | string | yes | Session public ID |