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 |
|---|---|---|---|
agentId | string | yes | Agent this session belongs to |
name | string | no | Optional session name |
actorId | 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. |
autoGenerate | boolean | no | When true, automatically triggers generation after each user message. |
toolContext | object | no | Key-value pairs forwarded as X-Soat-Context-<Key> headers on every http, mcp and soat tool call in this session. Each key's first character is uppercased and the rest is used verbatim. 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. |
inactivityTtlSeconds | number | no | Number of seconds of inactivity after which the session expires. 0 means the session never expires. |
messageDelaySeconds | number | 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 |
|---|---|---|---|
agentId | string | no | Filter by agent public ID |
actorId | 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 | no | Session name (set to null to clear) |
status | string | no | Session status |
autoGenerate | boolean | no | Enable or disable automatic generation after user messages. |
toolContext | object | no | Key-value pairs forwarded as X-Soat-Context-<Key> headers on every http, mcp and soat tool call in this session. Each key's first character is uppercased and the rest is used verbatim. 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. |
inactivityTtlSeconds | 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. |
messageDelaySeconds | number | 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 |
|---|---|---|---|
async | boolean | no | When true, generation runs in the background and 202 is returned immediately |
model | string | no | Optional model override |
toolContext | object | no | Key-value pairs forwarded as X-Soat-Context-<Key> headers on every http, mcp and soat tool call in this generation. Each key's first character is uppercased and the rest is used verbatim. 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 |
|---|---|---|---|
generationId | string | yes | The generation ID from the requires_action response |
toolOutputs | array<object> | yes | — |
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.