v2

OpenAPI 3.0.02026-08-051996591.2 MB

Agent Sessions

Update agent session

Updates the configuration of an existing agent session. You can modify fields such as the name, description, or metadata.

Updated metadata immediately influences agent behavior. It becomes available to instructions and tools for the remainder of the session. For more details about configuring the agent session, see Create agent session.

patch/v2/agents/{agent_key}/sessions/{session_key}

Path parameters

agent_keystring required

A unique key that identifies an agent.

Example:customer_support

The unique identifier of the agent.

session_keystring required

A unique key that identifies an agent session.

Example:customer_support_chat

The unique key of the session to update.

Headers

Request-Timeoutinteger

The platform makes a best effort to complete the request in the specified seconds, or it times out.

Request-Timeout-Millisinteger

The platform makes a best effort to complete the request in the specified milliseconds, or it times out.

Request body

namestring

Human-readable name for the session.

descriptionstring

A short description of the session's purpose. Pass an empty string to suppress auto-generation.

metadataobject

Arbitrary metadata associated with the session.

enabledboolean

Whether the session is enabled.

tti_minutesinteger

Time-to-idle in minutes for the session. If no events occur in the session for this duration, the session is deleted automatically. If set to 0, the session does not expire.

secretsobject

Patch the session's secrets. Names present in the map are added or replaced; names absent from the map are left unchanged. A name mapped to null is removed. Values are encrypted at rest with the owning agent's encryption key and returned masked on reads.

Example request

{
  "name": "Updated Session Name",
  "description": "Updated session description",
  "metadata": {
    "customer_id": "12345",
    "priority": "high",
    "status": "escalated"
  },
  "tti_minutes": 60,
  "secrets": {
    "slack_user_token": "xoxp-rotated-token",
    "old_token_to_remove": null
  }
}

Response

The updated agent session.

keystring required

A unique key that identifies an agent session.

agent_keystring required

A unique key that identifies an agent.

namestring required

Human-readable name for the session.

descriptionstring

A short description of the session's purpose. If omitted at creation, the platform generates one after the agent produces events. An empty string indicates auto-generation is disabled for this session.

metadataobject

Arbitrary metadata associated with the session.

current_step_namestring nullable

The step name the session will resume at on the next user message. If null, the session starts at the agent's first_step.

enabledboolean required

Whether the session is currently active and can accept new messages.

status'unstarted' | 'running' | 'stopped'

Lifecycle status of the session. unstarted before the session receives any event, running while the agent is producing events, and stopped when the session is idle with no event in flight. stopped implies no terminating action — the session returns to running on the next request.

created_by_agent_keystring

A unique key that identifies an agent.

created_by_session_keystring

A unique key that identifies an agent session.

tti_minutesinteger

Time-to-idle in minutes for the session. If no events occur in the session for this duration, the session is deleted automatically. If not specified, the session does not expire.

created_atstring date-time required

Timestamp when the session was created.

alias_keystring nullable

If this session was created through an alias (POST /v2/agent_aliases/{alias_key}/sessions), the alias key the caller used. The agent_key field above is the resolved agent the alias's policy picked. Null when the session was created directly under an agent (POST /v2/agents/{agent_key}/sessions).

secretsobject

Session-scoped secrets, with values masked as "****". Plaintext is never returned on read; tools resolve the real value via argument_override with {"$ref": "session.secrets.<name>"}. Set or rotate via the session create or update request.

Example response

{
  "key": "customer_support_chat",
  "agent_key": "customer_support",
  "name": "Customer Support Session",
  "description": "Helping customer troubleshoot widget installation issues",
  "metadata": {
    "customer_id": "12345",
    "priority": "high",
    "channel": "web_chat"
  },
  "current_step_name": "billing",
  "enabled": true,
  "status": "stopped",
  "created_by_agent_key": "customer_support",
  "created_by_session_key": "customer_support_chat",
  "tti_minutes": 60,
  "created_at": "2024-01-15T10:30:00Z",
  "session_context_usage": {
    "input_tokens": {
      "count": 120,
      "cached_tokens": 100
    },
    "output_tokens": {
      "count": 30
    },
    "total_tokens": 150,
    "model_context_window": 200000
  },
  "effective_compaction": {
    "enabled": true,
    "threshold_percent": 80,
    "keep_recent_inputs": 1
  },
  "alias_key": "support",
  "secrets": {
    "slack_user_token": "****"
  }
}