/claude-api

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

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: "claude-opus-4-7",
    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",
  },
);

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.

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,
)