Data: Managed Agents core concepts

Managed Agents — Core Concepts

Architecture

Managed Agents is built around four core concepts:

                       ┌─────────────────────────────────────┐
                       │  Anthropic orchestration layer      │
Agent (config) ───────▶│  (agent loop: Claude + tool calls)  │
                       └──────────────┬──────────────────────┘
                                      │ tool calls
                                      ▼
Environment (template) ──▶ Container (tool execution workspace)
                                 │
                         Session ─┤
                                 ├── Resources (files, repos, memory stores — attached at startup)
                                 ├── Vault IDs (MCP credential references)
                                 └── Conversation (event stream in/out)

Agent creation is a prerequisite. Sessions reference a pre-created agent by ID — model/system/tools live on the agent object, never on the session. Every flow starts with POST /v1/agents.

Session Lifecycle

rescheduling → running ↔ idle → terminated

• Events can be sent when the session is running or idle. Messages are queued and processed in order.
• The agent transitions idle → running when it receives a new event, then back to idle when done.
• Errors surface as session.error events in the stream, not as a status value.

Built-in session features

• Context compaction — if you approach max context, the API automatically condenses session history to keep the interaction going
• Prompt caching — historical repeated tokens are cached, reducing processing time and cost
• Extended thinking — on by default, returned as agent.thinking events

Session operations

These are ops/inspection calls — typically made from a terminal, not application code. From the shell (see shared/anthropic-cli.md):

ant beta:sessions list --transform '{id,title,status,created_at}' --format jsonl
ant beta:sessions retrieve --session-id "$SID"
ant beta:sessions:events stream --session-id "$SID"   # watch events live
ant beta:sessions archive  --session-id "$SID"
ant beta:sessions delete   --session-id "$SID"

Sessions

A session is a running agent instance inside an environment.

Session Object

Key fields returned by the API:

Creating a session

A session is meaningless without an agent. Sessions reference a pre-created agent by ID. Create the agent first via agents.create(), then reference it:

// 1. Create the agent (reusable, versioned)
const agent = await client.beta.agents.create(
  {
    name: "Coding Assistant",
    model: "{{OPUS_ID}}",
    system: "You are a helpful coding agent.",
    tools: [{ type: "agent_toolset_20260401"}],
  },
);

// 2. Start a session that references it
const session = await client.beta.sessions.create(
  {
    agent: agent.id,  // string shorthand → latest version. Or: { type: "agent", id: agent.id, version: agent.version }
    environment_id: environmentId,
    title: "Hello World Session",
  },
);

💡 Watch it live in Console. While developing, print a link so you can click through to the session UI instead of parsing the event stream: https://platform.claude.com/workspaces/{workspace}/sessions/{session.id}. Use default for the workspace slug unless you created the session in a non-default workspace; the sessions list for your workspace is at https://platform.claude.com/workspaces/default/sessions. Include this print/console.log in code you generate for users who are iterating locally.

Session creation parameters:

Agent configuration fields (passed to agents.create(), not sessions.create()):

Agents

This is where every Managed Agents flow begins. The agent object is a persisted, versioned configuration — you create it once, then reference it by ID every time you start a session. No agent → no session.

Agent Object

The API is flat — model, system, tools etc. are top-level fields, not wrapped in an agent:{} sub-object.

Lifecycle: create once, run many, update in place

The agent is a persistent resource, not a per-run parameter. The intended pattern:

┌─ setup (once) ─────────┐     ┌─ runtime (every invocation) ─┐
│ agents.create()        │     │ sessions.create(             │
│   → store agent_id     │ ──→ │   agent={type:..., id: ID}   │
│     in config/env/db   │     │ )                            │
└────────────────────────┘     └──────────────────────────────┘

Anti-pattern: calling agents.create() at the top of every script run. This accumulates orphaned agent objects, pays create latency on every invocation, and defeats the versioning model. If you see agents.create() in a function that's called per-request or per-cron-tick, that's wrong — hoist it to one-time setup and persist the ID.

Recommended — define agents and environments as YAML + apply via the ant CLI. The split is CLI for the control plane, SDK for the data plane: agents and environments are relatively static resources you manage with ant (version-controlled YAML, applied from CI); sessions are dynamic and driven by your application through the SDK. See shared/anthropic-cli.md → Version-controlled Managed Agents resources for the ant beta:agents create < agent.yaml / update --version N flow. The SDK agents.create() call shown elsewhere in this doc is the in-code equivalent — use it when you need to provision programmatically, but prefer the YAML flow for anything a human maintains.

Versioning

Each POST /v1/agents/{id} (update) creates a new immutable version (numeric timestamp, e.g. 1772585501101368014). The agent's history is append-only — you can't edit a past version.

Why version:

• Reproducibility — pin a session to a known-good config: {type: "agent", id, version: 3}
• Safe iteration — update the agent without breaking sessions already running on the old version
• Rollback — if a new system prompt regresses, pin new sessions back to the prior version while you debug

version is optional. Omit it (or use the string shorthand agent="agent_abc123") to get the latest version at session-creation time. Pass it explicitly ({type: "agent", id, version: N}) to pin for reproducibility.

Getting the version to pin: agents.create() and agents.update() both return version in the response. Store it alongside agent_id. To fetch the current latest for an existing agent: GET /v1/agents/{id} → .version.

When to update vs create new: Update (POST /v1/agents/{id}) when it's conceptually the same agent with tweaked behavior (better prompt, extra tool). Create a new agent when it's a different persona/purpose. Rule of thumb: if you'd give it the same name, update.

Agent Endpoints

⚠️ Archive is permanent. Archiving makes the agent read-only: existing sessions continue to run, but new sessions cannot reference it, and there is no unarchive. Since agents have no delete, this is the terminal lifecycle state. Never archive a production agent as routine cleanup — confirm with the user first.

Using an Agent in a Session

Reference the agent by string ID (latest version) or by object with an explicit version:

# String shorthand — uses the agent's latest version
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment_id,
)

# Or pin to a specific version (int)
session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": agent.version},
    environment_id=environment_id,
)

Updating the agent configuration mid-session

sessions.update() can change agent.tools, agent.mcp_servers (including permission policies), and vault_ids on an existing session. This is a session-local override — it does not create a new agent version and does not propagate back to the agent object. The provided arrays are full replacements; to append one tool, GET the session, modify, and POST back. The session must be idle — interrupt first if running.

client.beta.sessions.update(
    session.id,
    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"}],
    },
    vault_ids=["vlt_..."],
)