claude-managed-agents skill

A Claude Code skill that gives Claude a complete Python reference for Anthropic's Managed Agents API (/v1/agents, /v1/sessions).

When this skill is active, Claude can author, debug, and operate Managed Agents applications without reaching for external docs — all API behavior, event types, error handling, and SDK patterns are loaded directly into context.

Official resources:

• Docs: platform.claude.com/docs/en/managed-agents/overview
• Engineering blog: Scaling Managed Agents: Decoupling the brain from the hands

---

What are Managed Agents?

Managed Agents are Anthropic's hosted, stateful execution environment for Claude (currently in beta). Unlike the plain Messages API, the platform owns the conversation thread, manages context compaction, and runs tools server-side inside an isolated container. The Managed Agents API is language-agnostic (HTTP + SSE), but this skill focuses on the Python SDK.

Dimension	Messages API	Managed Agents
State	Stateless — caller owns history	Stateful sessions; server owns thread
Execution	Client sends full context each call	Hosted container; agent persists across turns
Communication	Request/response	Bidirectional event stream (SSE)
Configuration	Inline per-request	Reusable versioned Agent objects

Use Managed Agents when you need long-running multi-tool tasks, server-managed context, or reusable agent configurations that persist across sessions.

---

Skill coverage

SKILL.md is a single-file Python reference organized into 16 sections:

#	Section	What it covers
1	Orientation	Primitives (Agent, Environment, Session), when to use vs Messages API
2	Install + Auth	pip install anthropic, sync/async clients, timeouts, retries
3	Creating an Agent	client.beta.agents.create(), all parameters, tools, MCP servers, skills
4	Tools	agent_toolset_20260401, custom tools, mcp_toolset, permission policies
5	MCP Connectors	URL-based MCP servers, vault auth, mcp_auth_error handling
6	Skills	Attaching Anthropic and custom skills to agents
7	Environments + Vaults	Container config, networking, pip/apt packages, vault creation
8	Sessions	sessions.create(), versioned agent references, resources, lifecycle
9	Event Stream	Full event loop with match/case, custom tool results, tool confirmation
10	Multi-Agent	callable_agents, coordinator pattern, isolation guarantees
11	Agent Versioning	agents.update(), array replacement semantics, pinning versions
12	Observability	span.* events, session.retrieve().usage, Console UI
13	Files API	Upload, list, download, delete — client.beta.files.*
14	Prompt Caching	Automatic platform caching, TTL tiers, no client-side config needed
15	Errors + Retries	Exception hierarchy, SDK defaults, rate limits, non-retryable states
16	E2E Example	Minimal working example + reference to scripts/quickstart.py

Detailed reference material lives in references/:

File	Contents
api_cheatsheet.md	Condensed endpoint × parameter table for Agents, Sessions, Files
event_types.md	Exhaustive event-type reference with example payloads
migration_from_messages_api.md	Step-by-step migration from the plain Messages API
containers.md	Container specs, networking modes, environment reuse
tools_and_mcp.md	Tool type details and MCP connector setup
multi_agent.md	Multi-agent orchestration, callable_agents, thread routing
observability_and_caching.md	Span events, session usage totals, prompt caching details

---

Quickstart script

scripts/quickstart.py is a runnable end-to-end demo that exercises the full API surface:

1. Creates an environment
2. Creates an agent with agent_toolset_20260401 (always_ask) + a custom get_city_time tool + an MCP server declaration
3. Creates a vault
4. Creates a session referencing all three
5. Streams events; handles tool confirmation and custom tool results
6. Retrieves session usage after the session goes idle
7. Archives all resources on exit

# Preview the planned API calls without hitting the network
python scripts/quickstart.py --dry-run

# Run against the real API
ANTHROPIC_API_KEY=sk-ant-... python scripts/quickstart.py

---

Installing the skill

Claude Code (personal)

Copy SKILL.md and the references/ directory into your personal skills folder:

mkdir -p ~/.claude/skills/claude-managed-agents
cp SKILL.md ~/.claude/skills/claude-managed-agents/
cp -r references ~/.claude/skills/claude-managed-agents/

Claude Code (project)

Place the files under .claude/skills/ in your project root so the skill is shared with anyone who clones the repo.

Via a plugin

If you manage skills through a plugin registry, the skill name is claude-managed-agents and the entry point is SKILL.md.

---

When Claude loads this skill

The skill triggers automatically when Claude detects any of these signals in your code or conversation:

• Imports or references to client.beta.agents, client.beta.sessions, client.beta.environments, client.beta.vaults
• The beta header managed-agents-2026-04-01
• Tool types agent_toolset_20260401 or mcp_toolset
• Event types like session.status_idle, agent.custom_tool_use, user.tool_confirmation
• Phrases like "managed agents", "managed agent session", "callable_agents", "define_outcome"

---

Requirements

• Python 3.10+ (match/case syntax used in event loop examples; if/elif works for earlier versions)
• pip install anthropic
• ANTHROPIC_API_KEY environment variable
• Access to the Managed Agents beta — all requests require the header anthropic-beta: managed-agents-2026-04-01 (the Python SDK sets this automatically)

Note: Multi-agent orchestration, define_outcome, and memory stores are research-preview features requiring separate access. See the official docs for access details.