Claude Agent SDK guide: build, secure and deploy your first agent

The Claude Agent SDK is a Python and TypeScript library that gives your application the same agent loop, built-in tools and context management that power Claude Code. This guide shows when to use it, how to build a first agent, how to add tools and permissions, and how to host it in production.

What is the Claude Agent SDK?

The Claude Agent SDK is Anthropic's library for building agents in Python or TypeScript on top of Claude Code's engine. It gives your code the same agent loop, built-in tools (read, write and edit files, run shell commands, search the web) and context management that Claude Code uses, so you write the task and the guardrails instead of the plumbing (Agent SDK overview).

Under the hood, the SDK starts a claude CLI subprocess and talks to it over stdio. That detail explains most of how the SDK behaves: each session has a working directory, a shell and transcript files on disk, and it loads CLAUDE.md, skills and settings the way Claude Code does.

Built-in capabilities you get without writing them:

• Tools: file read, write and edit, glob and grep search, Bash, web search and fetch.
• Hooks: your code runs at points in the agent lifecycle, for example before a tool call.
• Subagents: specialized agents for focused subtasks.
• MCP: connect external tools and data sources, or define your own tools in-process.
• Permissions: decide which tools run automatically and which need approval.
• Sessions: keep context across turns, resume or fork later.

If you are new to agents, the core idea is a loop: the model plans, acts with a tool, observes the result and repeats until the task is done. The SDK runs that loop for you.

When should you use the Agent SDK instead of other Claude tools?

Use the Agent SDK when you want an agent that works on files and commands inside your own application or service. Anthropic offers four ways to build with Claude, and they differ in who runs the loop and what comes built in.

A quick rule of thumb:

• If a shell script with claude -p does the job, start there. It shares the same engine (headless docs).
• If you need typed messages, approval callbacks, custom tools in your own process or a web UI around the agent, use the Agent SDK.
• If your app needs a chat completion or a single tool call, not a multi-step agent, the plain Client SDK is simpler. Our Claude API tutorial covers it, and our guide to building an AI agent in Python shows how to write the loop yourself.

For a comparison with LangGraph, CrewAI, the OpenAI Agents SDK and others, see AI agent frameworks.

How do you install and authenticate the Agent SDK?

Install the package for your language, set an API key, and you are ready. You need Python 3.10+ or Node.js 18+; both SDKs bundle a native Claude Code binary for most platforms, so you don't install the CLI separately (quickstart).

1. Create a project folder. The agent can read files in that directory and its subdirectories by default.

2. Install the SDK.

   pip install claude-agent-sdk

   npm init -y && npm pkg set type=modulenpm install @anthropic-ai/claude-agent-sdknpm install --save-dev tsx

3. Set your API key from the Claude Console. The SDK reads it from the process environment and does not load .env files on its own.

   export ANTHROPIC_API_KEY=your-api-key

4. Or use a cloud provider. Set CLAUDE_CODE_USE_BEDROCK=1 (Amazon Bedrock), CLAUDE_CODE_USE_VERTEX=1 (Google Cloud) or CLAUDE_CODE_USE_FOUNDRY=1 (Microsoft Foundry) and configure that provider's credentials.

How do you build your first agent with the Claude Agent SDK?

A first agent is one call to query() with a prompt and options. query() returns an async iterator that streams messages as Claude thinks, calls tools and finishes, ending with a result message.

This Python agent reviews a file for crash bugs and fixes them. It pre-approves three tools and auto-accepts file edits:

import asynciofrom claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessageasync def main():    async for message in query(        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",        options=ClaudeAgentOptions(            allowed_tools=["Read", "Edit", "Glob"],            permission_mode="acceptEdits",            max_turns=20,        ),    ):        if isinstance(message, AssistantMessage):            for block in message.content:                if hasattr(block, "text"):                    print(block.text)                elif hasattr(block, "name"):                    print(f"Tool: {block.name}")        elif isinstance(message, ResultMessage):            print(f"Done: {message.subtype}")asyncio.run(main())

The TypeScript version has the same shape:

import { query } from "@anthropic-ai/claude-agent-sdk";for await (const message of query({  prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",  options: {    allowedTools: ["Read", "Edit", "Glob"],    permissionMode: "acceptEdits",    maxTurns: 20,  },})) {  if (message.type === "assistant" && message.message?.content) {    for (const block of message.message.content) {      if ("text" in block) console.log(block.text);      else if ("name" in block) console.log(`Tool: ${block.name}`);    }  } else if (message.type === "result") {    console.log(`Done: ${message.subtype}`);  }}

Run it with python agent.py or npx tsx agent.ts. A successful run ends with Done: success. If the agent hits the turn limit, the result subtype is error_max_turns and query() raises after yielding it, so wrap the loop in try when the process must exit cleanly.

Change behavior through options, not code:

How do you give an Agent SDK agent custom tools?

You define custom tools as functions and register them through an in-process MCP server. Each tool has a name, a description Claude reads to decide when to call it, an input schema and an async handler (custom tools docs).

This example gives an agent a read-only tool that looks up an order in your own system:

import asynciofrom typing import Annotated, Anyfrom claude_agent_sdk import (    tool, create_sdk_mcp_server, query, ClaudeAgentOptions, ResultMessage, ToolAnnotations,)@tool(    "get_order",    "Look up an order by ID and return its status, items and total",    {"order_id": Annotated[str, "Order ID such as ord_123"]},    annotations=ToolAnnotations(readOnlyHint=True),)async def get_order(args: dict[str, Any]) -> dict[str, Any]:    order = await fetch_order_from_db(args["order_id"])  # your own function    if order is None:        return {"content": [{"type": "text", "text": "No order with that ID."}], "is_error": True}    return {"content": [{"type": "text", "text": str(order)}]}orders = create_sdk_mcp_server(name="orders", version="1.0.0", tools=[get_order])async def main():    options = ClaudeAgentOptions(        mcp_servers={"orders": orders},        allowed_tools=["mcp__orders__get_order"],        tools=[],        permission_mode="dontAsk",    )    async for message in query(prompt="Why is order ord_123 delayed?", options=options):        if isinstance(message, ResultMessage) and message.subtype == "success":            print(message.result)asyncio.run(main())

Details that matter:

• Tool names in permission rules follow mcp__{server}__{tool}, so this tool is mcp__orders__get_order.
• tools=[] removes every built-in tool, so this support agent can't touch files or run shell commands.
• Returning is_error: True lets you write the error message Claude sees. An uncaught exception is also turned into an error result, but with the raw message.
• readOnlyHint lets Claude call the tool in parallel with other read-only tools. Annotations are hints; the handler decides what really happens.
• In TypeScript, use tool() with a Zod schema and createSdkMcpServer().

Tool search is on by default, so Claude sees tool names in a compact list and loads full schemas on demand. That keeps dozens of tools from filling the context window. To connect existing servers instead of writing your own, see what MCP is.

How do permissions work in the Claude Agent SDK?

The SDK checks every tool request in a fixed order: hooks, deny rules, ask rules, the permission mode, allow rules, and finally your canUseTool callback (permissions docs). The first step that decides wins, and deny rules apply even in bypassPermissions mode.

Three behaviors catch people out:

1. allowed_tools does not restrict bypassPermissions. In bypass mode every tool is approved, listed or not. Block tools with disallowed_tools instead.
2. Auto-approved calls never reach canUseTool. If a tool is allowed by a rule or the mode, checks in your callback are skipped. Put checks that must always run in a PreToolUse hook.
3. Subagents inherit the parent's mode. A parent in bypassPermissions gives its subagents full access too.

For a locked-down agent, pair a short allowed_tools list with permission_mode="dontAsk". For coding agents, prefer scoped rules such as Bash(npm test *) over a bare Bash. The same rule syntax is used by Claude Code hooks and settings files.

How do you deploy a Claude Agent SDK agent to production?

Deploy each agent session as a long-lived process with its own working directory, ideally in a sandboxed container. Hosting an agent is closer to hosting a small dev machine than a stateless API, because the subprocess keeps a shell, files and transcripts on local disk (hosting docs).

Pick a session pattern first:

Production checklist from Anthropic's hosting guide:

• Resources: start at 1 GiB RAM, 5 GiB disk and 1 CPU per agent, then measure peak memory for your real session lengths.
• Persistence: local transcripts disappear on restart. Configure a SessionStore adapter for sessions users expect to resume, and store working-directory files separately.
• Time limits: sessions have no top-level timeout. Set max_turns, and cap subagents with their own maxTurns.
• Network: allow outbound HTTPS to api.anthropic.com (or your cloud provider) and route other egress through a proxy with a domain allowlist.
• Secrets: supply ANTHROPIC_API_KEY from a secret manager, and inject tool credentials at a proxy rather than putting them in the agent's environment.
• Multi-tenant isolation: pass setting_sources=[], set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1, use a per-tenant CLAUDE_CONFIG_DIR and a per-tenant cwd, so one customer's files and memory never reach another's session.
• Observability: the SDK reads OpenTelemetry settings from the environment (CLAUDE_CODE_ENABLE_TELEMETRY=1 plus standard OTEL_* variables). Prompt text and tool inputs are excluded from exports by default.
• Cost: Anthropic estimates a minimal container at roughly $0.05 an hour, while one long session can spend dollars in tokens. Track tokens per session, not servers.

The SDK version pins the bundled CLI version, so updating the SDK is how you update the engine. Take patch releases and read the changelog before a minor upgrade.

If what you need is Claude Code itself working unattended on your repositories, not a custom product, you may not need the SDK at all. A server running Claude Code headless or a hosted box such as Orkio, which keeps Claude Code agents running on an always-on cloud server and opens pull requests for review, covers that case.

Next steps: ship a small agent this week

Start narrow, measure, then widen what the agent can do.

1. Pick one repetitive task with a clear output, such as triaging new issues or fixing lint errors in a directory.
2. Build it with query(), a three-tool allowed_tools list, permission_mode="dontAsk" or acceptEdits, and max_turns.
3. Move any domain logic the agent needs into one or two custom tools with clear error messages and accurate annotations.
4. Add a PreToolUse hook for any rule that must hold on every call, such as never touching migrations/.
5. Run it in a container with its own working directory and log every result message, including cost.
6. Review twenty runs by hand before you remove a human from the loop. Our guide to Claude Code subagents is the next step once one agent works and you want to split the work.

Frequently asked questions