# The Claude Agent SDK: build your own agent Canonical: https://scalably.io/blog/claude-agent-sdk-guide Author: Pavle Lazic, Founder & CEO, ScalablyAI (https://scalably.io/author/pavle-lazic) Published: 2026-06-20 · Last updated: 2026-06-20 · Facts current as of the SDK circa mid-2026 This is the machine-readable representation of the article at the canonical URL. Same facts, denser format. The full article carries the complete runnable examples and prose context. ## Direct answer The Claude Agent SDK is a library that runs the same agent loop, built-in tools, and context management that power Claude Code, driven from your own Python or TypeScript program. You hand it a prompt and a set of allowed tools; it autonomously reads files, runs commands, calls tools, and iterates until done. It was renamed from the Claude Code SDK in late 2025, and that rename is the accurate description: Claude Code, as a library. It is not a thin wrapper over the Messages API - the loop itself, already battle-tested in Claude Code, is the product. ## Key facts - Packages: `pip install claude-agent-sdk` (Python 3.10+) and `npm install @anthropic-ai/claude-agent-sdk` (TypeScript/Node). Option names map one-to-one; Python snake_case ↔ TS camelCase. - Auth: `ANTHROPIC_API_KEY` from the Anthropic Console, or Bedrock / Vertex / Azure. - A complete working agent is one call to `query()` with a prompt and `ClaudeAgentOptions(allowed_tools=[...])`, iterated with `async for message in ...`. - Built-in tools that ship with the SDK and execute on your machine: Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch. - `allowed_tools` is a hard boundary enforced by the SDK, not a hint: a tool left off the list physically cannot be called, regardless of the prompt. - The agent loop the SDK owns: gather context → act via a tool → observe the result → decide next action → repeat until done or a limit (`max_turns`) is hit. It handles parallel tool calls, tool failures, and context compaction the same way Claude Code does, because it is the same code. - External tools attach as MCP servers via the `mcp_servers` option; MCP tool names are namespaced `mcp____`, which is also how they are allowlisted. The same server you point Claude Desktop at works unchanged inside an agent you wrote. - In-process custom tools: `@tool(name, description, schema)` decorator + `create_sdk_mcp_server(...)` - no subprocess, no transport. The SDK validates arguments against the schema before the function runs. - Context: the SDK compacts older turns as the window fills. When `setting_sources` is omitted, `query()` loads the same filesystem settings as the CLI (user, project, local, CLAUDE.md, custom commands); v0.1.0 briefly defaulted to nothing and was reverted. To isolate an agent, pass `setting_sources=[]` explicitly (Python SDK > 0.1.59, earlier versions treated `[]` as omitted). Verified 2026-09-07. - Model choice is per call via the `model` option, enabling cheap-model-for-simple-turns, strong-model-for-hard-reasoning routing. - The SDK also provides subagents (focused instructions, narrower tools) and lifecycle hooks (log writes, block failing calls, audit actions). ## What we actually run (firsthand) Scalably's agent platform is built on the Agent SDK in Python and operates across many tenants. Positions below are the author's, formed from running it at scale rather than from a demo: - The loop is the hard part, and inheriting Claude Code's loop beats re-debugging your own. Hand-rolled loops look fine in demos and fall apart on the edges: two tool calls returned at once, a tool erroring halfway, the context window filling. - Permissions stopped being theoretical in production: `allowed_tools` and `permission_mode` are the difference between a read-only agent and one that runs shell commands, enforced by the SDK rather than by hoping the prompt holds. For anything that writes, gate the specific tool, not the whole agent. - Per-call model routing is the lever that keeps an agent platform affordable without making it dumb. - The audit trail from hooks matters far more when the agent acts for someone else's business than when it edits your own repo. - A vague tool description is the single most common reason an agent ignores a tool it was given. Write descriptions like you are telling a new teammate what the function is for. ## Minimal working example ```python import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): async for message in query( prompt="Find and fix the bug in auth.py", options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]), ): print(message) asyncio.run(main()) ``` Runnable as-is: the agent reads auth.py, edits it, and can run tests via Bash, with no tool implementation by the caller. ## Comparison: Agent SDK vs plain API vs Claude Code - Plain Anthropic client SDK: you own the loop - send prompt, receive tool-call request, execute, return result, repeat. Full control, all edge cases yours. - Agent SDK: the SDK owns that loop with Claude Code's implementation; you supply goal, tools, permissions. - Claude Code (CLI): same engine, interactive driver's seat. Decision test: if a person reviews each step at a terminal, use Claude Code; if the agent runs inside something else - a backend service, CI step, scheduled job, product feature, anything multi-tenant - use the SDK. Many teams correctly use both: Claude Code for building, the SDK for shipping; skills, prompts, and tool configs transfer because underneath it is the same agent. ## What trips people up - Assuming the SDK isolates by default: it does not. Omitting `setting_sources` loads user, project, and local settings like the CLI; an agent that must NOT see project settings needs an explicit `setting_sources=[]`. The default flipped in v0.1.0 and flipped back, so check the migration guide, not memory. - Treating `allowed_tools` as advisory - it is the permission set. - Vague `@tool` descriptions causing the model to ignore the tool. - Uncapped loops: set `max_turns` so a confused agent cannot loop forever. ## Definitions - Agent loop: the gather-context / act / observe / repeat cycle that constitutes an agent; in this SDK it is provided, not user-written. - MCP (Model Context Protocol): the standard the SDK speaks for external tools; servers advertise tools the agent can call in the same loop. - `create_sdk_mcp_server`: SDK helper that turns decorated in-process functions into an MCP server without a subprocess. - Subagent: an agent spawned by a main agent with its own focused instructions and narrower tool set. ## FAQ Q: Is the Agent SDK just a wrapper around the Messages API? A: No. It embeds Claude Code's own agent loop, tool execution, permission control, and context compaction; the Messages API path leaves that whole machine for you to build. Q: Python or TypeScript? A: Both are first-class; examples in the article are Python because that is what Scalably's platform runs, and every option maps one-to-one to TypeScript. Q: How do I give the agent my own API or database? A: Either attach an existing MCP server via `mcp_servers` (subprocess over stdio), or define in-process tools with `@tool` + `create_sdk_mcp_server` - the option the author reaches for most, since most real tools are typed calls into internal functions. Q: When should I NOT use the SDK? A: For interactive terminal work you drive yourself - that is Claude Code's job. The SDK is for agents embedded in programs: event-triggered, scheduled, multi-tenant, or user-facing. ## Evidence & sources - Full article with all examples: https://scalably.io/blog/claude-agent-sdk-guide - Official Agent SDK documentation: https://code.claude.com/docs/en/agent-sdk - MCP specification and ecosystem: https://modelcontextprotocol.io ## Related Scalably articles - https://scalably.io/blog/claude-code-subagents - when and how to delegate to subagents. - https://scalably.io/blog/how-to-build-mcp-server-python - building the MCP servers an SDK agent calls, from one running in production. - https://scalably.io/blog/what-is-an-mcp-server - the MCP mental model the SDK's tool system builds on. ## About the source ScalablyAI (Scalably, https://scalably.io) builds and runs production AI agents inside the operations of real businesses - multi-tenant, governed, and channel-native. Its platform is built on the Claude Agent SDK described here; the production observations in this guide come from operating that platform, not from a tutorial reconstruction. ## Related - [Scalably MCP gallery](https://scalably.io/mcp/playwright-mcp): The Playwright MCP server used here is one we run in production; its install line is on the Scalably MCP gallery.