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, then send a user event to start work. You can also collapse both steps into one call with initial_events.



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 creates 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



Seed the session with initial events

You can create a session and start its work in one call. initial_events is an optional array of initial events to send to the session at creation, processed in order. It supports user.message and user.define_outcome events, and accepts a maximum of 50 events. A non-empty list starts the agent loop in the same call: the session is created directly in the running status, with no further request.

The following example creates a session with a single user.message in initial_events:

SEEDED_SESSION_ID=$(ant beta:sessions create \
  --transform id --raw-output <<YAML
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
initial_events:
  - type: user.message
    content:
      - type: text
        text: List the files in the working directory.
YAML
)

# initial_events aren't echoed on the create response; list the session's
# events to see the seeded message.
echo "Seeded event: $(ant beta:sessions:events list \
  --session-id "$SEEDED_SESSION_ID" \
  --format raw \
  --transform 'data.#(type=="user.message").content.0.text' --raw-output)"

No other event type is accepted. Events that respond to an agent turn (user.tool_confirmation, user.tool_result, and user.custom_tool_result) aren't accepted because no agent turn exists yet, and user.interrupt isn't accepted because there is no turn to stop. Unlike initial_events on a scheduled deployment, a session's initial_events don't accept system.message.

Each event in initial_events is validated and persisted before the create response returns, in list order, with a server-assigned ID, exactly as if you had posted it to the send events endpoint immediately after creation. Per-event content rules are also the same as on that endpoint. An empty list is equivalent to omitting the field. Validation is all-or-nothing: if any event fails validation, the whole request is rejected and no session is created.

The create request is rejected in the following cases:

A user.define_outcome event in initial_events is accepted under the same conditions as sending one to an existing session; see Define outcomes.



Override agent configuration for a session

You can pass agent in three forms: an agent ID string, a pinned-version object (type: "agent"), or an overrides object. The overrides form changes parts of the agent's configuration for a single session. Use it to try a different model or grant an extra tool in one session without versioning the agent. For the overrides form, set type to agent_with_overrides and pass the agent's id and optionally a version (omit version to use the agent's latest version). Then include any of model, system, tools, mcp_servers, or skills with the values the session should use.

Each overridable field follows the same three rules:

• Omit the field: The session inherits the value from the agent version it references.
• Set the field to null, or to an empty array for list fields: The session runs with that field cleared. This rule applies in full to system and skills. There are three exceptions:
  • model is never clearable. A session always needs a model, so model: null returns a 400 agent_model_required error.
  • Clearing tools returns a 400 error when the session's effective skills is non-empty, because skills require the read tool. Otherwise, tools: null and tools: [] clear the field.
  • Clearing