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 sandbox, 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 sandbox 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.

See Session statuses for the statuses a session moves through, and Session operations for retrieving, listing, updating, archiving, and deleting sessions.