128 lines
4.6 KiB
Markdown
128 lines
4.6 KiB
Markdown
---
|
|
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*
|