Claude Agent SDK — Overview

Formerly the Claude Code SDK. Gives you the same tools, agent loop, and context management that power Claude Code — programmable in Python and TypeScript.

Migration note: if you used the old Claude Code SDK, see the Migration Guide.

What It Is

The Agent SDK wraps Claude with built-in tool execution. Unlike the raw Anthropic Client SDK where you implement your own tool loop, the Agent SDK handles the loop autonomously:

# Client SDK — you manage the loop
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    result = your_tool_executor(response.tool_use)
    response = client.messages.create(tool_result=result, **params)

# Agent SDK — Claude handles tools autonomously
async for message in query(prompt="Fix the bug in auth.py"):
    print(message)

Quickstart (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"]),
    ):
        print(message)

asyncio.run(main())

Built-in Tools

Tool	What it does
Read	Read any file in the working directory
Write	Create new files
Edit	Make precise edits to existing files
Bash	Run terminal commands, scripts, git operations
Monitor	Watch a background script, react to each output line as an event
Glob	Find files by pattern (`*/.ts`, `src/*/.py`)
Grep	Search file contents with regex
WebSearch	Search the web for current information
WebFetch	Fetch and parse web page content
AskUserQuestion	Ask the user clarifying questions with multiple-choice options

Claude Code Features Available in SDK

The SDK loads .claude/ config from the working directory and ~/.claude/ by default. Use setting_sources / settingSources to restrict which sources load.

Feature	Description	Location
Skills	Specialized capabilities defined in Markdown	`.claude/skills/*/SKILL.md`
Slash commands	Custom commands for common tasks	`.claude/commands/*.md`
Memory	Project context and instructions	`CLAUDE.md` or `.claude/CLAUDE.md`
Plugins	Extend with custom commands, agents, MCP servers	Programmatic via `plugins` option

Also supports: Hooks, Subagents, MCP, Permissions, Sessions.

Model Requirements

Opus 4.7 (claude-opus-4-7) requires Agent SDK v0.2.111 or later
If you see a thinking.type.enabled API error → update the SDK

Agent SDK vs Client SDK

	Client SDK	Agent SDK
Tool loop	You implement	Claude handles
Setup	Direct API access	Built-in tool execution
Best for	Fine-grained control	Autonomous agents

Branding (for partners)

Allowed: "Claude Agent", "Claude", "Powered by Claude"
Not permitted: "Claude Code" or "Claude Code Agent", Claude Code ASCII art

Key Takeaways

The Agent SDK = Claude Code's internals as a library (Python + TypeScript)
No need to implement your own tool loop — Claude handles tool execution autonomously
All Claude Code features available: skills, memory, MCP, hooks, subagents
Tool permissions are set via allowed_tools in ClaudeAgentOptions
Config auto-loads from .claude/ and ~/.claude/ — restrict with setting_sources
Opus 4.7 needs SDK v0.2.111+
Governed by Anthropic's Commercial Terms of Service

wiki/tech-patterns/python-ai-agents — Claude/Gemini/OpenAI integration patterns used in Oliver projects
wiki/architecture/_index — multi-agent AI patterns and how agents are structured in production
wiki/obsidian-rag/_index — another agentic pattern: LLM-navigable knowledge base

Sources

raw/Agent SDK overview 1.md — clipped from code.claude.com/docs/en/agent-sdk/overview (2026-04-17)
raw/Agent SDK overview.md — duplicate clip, same source page (2026-04-17)

4.4 KiB Raw Blame History