Building Agents with the Claude Agent SDK

At some point "Claude Code handles this perfectly in my terminal" wants to become "this runs in my product / pipeline / Slack bot." The Claude Agent SDK is that path: the same engine — agent loop, built-in tools, permissions, MCP, subagents, hooks — as a TypeScript/Python library. You stop driving the agent and start shipping it.

First agent in ten lines

TypeScript:

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt: "Find and fix the bug in auth.ts",
  options: { allowedTools: ["Read", "Edit", "Bash"] },
})) {
  if ("result" in message) console.log(message.result);
}

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"]),
    ):
        if hasattr(message, "result"):
            print(message.result)
 
asyncio.run(main())

Install with npm install @anthropic-ai/claude-agent-sdk (the package bundles the agent binary) or pip install claude-agent-sdk (Python 3.10+), export ANTHROPIC_API_KEY, and that code runs the full loop: the model plans, calls tools, reads their results, edits files, runs commands, and iterates — streaming every step back as messages you can render, log, or gate.

The options that matter

query() takes one options object; these carry most real applications:

Treat allowedTools + maxTurns as non-optional in production — they're the difference between an agent and an unbounded process with your credentials. The permission semantics are identical to Claude Code's.

Custom tools without a server process

The SDK's best trick: your application functions become agent tools via in-process MCP — no separate server to deploy.

import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";
 
const lookupOrder = tool(
  "lookup_order",
  "Look up an order by ID in our database",
  { orderId: z.string() },
  async ({ orderId }) => ({
    content: [{ type: "text", text: JSON.stringify(await db.orders.find(orderId)) }],
  })
);
 
const server = createSdkMcpServer({ name: "shop-tools", version: "1.0.0", tools: [lookupOrder] });
 
for await (const message of query({
  prompt: "Why did order #4127 fail to ship?",
  options: {
    mcpServers: { "shop-tools": { type: "sdk", name: "shop-tools", instance: server.instance } },
    allowedTools: ["mcp__shop-tools__lookup_order"],
  },
})) { /* ... */ }

Inputs are schema-validated before your handler runs, and the tool participates in permissions under its mcp__server__tool name. External MCP servers (the same ecosystem Claude Code uses) plug into the same mcpServers option.

Subagents and hooks: the patterns port over

Everything you've learned composing Claude Code carries into the SDK. Subagents keep big tasks coherent — define specialists and let the lead delegate:

options: {
  allowedTools: ["Read", "Glob", "Grep", "Agent"],
  agents: {
    "code-reviewer": {
      description: "Expert code reviewer",
      prompt: "Analyze code quality and suggest improvements.",
      tools: ["Read", "Glob", "Grep"],
    },
  },
}

Hooks add the deterministic layer — a PreToolUse hook that blocks writes outside a sandbox directory, a PostToolUse hook that logs every command for audit. In the SDK they're plain callbacks in options.hooks, same events and semantics as Claude Code hooks.

Production notes

• Auth: ANTHROPIC_API_KEY for the Claude API; CLAUDE_CODE_USE_BEDROCK=1 or CLAUDE_CODE_USE_VERTEX=1 to run on AWS/GCP with their credential chains. Consumer claude.ai logins aren't a thing here — this is the API surface.
• Billing: API usage is per-token. If your team is on Claude subscription plans, note that Anthropic announced a separate monthly Agent SDK credit for SDK and claude -p usage (planned for June 15, 2026) but paused it before it took effect — for now that usage still meters against your normal plan limits, so check the current policy before you budget.
• Where it sits in the landscape: against LangGraph, CrewAI, and the OpenAI Agents SDK, the Claude Agent SDK's pitch is the harness: you inherit a battle-tested tool-execution loop, permission system, and context management instead of assembling them. The trade is the same as Claude Code's — it runs Anthropic's models, tuned for them.

Start with the smallest version of your agent that does real work — one query(), three tools, maxTurns: 10 — and grow it the way you'd grow a Claude Code workflow: add a custom tool when the model needs your data, a subagent when one context stops being enough, a hook when a rule must hold every time. For making the result reliable, the production tool-calling guide and the agent-reliability-reviewer pick up where this tutorial ends.