Session operations

Once a session exists, use these operations to read, update, archive, or delete it. See Start a session for creating a session and sending it work.

Session statuses

Sessions progress through these statuses. See Start a session for the session lifecycle.

Updating the agent configuration

You can update a session's agent.tools and agent.mcp_servers, including permission policies, mid-session without creating a new agent version. Updates are session-local and do not propagate back to the underlying agent.

The semantics of an update are full replacement: the provided array is the new value. To preserve existing entries, GET the session, modify the array, and POST it back.

The session must be idle to update the agent. Interrupt the session if you need to update the agent while it's running.

ant beta:sessions update --session-id "$SESSION_ID" <<'YAML'
agent:
  tools:
    - type: agent_toolset_20260401
    - type: mcp_toolset
      mcp_server_name: linear
  mcp_servers:
    - type: url
      name: linear
      url: https://mcp.linear.app/sse
YAML

Retrieving a session

ant beta:sessions retrieve --session-id "$SESSION_ID"

Listing sessions

ant beta:sessions list --agent-id "$AGENT_ID"

Archiving a session

Archive a session to prevent new events from being sent while preserving its history. A running session cannot be archived; send an interrupt event if you need to archive it immediately.

ant beta:sessions archive \
  --session-id "$SESSION_ID"

Deleting a session

Delete a session to permanently remove its record, events, and associated sandbox. A running session cannot be deleted; send an interrupt event if you need to delete it immediately.

Files, memory stores, vaults, skills, environments, and agents are independent resources and are not affected by session deletion.

ant beta:sessions delete \
  --session-id "$SESSION_ID"