anthropic-managed-agents

---
name: anthropic-managed-agents
description: Anthropic Managed Agents API for programmatically creating, running, and streaming AI agents on Anthropic's cloud infrastructure. Use when the user mentions "Managed Agents", "Anthropic agent sessions", or needs to create/run/stream an Anthropic agent with tool use (bash, git, web), attach GitHub repositories, or inject secrets via Vault. Do NOT use for standard Claude Messages API — use the Claude API skill instead.
---

## 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`:

```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:

```bash
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

```bash
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

```bash
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.

```bash
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`:

```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:

```bash
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`:

```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:

```bash
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:**
```json
{
  "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.

```bash
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:

```bash
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:

```bash
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:

```bash
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

```bash
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

```bash
# 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

```bash
# 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](https://console.anthropic.com/).