anthropic-managed-agents

What this skill does

## 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" \
  -