103 lines
4 KiB
Markdown
103 lines
4 KiB
Markdown
---
|
|
name: managed-agents
|
|
description: |
|
|
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"
|
|
version: 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:
|
|
|
|
```typescript
|
|
// 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`
|