Anthropic Managed Agents

Troubleshooting

If requests fail, run zero doctor check-connector --env-name ANTHROPIC_MANAGED_AGENTS_TOKEN or zero doctor check-connector --url https://api.anthropic.com/v1/agents --method POST

How to Use

All examples assume ANTHROPIC_MANAGED_AGENTS_TOKEN is set. The base URL is https://api.anthropic.com.

1. Create an Agent

An agent is a reusable configuration (model + system prompt + toolset). Create it once; use it across many sessions.

Write to /tmp/agent_create.json:

{
  "model": "claude-sonnet-4-6",
  "name": "Code Review Agent",
  "description": "Reviews pull requests and suggests improvements",
  "system": "You are an expert code reviewer. Analyze the code in the mounted repository, identify issues, and provide actionable feedback.",
  "tools": [
    {
      "type": "agent_toolset_20260401"
    }
  ]
}

Then run:

curl -s -X POST "https://api.anthropic.com/v1/agents" \
  -H "x-api-key: $ANTHROPIC_MANAGED_AGENTS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "Content-Type: application/json" \
  -d @/tmp/agent_create.json | jq '{id: .id, name: .name}'

Save the returned id (e.g., agent_011CZk...) for use in sessions.

Built-in tools in `agent_toolset_20260401`: bash, edit, read, write, glob, grep, web_fetch, web_search

Available models: claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5

2. List Agents

curl -s "https://api.anthropic.com/v1/agents" \
  -H "x-api-key: $ANTHROPIC_MANAGED_AGENTS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" | jq '.data[] | {id: .id, name: .name, model: .model}'

3. Get an Agent

curl -s "https://api.anthropic.com/v1/agents/<AGENT_ID>" \
  -H "x-api-key: $ANTHROPIC_MANAGED_AGENTS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" | jq '.'

4. Delete an Agent

DELETE is served by an older beta API and requires a different anthropic-beta header than the other endpoints. Use agent-api-2026-03-01 alone — combining it with managed-agents-2026-04-01 is rejected as incompatible.

curl -s -X DELETE "https://api.anthropic.com/v1/agents/<AGENT_ID>" \
  -H "x-api-key: $ANTHROPIC_MANAGED_AGENTS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: agent-api-2026-03-01"

5. Create an Environment

An environment defines the container configuration (network policy, packages) that sessions run in. Create once, reuse across sessions.

Write to /tmp/env_create.json:

{
  "name": "Default Cloud Environment",
  "description": "Standard environment with unrestricted network access",
  "config": {
    "type": "cloud",
    "networking": {
      "type": "unrestricted"
    },
    "packages": {
      "pip": ["requests", "pandas"],
      "npm": ["typescript"]
    }
  }
}

Then run:

curl -s -X POST "https://api.anthropic.com/v1/environments" \
  -H "x-api-key: $ANTHROPIC_MANAGED_AGENTS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "Content-Type: application/json" \
  -d @/tmp/env_create.json | jq '{id: .id, name: .name}'

Save the returned id (e.g., env_011...) for session creation.

Network options:

• {"type": "unrestricted"} — full internet access
• {"type": "limited", "allow_package_managers": true, "allow_mcp_servers": true, "allowed_hosts": ["api.github.com"]} — restricted outbound

6. Create a Session (Start a Task)

A session runs one task: it mounts resources (repos, files), runs the agent, and produces output. Each session is a separate container.

Write to /tmp/session_create.json:

{
  "agent": "agent_011CZk...",
  "environment_id": "env_011...",
  "title": "Review PR #42",
  "resources": [
    {
      "type": "github_repository",
      "url": "https://github.com/your-org/your-repo",
      "authorization_token": "ghp_xxx",
      "checkout": {
        "type": "branch",
        "name": "feature/your-branch"
      }
    }
  ]
}

Then run:

curl -s -X POST "https://api.anthropic.com/v1/sessions" \
  -H "x-api-key: $ANTHROPIC_MANAGED_AGENTS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "Content-Type: application/json" \
  -d @/tmp/session_create.json | jq '{id: .id, status: .status}'

Resource types:

• github_repository — mounts a GitHub repo; requires url, authorization_token (GitHub PAT), and optional checkout (branch or commit SHA). Defaults to repo's default branch.
• file — mounts a file uploaded via the Files API; requires file_id.

Checkout options:

• {"type": "branch", "name": "main"}
• {"type": "commit", "sha": "abc123..."}

With Vault secrets:

{
  "agent": "agent_011CZk...",
  "environment_id": "env_011...",
  "resources": [...],
  "vault_ids": ["vault_abc..."]
}

7. Stream Session Events

Stream real-time SSE events from a running session. The stream stays open until the session completes.

curl -s "https://api.anthropic.com/v1/sessions/<SESSION_ID>/events/stream" \
  -H "x-api-key: $ANTHROPIC_MANAGED_AGENTS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "Accept: text/event-stream"

Events are Server-Sent Events (SSE). Each event has a type field:

• agent.message — agent text output
• agent.tool_use — tool invocation (bash command, file read, etc.)
• agent.tool_result — tool output
• agent.thinking — extended thinking progress signal
• agent.mcp_tool_use — MCP tool invocation
• agent.mcp_tool_result — MCP tool output

Parse agent message text output only:

curl -s "https://api.anthropic.com/v1/sessions/<SESSION_ID>/events/stream" \
  -H "x-api-key: $ANTHROPIC_MANAGED_AGENTS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "Accept: text/event-stream" | grep '^data:' | python3 -c "
import sys, json
for line in sys.stdin:
    line = line.strip()
    if line.startswith('data: '):
        try:
            ev = json.loads(line[6:])
            # agent.message events contain content blocks with text
            if ev.get('type') == 'agent.message':
                for block in ev.get('content', []):
                    if block.get('type') == 'text':
                        print(block.get('text', ''), end='', flush=True)
        except:
            pass
"

7b. Send Events to a Session (Follow-up Messages)

While a session is idle (waiting), send follow-up messages or tool results:

curl -s -X POST "https://api.anthropic.com/v1/sessions/<SESSION_ID>/events" \
  -H "x-api-key: $ANTHROPIC_MANAGED_AGENTS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.message",
        "content": [{"type": "text", "text": "Now focus on the security implications."}]
      }
    ]
  }'

7c. List Past Events

Replay all events from a completed or running session:

curl -s "https://api.anthropic.com/v1/sessions/<SESSION_ID>/events" \
  -H "x-api-key: $ANTHROPIC_MANAGED_AGENTS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" | jq '.data[] | {type: .type, id: .id}'

8. Get Session Status

curl -s "https://api.anthropic.com/v1/sessions/<SESSION_ID>" \
  -H "x-api-key: $ANTHROPIC_MANAGED_AGENTS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" | jq '{id: .id, status: .status, title: .title}'

Session statuses: running, idle, terminated

9. List Sessions

# List all sessions for an agent
curl -s "https://api.anthropic.com/v1/sessions?agent_id=<AGENT_ID>&limit=10" \
  -H "x-api-key: $ANTHROPIC_MANAGED_AGENTS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" | jq '.data[] | {id: .id, status: .status, title: .title}'

Supports filters: agent_id, agent_version, created_at[gt/gte/lt/lte], include_archived, order (asc/desc), limit, page.

10. Full End-to-End Example: Code Review Workflow

# Step 1: Create agent (one-time setup)
AGENT_ID=$(curl -s -X POST "https://api.anthropic.com/v1/agents" \
  -H "x-api-key: $ANTHROPIC_MANAGED_AGENTS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "name": "Code Reviewer",
    "system": "Review the code changes in the repository and provide detailed feedback on correctness, style, and potential issues.",
    "tools": [{"type": "agent_toolset_20260401"}]
  }' | jq -r '.id')
echo "Agent: $AGENT_ID"

# Step 2: Create environment (one-time setup)
ENV_ID=$(curl -s -X POST "https://api.anthropic.com/v1/environments" \
  -H "x-api-key: $ANTHROPIC_MANAGED_AGENTS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{"name": "Default", "config": {"type": "cloud", "networking": {"type": "unrestricted"}}}' | jq -r '.id')
echo "Environment: $ENV_ID"

# Step 3: Start a session for this PR review task
SESSION_ID=$(curl -s -X POST "https://api.anthropic.com/v1/sessions" \
  -H "x-api-key: $ANTHROPIC_MANAGED_AGENTS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "Content-Type: application/json" \
  -d "{
    \"agent\": \"$AGENT_ID\",
    \"environment_id\": \"$ENV_ID\",
    \"title\": \"Code Review\",
    \"resources\": [{
      \"type\": \"github_repository\",
      \"url\": \"https://github.com/your-org/your-repo\",
      \"authorization_token\": \"$GITHUB_TOKEN\",
      \"checkout\": {\"type\": \"branch\", \"name\": \"feature/my-feature\"}
    }]
  }" | jq -r '.id')
echo "Session: $SESSION_ID"

# Step 4: Stream the output until complete
curl -s "https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream" \
  -H "x-api-key: $ANTHROPIC_MANAGED_AGENTS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "Accept: text/event-stream" | grep '^data:' | python3 -c "
import sys, json
for line in sys.stdin:
    line = line.strip()
    if line.startswith('data: '):
        try:
            ev = json.loads(line[6:])
            t = ev.get('type', '')
            if t == 'text':
                print(ev.get('text', ''), end='', flush=True)
            elif t == 'status_change':
                print(f\"\n[Status: {ev.get('status')}]\", flush=True)
        except:
            pass
"

Guidelines

1. Agent lifecycle: Create an agent once; reuse its ID for all sessions. Agents are versioned — each update increments the version. 2. Environment lifecycle: Create an environment once per container config. Reference the same env_id across many sessions. 3. Sessions are single-use: Each session runs one task in an isolated container. For follow-up questions, create a new session. 4. Stream before polling: Use the SSE stream (/events/stream) to get real-time output. Only fall back to GET /v1/sessions/{id} for status checks after the stream closes. 5. GitHub auth: Pass a GitHub PAT with repo scope as authorization_token in repository resources. The token is used only for that session. 6. Vaults for secrets: Store long-lived credentials (API keys, tokens) in a Vault and pass vault_ids instead of embedding secrets in session payloads. 7. Model selection: Use claude-sonnet-4-6 for most coding tasks (speed + quality balance). Use claude-opus-4-6 for complex multi-file refactors. 8. Beta header required: Most Managed Agents endpoints require anthropic-beta: managed-agents-2026-04-01. The sole exception is DELETE /v1/agents/{id}, which requires agent-api-2026-03-01 instead — the two beta values are mutually exclusive and cannot be combined in one request. 9. Billing: Sessions consume Claude API credits (tokens), not claude.ai subscription quota. Monitor usage in Claude Console.