Start a session

A session is an agent instance within an environment. Each session references an agent and an environment (both created separately), and maintains conversation history across multiple interactions. Sessions follow a two-step lifecycle: first create the session to provision its container, then send a user event to start work.

Creating a session

A session requires an agent ID and an environment ID. Agents are versioned resources; passing in the agent ID as a string starts the session with the latest agent version.

ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID"

To pin a session to a specific agent version, pass an object. This lets you control exactly which version runs and stage rollouts of new versions independently.

ant beta:sessions create <<YAML
agent:
  type: agent
  id: $AGENT_ID
  version: 1
environment_id: $ENVIRONMENT_ID
YAML

MCP authentication through vaults

If your agent uses MCP tools that require authentication, pass vault_ids at session creation to reference a vault containing stored OAuth credentials. Anthropic manages token refresh on your behalf. See Authenticate with vaults for how to create vaults and register credentials.

ant beta:sessions create <<YAML
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
vault_ids:
  - $VAULT_ID
YAML

Starting the session

Creating a session provisions the environment's container but does not start any work. To delegate a task, send events to the session using a user event. The session acts as a state machine that tracks progress while events drive the actual execution.

ant beta:sessions:events send \
  --session-id "$SESSION_ID" <<'YAML'
events:
  - type: user.message
    content:
      - type: text
        text: List the files in the working directory.
YAML

See Session event stream for how to stream the agent's responses and handle tool confirmations.

Session statuses

Sessions progress through these statuses:

Other session operations

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:

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

Deleting a session

Delete a session to permanently remove its record, events, and associated container. 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"