Quickstart

1. Set up a project with the Agent SDK
2. Create a file with some buggy code
3. Run an agent that finds and fixes the bugs automatically

​

Prerequisites

• Node.js 18+ or Python 3.10+
• An Anthropic account (sign up here)

​

Setup

mkdir my-agent
cd my-agent

npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

uv init
uv add claude-agent-sdk

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk

export ANTHROPIC_API_KEY=your-api-key

$env:ANTHROPIC_API_KEY = "your-api-key"

​

Create a buggy file

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)


def get_user_name(user):
    return user["name"].upper()

1. calculate_average([]) crashes with division by zero
2. get_user_name(None) crashes with a TypeError

​

Build an agent that finds and fixes bugs

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


async def main():
    # Agentic loop: streams messages as Claude works
    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"],  # Auto-approve these tools
            permission_mode="acceptEdits",  # Auto-approve file edits
        ),
    ):
        # Print human-readable output
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)  # Claude's reasoning
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")  # Tool being called
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")  # Final result


asyncio.run(main())

1. query: the main entry point that creates the agentic loop. It returns an async iterator, so you use async for to stream messages as Claude works. See the full API in the Python or TypeScript SDK reference.
2. prompt: what you want Claude to do. Claude figures out which tools to use based on the task.
3. options: configuration for the agent. This example uses allowedTools to pre-approve Read, Edit, and Glob, and permissionMode: "acceptEdits" to auto-approve file changes. Other options include systemPrompt, mcpServers, and more. See all options for Python or TypeScript.

​

Run your agent

npx tsx agent.ts

uv run agent.py

python agent.py

1. Read utils.py to understand the code
2. Analyzed the logic and identified edge cases that would crash
3. Edited the file to add proper error handling

​

Try other prompts

• "Add docstrings to all functions in utils.py"
• "Add type hints to all functions in utils.py"
• "Create a README.md documenting the functions in utils.py"

​

Customize your agent

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"], permission_mode="acceptEdits"
)

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

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"], permission_mode="acceptEdits"
)

​

Key concepts

​

Next steps

• Permissions: control what your agent can do and when it needs approval
• Hooks: run custom code before or after tool calls
• Sessions: build multi-turn agents that maintain context
• MCP servers: connect to databases, browsers, APIs, and other external systems
• Hosting: deploy agents to Docker, cloud, and CI/CD
• Example agents: see complete examples: email assistant, research agent, and more