---
title: "Agent SDK Quickstart"
aliases: [agent-sdk-quickstart, sdk-quickstart, getting-started-agent-sdk]
tags: [agent-sdk, quickstart, python, typescript, anthropic, claude]
sources: [raw/Quickstart.md]
created: 2026-04-17
updated: 2026-04-17
---

# 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)

```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:**
```python
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:**
```python
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:
1. **AssistantMessage** — Claude's reasoning text + tool calls
2. **Tool result** — output from each tool execution
3. **ResultMessage** — final outcome (`subtype` = success/error/etc.)
4. System/internal state (filter out for clean output)

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

---

*Source: raw/Quickstart.md*