Developing Claude Agent Sdk Agents

The Claude Agent SDK enables building autonomous AI agents that can:

• Execute multi-turn conversations with tool use
• Read, write, and edit files in a working directory
• Run shell commands
• Integrate with external services via MCP
• Spawn specialized subagents

1. Streaming is Primary

The SDK operates as a streaming API. You iterate over messages as they're generated:

// TypeScript
for await (const message of query({ prompt: "...", options })) {
  // Handle each message type
}

# Python
async for message in query(prompt="...", options=options):
    # Handle each message type

2. System Prompt is Empty by Default

The SDK uses an empty system prompt by default. To get Claude Code's full capabilities:

systemPrompt: { type: "preset", preset: "claude_code" }

3. Settings Sources Must Be Explicit

CLAUDE.md, skills, and slash commands are NOT loaded by default. You must specify:

settingSources: ["user", "project"]  // TypeScript
setting_sources=["user", "project"]  # Python

4. Permission Modes Control Tool Access

Choose permission mode based on your use case:

• default - Interactive approval
• acceptEdits - Auto-approve file changes
• bypassPermissions - Skip all permission checks (use with care)

5. MCP Tools Require Streaming Input

Custom MCP tools require streaming input mode (async generator), not simple strings.

Install:

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

Basic agent:

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

for await (const msg of query({
  prompt: "Read package.json and summarize the dependencies",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" },
    allowedTools: ["Read", "Grep", "Glob"],
    maxTurns: 5
  }
})) {
  if (msg.type === "result") console.log(msg.result);
}

For detailed guidance, select a workflow below.

1. Build a new agent from scratch
2. Add custom tools (MCP servers)
3. Implement hooks for behavior modification
4. Configure permissions and security
5. Deploy an agent to production
6. Debug an agent issue
7. Something else

Then read the matching workflow from workflows/ and follow it.

After reading the workflow, follow it exactly.

# TypeScript
npx tsc --noEmit  # Type check
npm test          # Run tests

# Python
python -m mypy .  # Type check
pytest            # Run tests

Test the agent interactively:

npx tsx my-agent.ts    # TypeScript
python my_agent.py     # Python

Report to the user:

• "Type check: OK/X errors"
• "Tests: X pass, Y fail"
• "Agent runs and responds correctly"

All in references/:

Core:

• sdk-overview.md - Architecture, installation, message types, API comparison
• built-in-tools.md - Read, Write, Edit, Bash, Glob, Grep, MCP tools

Features:

• hooks.md - Lifecycle hooks, callbacks, patterns
• subagents.md - Creating and spawning subagents
• mcp-and-custom-tools.md - MCP servers, custom tool definition
• permissions.md - Permission modes, tool restrictions, canUseTool
• sessions.md - Resuming, forking, context management

Advanced:

• patterns-and-features.md - Streaming modes, structured outputs, checkpointing
• filesystem-features.md - Skills, slash commands, CLAUDE.md, plugins
• hosting-and-deployment.md - Docker, sandboxing, production patterns
• debugging.md - Common issues and solutions

All in workflows/: