The Claude Agent SDK: building on the Claude Code loop

What it saves you writing

Installing it and running one agent

Prerequisites are Node.js 18 or later, or Python 3.10 or later.

# TypeScript
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

# Python, with uv
uv add claude-agent-sdk

# Python, with pip
pip install claude-agent-sdk

# then, in the shell that runs your agent
export ANTHROPIC_API_KEY=your-api-key

import { query } from "@anthropic-ai/claude-agent-sdk";

const result = query({
  prompt: "Review src/auth/session.ts for security defects. Report only "
        + "issues with a concrete exploit path.",
  options: {
    cwd: "/Users/you/code/project",
    model: "claude-opus-5",

    // Capability is the control. An instruction is not.
    allowedTools: ["Read", "Grep", "Glob"],
    permissionMode: "default",

    // Two independent stops.
    maxTurns: 12,
    maxBudgetUsd: 2,
  },
});

for await (const message of result) {
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if (block.type === "text") process.stdout.write(block.text);
    }
  }
  if (message.type === "result") {
    console.error(
      `\ncost $${message.total_cost_usd} in ${message.num_turns} turns`,
    );
  }
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage


async def main():
    async for message in query(
        prompt="Review src/auth/session.py for security defects.",
        options=ClaudeAgentOptions(
            cwd="/Users/you/code/project",
            model="claude-opus-5",
            allowed_tools=["Read", "Grep", "Glob"],
            permission_mode="default",
            max_turns=12,
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
        elif isinstance(message, ResultMessage):
            print(f"done: {message.subtype}")


asyncio.run(main())

The options that actually matter

The TypeScript option surface is large. These are the ones that change whether your agent is safe, bounded, and reproducible.

Sessions, and why they are the reason to use this

A single query() is easy to build yourself. What is not easy is everything that happens when a task spans more than one call: persisting the transcript, resuming it on a different machine, forking it so two branches share a prefix, and compacting it when it outgrows the window. The SDK gives you all four as options rather than as a subsystem you own.

Streaming or collecting

The example above streams, because query() returns an async iterator and each iteration yields the next event: reasoning, a tool call, a tool result, or the final outcome. That is what you want behind a user interface, where minutes of silence is not an acceptable loading state.

For a background job or a CI step there is nothing to show, so collect the messages and read the result at the end. The trade is only about who is watching, not about capability, and the same code shape works either way.

SDK, CLI, Client SDK, or Managed Agents

Four things that surprise people

1. It reads your project files. CLAUDE.md, .claude/settings.json, skills, and configured MCP servers all load based on cwd. Convenient in development, surprising in production, and occasionally a real leak. Pass settingSources: [] and strictMcpConfig: true when you want a hermetic agent.
2. Cost is per session, not per call. The loop makes many model calls. total_cost_usd on the result message is the number that matters, and maxBudgetUsd is the only thing that stops it climbing while nobody is looking.
3. You cannot resell claude.ai login. Unless previously approved, Anthropic does not permit third-party developers to offer claude.ai login or subscription rate limits in their products, including agents built on this SDK. Ship API-key authentication, or your own billing on top of it.
4. Branding is constrained. "Claude Agent" and "Powered by Claude" are permitted. "Claude Code", "Claude Code Agent", and Claude Code ASCII art are not. Your product should not look like it is Claude Code.

Questions people ask

Keep reading