Claude Agent SDK

The Claude Agent SDK exposes Claude Code's agent loop as a library. Same built-in tools (Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, AskUserQuestion), same skills / hooks / sub-agents, but programmable from Python or TypeScript.

The Claude Code SDK was renamed to the Claude Agent SDK. Old package imports still work; new imports should target @anthropic-ai/claude-agent-sdk (TS) or claude-agent-sdk (Python).

Install

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

# Python
pip install claude-agent-sdk

# Auth
export ANTHROPIC_API_KEY=sk-ant-...

Third-party platforms also supported — set CLAUDE_CODE_USE_BEDROCK=1, CLAUDE_CODE_USE_VERTEX=1, or CLAUDE_CODE_USE_FOUNDRY=1 and configure cloud credentials accordingly.

Opus 4.7 (claude-opus-4-7) requires Agent SDK v0.2.111 or later.

First win

A bug-fixing agent in 10 lines:

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

for await (const message of query({
  prompt: 'Find and fix the bug in auth.ts. Run the tests when done.',
  options: { allowedTools: ['Read', 'Edit', 'Bash', 'Glob', 'Grep'] },
})) {
  console.log(message);
}

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. Run the tests when done.",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash", "Glob", "Grep"]),
    ):
        print(message)

asyncio.run(main())

That's it — Claude reads the file, locates the bug, edits it, runs tests, iterates on failures. You don't implement the tool loop; the SDK does.

Capabilities

Same feature set as Claude Code, exposed programmatically:

• Built-in tools — Read, Write, Edit, Bash, Monitor, Glob, Grep, WebSearch, WebFetch, AskUserQuestion
• Hooks — callbacks on PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, UserPromptSubmit
• Sub-agents — spawn specialized agents for focused subtasks; they run in isolated contexts
• Sessions — capture session_id from the first query, resume with options: { resume: sessionId }
• Permissions — allowedTools pre-approves; permissionMode: 'acceptEdits' auto-approves edits only
• MCP — configure MCP servers via mcpServers in options
• Filesystem-based config — .claude/skills/*/SKILL.md, .claude/commands/*.md, CLAUDE.md all load automatically

Agent SDK vs Client SDK

Anthropic has two SDKs. Pick based on what you need:

Many teams use both: CLI for daily dev, Agent SDK for production automation.

Hooks example

Audit every file edit:

import { query } from '@anthropic-ai/claude-agent-sdk';
import { appendFile } from 'node:fs/promises';

for await (const message of query({
  prompt: 'Refactor utils.ts for readability.',
  options: {
    permissionMode: 'acceptEdits',
    hooks: {
      PostToolUse: [
        {
          matcher: 'Edit|Write',
          hooks: [
            async (input) => {
              const path = (input as any).tool_input?.file_path ?? 'unknown';
              await appendFile('./audit.log', `${new Date().toISOString()}: ${path}\n`);
              return {};
            },
          ],
        },
      ],
    },
  },
})) {
  console.log(message);
}

Sub-agents example

Delegate a code review to a specialized agent:

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Use the code-reviewer agent to review this codebase",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "code-reviewer": AgentDefinition(
                    description="Expert code reviewer for quality and security.",
                    prompt="Analyze code quality and flag any issues.",
                    tools=["Read", "Glob", "Grep"],
                ),
            },
        ),
    ):
        print(message)

Gotchas

• Same permissions pitfalls as Claude Code. allowedTools: ['Bash'] gives shell access — scope it or sandbox.
• Sessions are local. resume works within the same machine; for distributed workloads, roll your own session serialization.
• MCP context adds up. Every enabled MCP server adds tool schemas to every turn. Cap at 5–6.
• Branding guidance. If you ship a product on top of the SDK, Anthropic asks you not to call it "Claude Code" — use "Claude Agent" or your own name.

Further reading

• Official docs: code.claude.com/docs/en/agent-sdk/overview
• Quickstart
• Example agents — email assistant, research agent, and more
• TypeScript SDK + Python SDK
• Framework Comparison — Claude Agent SDK vs OpenAI Agents SDK vs Pydantic AI vs LangGraph