Agent SDK Quickstart

Build an AI agent that autonomously reads, analyzes, and fixes code — no manual intervention.

Prerequisites

Python 3.10+ or Node.js 18+
Anthropic account with ANTHROPIC_API_KEY set

Minimal Agent (Python)

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")

asyncio.run(main())

Three Core Parts

Part	What it does
`query()`	Main entry point — creates the agentic loop, returns an async iterator
`prompt`	Natural language task — Claude decides which tools to call
`options`	Config: `allowed_tools`, `permission_mode`, `system_prompt`, `mcpServers`

Tools Reference

Tools	Agent capability
`Read`, `Glob`, `Grep`	Read-only analysis
`Read`, `Edit`, `Glob`	Analyze and modify code
`Read`, `Edit`, `Bash`, `Glob`, `Grep`	Full automation
+ `WebSearch`	Add web search capability

Permission Modes

Mode	Behavior	Use case
`acceptEdits`	Auto-approves file edits + common FS commands	Trusted dev workflows
`dontAsk`	Denies anything not in `allowedTools`	Locked-down headless agents
`auto` (TS only)	Model classifier approves/denies each tool call	Autonomous with guardrails
`bypassPermissions`	No prompts at all	Sandboxed CI
`default`	Requires `canUseTool` callback	Custom approval flows

Customization Examples

Custom system prompt:

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="You are a senior Python developer. Always follow PEP 8.",
)

Add Bash for full automation:

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"],
    permission_mode="acceptEdits",
)
# Prompt: "Write unit tests for utils.py, run them, and fix any failures"

Message Stream Types

The async for loop yields four message types:

AssistantMessage — Claude's reasoning text + tool calls
Tool result — output from each tool execution
ResultMessage — final outcome (subtype = success/error/etc.)
System/internal state (filter out for clean output)

See wiki/agent-sdk/agent-loop for the full message lifecycle.

Troubleshooting

Error	Fix
`API key not found`	Set `ANTHROPIC_API_KEY` env var
`thinking.type.enabled not supported`	Upgrade to Agent SDK v0.2.111+ (Opus 4.7 changed to `thinking.type.adaptive`)

Key Takeaways

query() is the single entry point — it drives the full agentic loop with async for
allowed_tools pre-approves tools; permission_mode="acceptEdits" removes interactive prompts
The loop ends when Claude finishes the task or hits an error — SDK handles orchestration
Streaming (async for) is for real-time output; collect all messages for background/CI jobs
system_prompt and mcpServers in ClaudeAgentOptions are the main extension points

Next Steps

wiki/agent-sdk/configure-permissions — full permission modes + allow/deny rules
wiki/agent-sdk/sdk-hooks — intercept tool calls with PreToolUse/PostToolUse
wiki/agent-sdk/mcp-integration — connect to databases, browsers, external APIs
wiki/agent-sdk/hosting-production — deploy to Docker, cloud, CI/CD
wiki/agent-sdk/user-input-approvals — canUseTool callback for custom approval flows
wiki/agent-sdk/agent-loop — understand message lifecycle and context management

Source: raw/Quickstart.md

4.6 KiB Raw Permalink Blame History