managed-agents-api

Managed Agents API

The Managed Agents API lets Anthropic run the agent loop server-side. You POST a user message; they run the tool loop, manage context, and stream results. You lose control but gain simplicity and durability.

When to Use

• Production agents where you don't want to operate infrastructure
• Long-running agents that span hours/days — server-side compaction handles it
• Multi-client agents (web + mobile + CLI) sharing sessions
• Scaling without worrying about loop-runner uptime

When NOT to Use

• Agents with heavy client-side context (local files, IDE state) — SDK fits better
• You need custom tool-execution environments not exposed by Managed
• Debug-heavy development — self-hosted gives you more visibility

Core Objects

1. Agent (/v1/agents) — a template: name, system prompt, tools, model
2. Session (/v1/sessions) — a live conversation bound to an agent
3. Message — added to a session; triggers agent run

Create an Agent

const agent = await client.beta.agents.create({
  name: "support-bot",
  description: "Customer support for ACME",
  model: "claude-sonnet-4-6",
  system_prompt: "You are ACME's support agent. Be concise and accurate.",
  tools: [
    { type: "search_tickets", name: "search_tickets", /* schema */ },
    { type: "create_escalation", name: "create_escalation" },
  ],
  mcp_servers: [
    { type: "url", url: "https://mcp.acme.com/sse", name: "acme" },
  ],
});
// Returns: { id: "agt_...", name: "support-bot", ... }

Agents are versionable — update without breaking live sessions.

Start a Session

const session = await client.beta.sessions.create({
  agent_id: agent.id,
  metadata: { user_id: "u-42", ticket_id: "T-1001" },
});
// Returns: { id: "ses_...", agent_id: "agt_...", status: "idle", ... }

Metadata is yours to use for filtering, auditing, linking to your domain.

Send a Message

const stream = client.beta.sessions.messages.stream({
  session_id: session.id,
  content: "My order #12345 is stuck — can you help?",
});

for await (const event of stream) {
  if (event.type === "text") console.log(event.delta);
  if (event.type === "tool_use") console.log("TOOL:", event.name);
  if (event.type === "done") break;
}