agent-builder/skills/managed-agents/SKILL.md

name	description	version
managed-agents	This skill should be used when the user asks about "managed agents", "Anthropic API agents", "cloud-hosted agents", "agent SDK", "deploying agents to the cloud", "serverless agents", "API-based agent deployment", "/v1/agents endpoint", "remote agent hosting", "agent as a service"	0.1.0

What are managed agents

Managed agents are Anthropic-hosted agent runtimes accessed via the Agent SDK (@anthropic-ai/sdk for TypeScript, anthropic for Python). Instead of running Claude Code locally, the agent runs on Anthropic's infrastructure with persistent sessions, tool access, and automatic scaling.

Key difference from local agents: managed agents don't have local filesystem access by default. They work through tools you define in code, not through Claude Code's built-in Read/Write/Bash tools.

When to use managed agents vs local deployment

Dimension	Managed Agents (API)	Local (Claude Code CLI)
Infrastructure	Anthropic-hosted	Your machine/server
Filesystem	Via tools you define	Full local access
MCP servers	Not available	Full MCP support
Scaling	Automatic	Manual
Cost model	Per-token API billing	Subscription or API key
Best for	SaaS products, API integrations	Personal pipelines, file-heavy work
Session persistence	Via API sessions	Via --resume / --name

Decision rule: If your agents need local filesystem access, MCP servers, or run as part of a personal workflow → use local deployment (cron/launchd/systemd/Docker). If your agents are part of a product, need to scale, or don't need local files → use managed agents.

Important limitation: Managed agents cannot use MCP servers. If your agent system relies on MCP servers for Slack, GitHub, databases, or other integrations, use local deployment with Docker for isolation instead.

SDK patterns

For concrete code patterns, see: ${CLAUDE_PLUGIN_ROOT}/skills/managed-agents/references/api-patterns.md

Session management

Managed agents support persistent sessions via the API:

// Create a new session
const session = await client.agents.sessions.create({
  agent_id: "ag_...",
  system_prompt: "You are a research agent..."
});

// Resume an existing session
const response = await client.agents.sessions.messages.create({
  agent_id: "ag_...",
  session_id: session.id,
  messages: [{ role: "user", content: "Continue the analysis" }]
});

Sessions maintain conversation history and tool state across multiple interactions, similar to claude --resume for local agents.

Budget and cost considerations

Managed agents bill per token at standard API rates. For cost control:

1. Set max_tokens on each request to cap output length
2. Use prompt caching — cached input tokens cost 90% less
3. Batch non-urgent work — batch API gives 50% discount
4. Monitor with Admin API — if you have org access, use /v1/organizations/usage_report/messages with an Admin API key (sk-ant-admin...) for detailed cost breakdowns
5. Use --max-budget-usd flag for local headless runs as a budget cap

Note: The Usage & Cost API requires an Admin API key and organization account. Individual accounts should estimate costs from token counts.

Migration path: local → managed

1. Extract your agent's system prompt from .claude/agents/[name].md
2. Convert tool access to SDK tool definitions
3. Replace file-based memory with session persistence or external storage
4. Replace MCP server integrations with direct API calls in tool handlers
5. Test with the SDK before removing local deployment

This is a significant architectural change. Only migrate if you need API-based access or auto-scaling. Local deployment is simpler and cheaper for personal use.

Getting started

For a guided setup: run /agent-factory:build and choose "Managed Agents" as the deployment target in Phase 6.

For manual setup: see the API patterns reference at ${CLAUDE_PLUGIN_ROOT}/skills/managed-agents/references/api-patterns.md