Claude Agent SDK: The Shortest Path from Prototype to Production Agent

You built an AI agent that works in your terminal. It reads files, calls APIs, makes decisions. Impressive demo. Now someone asks: "Can we deploy this?"
And you realize you need sandboxing, state management, tool authentication, error recovery, streaming, and a way to not blow through your API budget when the agent gets stuck in a loop.
The Agent SDK handles the infrastructure so you can focus on what your agent actually does.

Key Takeaways

• The Agent SDK extends Claude Code's runtime into a library you can embed in your own apps
• Available in TypeScript and Python
• Managed Agents (public beta) runs your agents in Anthropic's cloud with sandboxing and persistence
• Your agent gets the same tools Claude Code uses: file system, shell, web search, subagents
• You define the agent's behavior with markdown instructions, the same way skills work

Two Ways to Ship an Agent

Agent SDK (self-hosted): You run the agent runtime in your own infrastructure. Full control over the environment, tools, and data flow. Good when you need to access internal systems or have compliance requirements.
Managed Agents (Anthropic cloud): Anthropic runs the agent for you in a sandboxed environment. You create sessions via API, the agent runs in the cloud, you get results via server-sent events. Good when you want to skip the ops work.
Both use the same programming model. Code written for one works with the other.

Getting Started with the SDK

Install:

# TypeScript
npm install @anthropic-ai/claude-code-sdk

# Python
pip install claude-code-sdk

Run your first agent:

import { ClaudeCode } from '@anthropic-ai/claude-code-sdk';

const agent = new ClaudeCode();
const result = await agent.run({
  prompt: 'Find all TODO comments in this repo and create GitHub issues for them',
  tools: ['Read', 'Bash', 'Write'],
});

The agent gets the same tool ecosystem as Claude Code. It can read files, run commands, search the web, and spawn subagents for parallel work.

What Makes This Different from Raw API Calls

Tool orchestration is built in. When the agent needs to read a file, it calls the Read tool. When it needs to run a command, it calls Bash. You don't need to implement tool routing, parameter validation, or error handling for each tool.
Subagents for parallel work. Your agent can spawn child agents that run in isolated contexts. A code review agent spawns three subagents: one checks tests, one checks security, one checks style. Results merge back.
State persists across turns. The agent maintains conversation context, file system state, and tool results across multiple interactions. You can build multi-step workflows where each step builds on the last.
Sandboxing by default. Managed Agents run in isolated containers. Your agent can't accidentally rm -rf your production server because it's not on your production server.

Managed Agents: The Cloud Path

Managed Agents is in public beta. You interact with it through the API:

1. Create a session with your agent's instructions and tools
2. Send messages to the session
3. Stream responses via server-sent events
4. The agent persists — come back hours later and it remembers the context
   The API requires the managed-agents-2026-04-01 beta header.

💡 Memory is built in. Managed Agents can remember things across sessions. Tell it "remember that our API uses v2 endpoints" and it'll know next time without you repeating it.

When to Use What

Use the SDK when: you need to access internal systems, have data residency requirements, want full control over the runtime, or are building the agent into an existing product.
Use Managed Agents when: you want to skip infrastructure setup, need sandboxing without building it yourself, want built-in persistence and memory, or are prototyping and want the fastest path to a working agent.
Use neither (just Claude Code) when: you're building for yourself, not for users. Claude Code with skills and hooks is already an agent runtime — the SDK is for embedding that capability in your own software.

A Few Things That Surprised Me

💡 The SDK agent uses the same CLAUDE.md and skills as Claude Code. If you have a project with existing Claude Code configuration, the SDK agent picks it up automatically.
💡 Subagent types are the same. Explore, Plan, general-purpose — the agent types you know from Claude Code work the same way in the SDK.
💡 Streaming is real-time. Server-sent events mean your UI can show the agent's progress as it works, not just the final result.

Honest Limitations

❌ Managed Agents is in beta. Expect rough edges in documentation and occasional API changes.
❌ Cost can add up fast. An agent that runs for 10 minutes doing complex work will use significantly more tokens than a single API call. Set token budgets.
❌ Not every tool is available in Managed Agents. Computer use, for example, requires desktop access that the cloud environment doesn't have.

Setting Up

Agent SDK:

1. Install the SDK (npm install @anthropic-ai/claude-code-sdk or pip install claude-code-sdk)
2. Set your API key (ANTHROPIC_API_KEY)
3. Write your agent's instructions and run it
   Managed Agents:
4. Get API access with the managed-agents beta header
5. Create a session via the API
6. Send messages and stream responses
   Agent SDK overview | SDK TypeScript reference | SDK Python reference