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 |
name | string | no | Optional session name |
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 never case-converted — they round-trip exactly as sent. 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. |
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 |
|---|---|---|---|
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) |
limit | number | no | — |
offset | number | no | — |
get-session
Get a session
Arguments
This tool takes no arguments.
update-session
Update a session
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
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 never case-converted — they round-trip exactly as sent. 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. |
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
This tool takes no arguments.
add-session-message
Add a user message
Arguments
This tool takes no arguments.
generate-session-response
Trigger agent generation
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
wait | boolean | no | When omitted or false (default), generation runs in the background and 202 Accepted is returned immediately. Pass true to block until the generation settles and receive the result. |
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 |
|---|---|---|---|
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 |
|---|---|---|---|
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 | object | no | Optional tags for the forked session |
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 |
|---|---|---|---|
limit | number | no | — |
offset | number | no | — |
get-session-tags
Get session tags
Arguments
This tool takes no arguments.
replace-session-tags
Replace session tags
Arguments
This tool takes no arguments.
merge-session-tags
Merge session tags
Arguments
This tool takes no arguments.