managed-agents-api

---
name: managed-agents-api
description: |
  Use Claude Managed Agents (beta), where Anthropic runs the agent loop and a per-session sandbox: create a versioned agent once, an environment, then sessions that you drive with events over SSE. Covers the correct object model, tool permission policies, custom tools, outcomes, session budgets, data-retention limits, and when to choose it over the Agent SDK.
  Use this skill when building hosted, long-running, or scheduled agents on the Claude API, deciding between Managed Agents and the Agent SDK, or fixing code that puts model or tools on the session or calls agents.create on every run.
  Activate when: Managed Agents, Claude Managed Agents, /v1/agents, /v1/sessions, /v1/environments, client.beta.agents, client.beta.sessions, sessions.events.stream, agent_toolset, server-side agent.
---

# Managed Agents API

**Managed Agents is a hosted agent harness: you define an agent (model, system prompt, tools) once, start sessions against it in an environment, and exchange events. Anthropic runs the loop and the sandbox where tools execute.**

## When to Use

- Long-running or asynchronous tasks (minutes to hours, many tool calls)
- You want a sandbox with bash and file tools without operating one
- Persisted, versioned agent configurations shared across many runs
- Scheduled runs (the platform supports scheduled deployments)

## When NOT to Use

- You need zero data retention or HIPAA BAA coverage: the docs list Managed Agents as not eligible (sessions persist until you delete them)
- You are on a cloud platform where it is not offered; check the availability table
- A single request or a short tool loop you control is enough: use the Messages API
- You want Claude Code's harness inside your own process: use the Agent SDK

## Workflow

### Step 1: Understand the object model

| Object | Holds | Created |
|--------|-------|---------|
| Agent | Model, system prompt, tools, MCP servers, skills; versioned | Once, then updated |
| Environment | Where sessions run (cloud sandbox or self-hosted) | Once per configuration |
| Session | One running agent instance and its history | Every run |
| Events | User messages, tool results, status updates | Continuously |

Model, system prompt, and tools live on the agent, never on the session. The session takes a pointer to an agent (and optionally a pinned version). All endpoints are beta and need the `managed-agents-2026-04-01` header, which the official SDKs set automatically on `client.beta.*` calls.

### Step 2: Create the environment and agent in setup code

```ts
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const MODEL = process.env.ANTHROPIC_MODEL!; // a current model ID

const environment = await client.beta.environments.create({
  name: "dev-env",
  config: { type: "cloud", networking: { type: "limited", allow_package_managers: true, allow_mcp_servers: true } },
});

const agent = await client.beta.agents.create({
  name: "Code Reviewer",
  model: MODEL,
  system: "You are a senior code reviewer.",
  tools: [{
    type: "agent_toolset_20260401",
    default_config: { enabled: true, permission_policy: { type: "auto" } },
    configs: [{ name: "web_fetch", enabled: false }, { name: "web_search", enabled: false }],
  }],
});
// Persist environment.id, agent.id and agent.version; do not create these per request.
```

To change behavior later, update the agent (`client.beta.agents.update`); each update creates a new version, and running sessions keep the version they started with. The Anthropic docs also describe keeping agents as version-controlled files synced with the `ant` CLI.

### Step 3: Start a session and stream events

Open the stream before (or concurrently with) sending the first message; the stream only delivers events that occur after it opens.

```ts
const session = await client.beta.sessions.create({
  agent: { type: "agent", id: AGENT_ID, version: AGENT_VERSION },
  environment_id: ENVIRONMENT_ID,
  title: "Review auth module",
});

const stream = await client.beta.sessions.events.stream(session.id);
await client.beta.sessions.events.send(session.id, {
  events: [{ type: "user.message", content: [{ type: "text", text: "Review the auth module" }] }],
});

for await (const event of stream) {
  if (event.type === "agent.message") {
    for (const block of event.content) if (block.type === "text") process.stdout.write(block.text);
  } else if (event.type === "session.status_idle") {
    if (event.stop_reason.type !== "requires_action") break; // otherwise it is waiting on you
  } else if (event.type === "session.status_terminated") {
    break;
  }
}
```

Session statuses are `idle`, `running`, `rescheduling`, and `terminated`. `terminated` means the session is over, either completed or failed; retrieve the session to tell which. Errors arrive as `session.error` events, not as a status.

### Step 4: Answer tool confirmations and custom tools

- Tool calls whose permission evaluates to `ask` pause the session. Reply with a `user.tool_confirmation` event (`result: "allow"` or `"deny"`). When nobody is watching, deny rather than allowing everything
- Custom tools you defined on the agent (`type: "custom"`) arrive as `agent.custom_tool_use`; reply with `user.custom_tool_result`
- Keep secrets out of the sandbox: the docs describe vault credentials substituted at egress, with host-side custom tools as the fallback

### Step 5: Choose a kickoff: message or outcome

For conversational sessions send `user.message`. For deliverables (a report, a PR, a fixed set of changes), the docs describe `user.define_outcome` with a rubric: a grader evaluates each iteration and the agent revises until it passes or hits `max_iterations`. Send one or the other as the kickoff, not both.

### Step 6: Bound cost

Sessions accept an optional `budget` at creation: `{ type: "limit", max_list_cost: { amount: "2500", currency: "USD" } }`, where the amount is an integer string in cents. At the cap the session goes `idle` with `stop_reason` `budget_reached`; changing or removing the budget resumes it. A budget cannot be added after creation. List cost is priced at public list rates, which may differ from your contracted price; check the pricing page for what counts.

### Step 7: Manage session records

Available operations include `sessions.retrieve`, `list`, `update` (title, metadata, session-local tool overrides while idle, budget), `archive`, and `delete`. There is no session fork in Managed Agents. Delete sessions and uploaded files you no longer need, since transcripts persist until deleted.

## Managed Agents vs Agent SDK

| | Managed Agents | Agent SDK |
|--|----------------|-----------|
| Who runs the loop | Anthropic | Your process |
| Where tools execute | Per-session sandbox (cloud or self-hosted) | Your machine or container |
| Configuration | Versioned agent objects via API | Options per `query()` call |
| State | Server-side sessions and events | Local session transcripts |

## Best Practices

1. Create agents and environments in setup code or config files, never on the request path
2. Pin the agent version on sessions you need to reproduce
3. Open the event stream before sending events
4. Handle `requires_action` pauses explicitly and deny by default when unattended
5. Disable web tools unless the job needs them; restrict domains when it does
6. Set a session budget on unattended runs
7. Delete sessions and files under your retention policy

## References

- Managed Agents overview: https://platform.claude.com/docs/en/managed-agents/overview
- Quickstart: https://platform.claude.com/docs/en/managed-agents/quickstart
- Sessions: https://platform.claude.com/docs/en/managed-agents/sessions
- Reference (events, limits): https://platform.claude.com/docs/en/managed-agents/reference
- Tools: https://platform.claude.com/docs/en/managed-agents/tools
- Agent SDK comparison: https://code.claude.com/docs/en/agent-sdk/overview