Claude Agent SDK

Overview

The Claude Agent SDK is Anthropic’s toolkit for building autonomous AI agents that can read/edit files, execute bash commands, search the web, and interact with external services via the Model Context Protocol (MCP). It provides the same infrastructure that powers Claude Code, enabling developers to build custom AI agents for any domain—not just coding.

Origin: Originally named “Claude Code SDK,” it was renamed to “Claude Agent SDK” to reflect its broader applicability beyond software development. Anthropic discovered the agent harness was equally effective for research, video creation, note-taking, and countless other non-coding applications.

Release Timeline

Initial Release (2025)

2025-09-29: Official announcement alongside Claude Sonnet 4.5
2025-09-28: Version 0.1.0 released (production-ready with breaking changes from old Claude Code SDK)
November-December 2025: Rapid iteration with 17+ releases (v0.1.1 through v0.1.17)
- 2025-11-19: Claude Code CLI bundled in pip package (v0.1.8)
- Multiple stability improvements and feature additions

TypeScript V2 Interface (Late 2025)

Preview release of redesigned TypeScript API
Simplified session-based send/receive pattern
Supports 1M context window
Sandboxing improvements
Status: Preview with unstable_v2_* prefix, APIs may change

Current Version: 0.1.x (the “v2” designation applies only to TypeScript interface preview, not entire SDK)

Key Features

Core Infrastructure

Agent Loop: Automated feedback cycle (Gather context → Take action → Verify work → Repeat)
Context Management: Automatic compaction prevents context limit issues
Session Management: Persistent conversations with resume capability
Permission System: Fine-grained control over agent capabilities

Tools and Actions

File Operations: Read, write, edit files with change tracking
Code Execution: Bash commands and script execution in sandboxed environments
Web Search: Built-in web search capabilities
MCP Integration: Connect to databases, APIs, and services (Slack, GitHub, Asana, etc.)
Custom Tools: Define domain-specific tools for specialized tasks

Advanced Features

Subagents: Isolated context windows for parallel processing
Hooks: Intercept and modify agent behavior at key points
Skills: Reusable agent capabilities
Slash Commands: Custom commands for workflow automation
Prompt Caching: Reduce costs and latency with automatic caching
1M Context Window Support: Handle extensive conversations and documentation (late 2025)

Agent Loop Architecture

The SDK implements a structured feedback loop:

1. Gather Context

Agentic search using bash commands (grep, tail, find)
Semantic search for faster retrieval
File system operations

2. Take Action

Custom tools (primary action mechanism)
Bash/script execution for flexible computer work
Code generation for precise, reusable operations

3. Verify Work

Rules-based feedback (linting, testing)
Visual feedback (screenshots, renders)
LLM-as-judge for fuzzy criteria

4. Repeat

Iterate until success or termination condition

TypeScript V2 Interface (Preview)

Major Improvements from V1

V1 Approach:

Used async generators with yield coordination
Input and output flow through single async generator
Complex state management across turns
Required restructuring for multi-turn conversations

V2 Approach:

Session-based send/receive pattern
Explicit separation of sending and receiving
Each turn is separate send()/receive() cycle
Simplified multi-turn conversation management

V2 API Simplification

Reduced to three concepts:

createSession() / resumeSession() - Start or continue conversations
session.send() - Send messages
session.receive() - Get responses

Example Comparison

// V1: Multi-turn requires async iterable coordination  
async function* createInputStream() {  
  yield { type: 'user', message: {...} }  
  // Must coordinate when to yield next message  
  yield { type: 'user', message: {...} }  
}  
  
// V2: Simple send/receive pattern  
await session.send('What is 5 + 3?')  
for await (const msg of session.receive()) { ... }  
  
await session.send('Multiply that by 2')  
for await (const msg of session.receive()) { ... }

V2 Benefits

Easier to add logic between turns
Better session lifecycle management with TypeScript 5.2+ await using syntax
Clearer intent with explicit send/receive operations
Simplified session resumption with dedicated resumeSession() method

V2 Limitations

Not all V1 features available yet (session forking requires V1)
Still in preview status with unstable_v2_* prefix
APIs may change based on feedback

Breaking Changes (Claude Code SDK → Claude Agent SDK)

1. Package Renaming

TypeScript: @anthropic-ai/claude-code → @anthropic-ai/claude-agent-sdk
Python: claude-code-sdk → claude-agent-sdk

2. System Prompt Change

Old: Claude Code system prompt included by default
New: Empty system prompt by default (opt-in to Claude Code preset)

3. Settings Sources

Old: Automatically loaded from filesystem (CLAUDE.md, settings.json, slash commands)
New: No settings loaded by default (must explicitly specify settingSources)

Rationale: Better isolation for SDK applications, ensuring predictable behavior independent of local configurations—critical for CI/CD, deployed applications, and multi-tenant systems.

Installation

Python

pip install claude-agent-sdk

TypeScript/JavaScript

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

Usage Examples

Python SDK

from claude_agent_sdk import query, ClaudeAgentOptions  
  
options = ClaudeAgentOptions(  
    model="claude-sonnet-4-5-20250929",  
    permission_mode="acceptEdits",  
    setting_sources=["project"]  
)  
  
async for message in query(prompt="Task", options=options):  
    print(message)

TypeScript SDK (V2)

import { unstable_v2_createSession } from '@anthropic-ai/claude-agent-sdk'  
  
await using session = unstable_v2_createSession({  
  model: 'claude-sonnet-4-5-20250929'  
})  
  
await session.send('Task')  
for await (const msg of session.receive()) {  
  // Process messages  
}

Use Cases

Coding & Development Agents

SRE Agents: Diagnose and fix production issues autonomously
Security Review Bots: Audit code for vulnerabilities
Oncall Engineering Assistants: Triage incidents and gather diagnostics
Code Review Agents: Enforce style guides and best practices

Business Agents

Legal Assistants: Review contracts, check compliance, extract clauses
Finance Advisors: Analyze reports, evaluate investments, access external APIs
Customer Support Agents: Handle complex requests, access user data, resolve technical issues

Specialized Applications

Personal Assistants: Book travel, manage calendars, coordinate schedules
Research Agents: Synthesize information from large document collections
Content Creation: Multi-agent pipelines (research → draft → edit → visuals)
Market Analysis: Track live trends across industries (startups, AI, finance, sustainability)

Real-World Examples

Multi-Agent Documentation Workflow: 7-subagent pipeline reducing time from 23 hours → 5 hours
InspireBot CLI: Web search with custom fallback tools
NoteSmith: Multi-tool note-taking with usage tracking
TrendSmith: Live market trend tracking
Blog Outline Generator: One-shot content planning

Context Management

Automatic Compaction

Summarizes previous messages when approaching context limit
Prevents agents from running out of context during long tasks

Subagents for Isolation

Independent context windows for parallel processing
Send only relevant information back to orchestrator
Ideal for sifting through large amounts of information

Memory System

CLAUDE.md files for project-level instructions
~/.claude/CLAUDE.md for user-level preferences
Session persistence and resumption by ID

Production Features

Error Handling

Built-in error recovery mechanisms
Graceful degradation on tool failures

Performance Optimizations

Automatic prompt caching
Reduced latency and costs
Improved throughput

Monitoring & Observability

Session tracking
Tool usage metrics
Error reporting

Security & Permissions

Fine-grained control over allowed tools
Permission modes (accept edits, require approval, etc.)
Sandbox environments for code execution

Relationship to Claude Code

Foundational: The Claude Agent SDK is the programmatic interface to Claude Code’s underlying technology. Claude Code (the CLI tool) is built on top of this same infrastructure.

Bundling: The Claude Code CLI is automatically bundled with the SDK package—no separate installation required.

Shared Capabilities: Both use identical:

Tool ecosystem
Agent loop architecture
Context management systems
Permission frameworks

Key Difference:

Claude Code: End-user CLI tool for direct interaction
Claude Agent SDK: Developer framework for building custom agents programmatically

Explorer