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.