Claude Agent SDK: Building Production-Grade AI Agents

What Is the Claude Agent SDK?

The Claude Agent SDK is Anthropic's official framework for building autonomous AI agents in Python and TypeScript. It provides the same agentic capabilities that power Claude Code -- file reading, code execution, web browsing, and tool use -- as a programmable library that you embed in your own applications. Python requires 3.10+ and TypeScript requires Node 18+.

At its foundation, the SDK implements a 4-phase agentic loop: (1) the agent receives a task, (2) it reasons about what tools to use, (3) it executes tool calls and collects results, and (4) it evaluates whether the task is complete or needs further iteration. This loop runs autonomously until the agent determines the task is finished or hits a configured limit.

The SDK abstracts away the complexities of tool calling, response parsing, error handling, and conversation management. You define your agent's system prompt, available tools (built-in or custom), and constraints. The SDK handles the rest: constructing API calls, parsing tool use responses, executing tools, feeding results back, managing context window limits, and streaming output to the user. It also integrates natively with MCP servers, allowing your agents to access the same ecosystem of 50+ tool servers available to Claude Code.

How I Use It

I use the Claude Agent SDK to build custom automation agents that go beyond what Claude Code offers out of the box. My primary use case is building specialized agents for clients -- agents that understand their specific business domain, connect to their internal tools, and automate their unique workflows.

For the project, I built a deployment agent that reads the git log, determines which microservices changed, generates Helm chart values, validates Kubernetes manifests, and triggers deployments. This agent runs in a CI/CD pipeline and has reduced deployment errors to near zero because it cross-references changes with the service dependency graph before deploying.

Another production agent handles database migration validation. It reads proposed migration files, analyzes them against the current schema, checks for backward compatibility, estimates execution time on production-sized tables, and generates rollback scripts. This replaced a manual review process that took 30 minutes per migration and occasionally missed breaking changes.

I also build agents with structured JSON outputs for data processing pipelines. These agents analyze unstructured data (emails, documents, logs), extract structured information according to a defined schema, and feed results into downstream systems. The structured output guarantees that every agent response is machine-parseable, eliminating the fragility of regex-based extraction.

Getting Started

Install the SDK and build your first agent in under 20 lines. The Python SDK requires Python 3.10+, and the TypeScript SDK requires Node 18+.

# Install the Python SDK
pip install claude-agent-sdk

# Or the TypeScript SDK
npm install @anthropic-ai/agent-sdk

Create a minimal agent with a system prompt and built-in tools. This agent can read files, search code, and execute commands.

# minimal_agent.py - Python example
from claude_agent_sdk import Agent, BuiltinTools

agent = Agent(
    model="claude-sonnet-4-20250514",
    system_prompt="""You are a code review assistant.
    Analyze code for bugs, security issues, and
    style violations. Be concise and actionable.""",
    tools=[
        BuiltinTools.Read,
        BuiltinTools.Glob,
        BuiltinTools.Grep,
        BuiltinTools.Bash
    ],
    max_iterations=20
)

result = agent.run(
    "Review the Python files in ./src/ for common "
    "security vulnerabilities and suggest fixes."
)
print(result.text)

Add a custom tool to extend your agent's capabilities. In Python, tools are defined as decorated functions with typed parameters.

# Custom tool definition (Python)
from claude_agent_sdk import tool

@tool(description="Query the user database")
def query_users(
    filter: str = "Filter expression (e.g. 'active=true')",
    limit: int = "Maximum results to return"
) -> str:
    """Execute a filtered query against the user table."""
    results = db.users.find(parse_filter(filter), limit=limit)
    return json.dumps([u.to_dict() for u in results])

# Add to agent
agent = Agent(
    model="claude-sonnet-4-20250514",
    system_prompt="You are a data analyst assistant.",
    tools=[BuiltinTools.Read, query_users],
    max_iterations=10
)

In TypeScript, tools are defined as objects with a name, description, JSON Schema for inputs, and an execute function.

// Custom tool definition (TypeScript)
import { Agent, Tool } from "@anthropic-ai/agent-sdk";

const queryUsers: Tool = {
  name: "query_users",
  description: "Query the user database",
  inputSchema: {
    type: "object",
    properties: {
      filter: {
        type: "string",
        description: "Filter expression (e.g. 'active=true')"
      },
      limit: {
        type: "number",
        description: "Maximum results to return"
      }
    },
    required: ["filter"]
  },
  async execute(input) {
    const results = await db.users.find(
      parseFilter(input.filter),
      { limit: input.limit ?? 10 }
    );
    return JSON.stringify(results);
  }
};

const agent = new Agent({
  model: "claude-sonnet-4-20250514",
  systemPrompt: "You are a data analyst assistant.",
  tools: [queryUsers],
  maxIterations: 10
});

Connect MCP servers to give your agent access to external services directly from code.

# MCP integration example (Python)
from claude_agent_sdk import Agent, BuiltinTools, MCPServer

agent = Agent(
    model="claude-sonnet-4-20250514",
    system_prompt="You are a project management assistant.",
    tools=[BuiltinTools.Read, BuiltinTools.Bash],
    mcp_servers=[
        MCPServer(
            name="github",
            command="npx",
            args=["-y", "@modelcontextprotocol/server-github"],
            env={"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]}
        ),
        MCPServer(
            name="slack",
            command="npx",
            args=["-y", "@modelcontextprotocol/server-slack"],
            env={"SLACK_BOT_TOKEN": os.environ["SLACK_TOKEN"]}
        )
    ],
    max_iterations=15
)

# Agent can now use GitHub and Slack tools natively
result = agent.run(
    "Read PR #42 from repo acme/api, summarize the "
    "changes, and post a summary to #dev-updates on Slack."
)

Advanced Techniques

Multi-Agent Pipelines

Build pipelines where specialized agents hand off work. A planner agent breaks tasks into subtasks, worker agents execute each subtask, and a reviewer agent validates results. Each agent has a focused system prompt and tool set, improving reliability over a single general-purpose agent.

# Multi-agent pipeline
planner = Agent(
    model="claude-opus-4-20250514",
    system_prompt="Break tasks into subtasks. Output JSON.",
    tools=[BuiltinTools.Read, BuiltinTools.Glob]
)

worker = Agent(
    model="claude-sonnet-4-20250514",
    system_prompt="Execute coding tasks. Write clean code.",
    tools=[BuiltinTools.Read, BuiltinTools.Write,
           BuiltinTools.Bash]
)

reviewer = Agent(
    model="claude-sonnet-4-20250514",
    system_prompt="Review code for bugs and style issues.",
    tools=[BuiltinTools.Read, BuiltinTools.Grep]
)

# Orchestrate
plan = planner.run("Refactor auth module for OAuth2")
for subtask in plan.structured_output["subtasks"]:
    result = worker.run(subtask["description"])
    review = reviewer.run(f"Review: {result.text}")

Structured Output Schemas

Define JSON schemas that force agent responses into predictable structures. This is essential for agents that feed into automated pipelines. The SDK validates outputs and retries with corrective feedback if the model produces invalid JSON.

# Structured output with schema
output_schema = {
    "type": "object",
    "properties": {
        "vulnerabilities": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "severity": {"enum": ["low","medium","high","critical"]},
                    "file": {"type": "string"},
                    "line": {"type": "integer"},
                    "description": {"type": "string"},
                    "fix": {"type": "string"}
                },
                "required": ["severity","file","line","description","fix"]
            }
        },
        "summary": {"type": "string"}
    },
    "required": ["vulnerabilities", "summary"]
}

agent = Agent(
    model="claude-sonnet-4-20250514",
    system_prompt="Security audit agent.",
    tools=[BuiltinTools.Read, BuiltinTools.Grep],
    output_schema=output_schema
)

Streaming and Real-Time Output

Use streaming mode for interactive applications where users need to see progress in real-time. The SDK emits events for each token, tool call start/end, and thinking block. In single mode, you get the complete response at once, which is better for batch processing and automated pipelines where latency per-item is less important than throughput.

# Streaming mode (Python)
async for event in agent.stream("Analyze this codebase"):
    if event.type == "text":
        print(event.text, end="", flush=True)
    elif event.type == "tool_start":
        print(f"\n[Using {event.tool_name}...]")
    elif event.type == "thinking":
        print(f"\n[Thinking: {event.summary}]")

Session Persistence and Recovery

Save session state to disk or a database for cross-session recovery. When an agent crashes or a user returns later, resume from exactly where the conversation left off. Session state includes conversation history, tool results, memory entries, and todo items. Useful for long-running tasks that span multiple user interactions.

# Session persistence (Python)
from claude_agent_sdk import Agent, SessionStore

store = SessionStore(backend="sqlite", path="./sessions.db")

# Resume or start new session
agent = Agent(
    model="claude-sonnet-4-20250514",
    system_prompt="You are a project assistant.",
    tools=[BuiltinTools.Read, BuiltinTools.Write],
    session_store=store,
    session_id="user-123-project-abc"
)

# Agent resumes from last checkpoint if session exists
result = agent.run("Continue where we left off.")

Cost Management Strategies

Implement tiered model selection based on task complexity. Use Haiku for simple extraction, Sonnet for general tasks, and Opus for complex reasoning. Cache tool results across iterations to avoid redundant API calls. Set token budgets per agent to prevent runaway costs. Monitor per-session spending and alert on anomalies.

# Cost tracking (Python)
result = agent.run("Analyze security vulnerabilities")

print(f"Input tokens:  {result.usage.input_tokens}")
print(f"Output tokens: {result.usage.output_tokens}")
print(f"Cache reads:   {result.usage.cache_read_tokens}")
print(f"Total cost:    ${result.usage.total_cost:.4f}")
print(f"Iterations:    {result.iterations}")

Batch Processing

Process large datasets by running multiple agent instances in parallel. Queue tasks, distribute across workers, collect structured results, and handle individual failures without stopping the batch. Combine with structured outputs to guarantee consistent machine-parseable results across all items.

# Batch processing (Python)
import asyncio
from claude_agent_sdk import Agent, BuiltinTools

agent = Agent(
    model="claude-haiku-3-20250307",
    system_prompt="Extract company info from text.",
    output_schema=company_schema
)

async def process_batch(documents):
    tasks = [agent.arun(doc) for doc in documents]
    results = await asyncio.gather(*tasks,
                                    return_exceptions=True)
    return [r.structured_output for r in results
            if not isinstance(r, Exception)]

# Process 500 documents in parallel batches
all_results = await process_batch(documents)

Latest SDK Updates (2025-2026)