Quickstart

Get started with the Python or TypeScript Agent SDK to build AI agents that work autonomously

Use the Agent SDK to build an AI agent that reads your code, finds bugs, and fixes them, all without manual intervention.

What you'll do:

Set up a project with the Agent SDK
Create a file with some buggy code
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

Create a project folder

Create a new directory for this quickstart:

mkdir my-agent
cd my-agent

For your own projects, you can run the SDK from any folder; it will have access to files in that directory and its subdirectories by default.

Install the SDK

Install the Agent SDK package for your language:

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

Setting "type": "module" in package.json lets your agent script use top-level await, and tsx runs TypeScript files directly.

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

tsx runs TypeScript files directly. If your project uses CommonJS, name your agent script agent.mts instead of agent.ts. The .mts extension makes tsx treat the file as an ES module, so top-level await works without converting your whole project to ES modules. Use agent.mts in place of agent.ts in the create and run steps later in this quickstart.

uv is a fast Python package manager that handles virtual environments automatically:

uv init
uv add claude-agent-sdk

Create and activate a virtual environment, then install the package.

On macOS or Linux:

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

On Windows:

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

If PowerShell blocks Activate.ps1 with an execution policy error, run Set-ExecutionPolicy -Scope Process RemoteSigned first.

Set your API key

Get an API key from the Claude Console, then set it as an environment variable in the shell where you'll run your agent:

export ANTHROPIC_API_KEY=your-api-key

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

The SDK reads the key from the environment of the process that runs your agent; it doesn't load .env files automatically. If you keep the key in a .env file, load it yourself, for example with the dotenv package, before calling the SDK.

The SDK also supports authentication via third-party API providers:

Amazon Bedrock: set CLAUDE_CODE_USE_BEDROCK=1 environment variable and configure AWS credentials
Claude Platform on AWS: set CLAUDE_CODE_USE_ANTHROPIC_AWS=1 and ANTHROPIC_AWS_WORKSPACE_ID, then configure AWS credentials
Google Vertex AI: set CLAUDE_CODE_USE_VERTEX=1 environment variable and configure Google Cloud credentials
Microsoft Azure: set CLAUDE_CODE_USE_FOUNDRY=1 environment variable and configure Azure credentials

See the setup guides for Bedrock, Claude Platform on AWS, Vertex AI, or Azure AI Foundry for details.

Create a buggy file

This quickstart walks you through building an agent that can find and fix bugs in code. First, you need a file with some intentional bugs for the agent to fix. Create utils.py in the my-agent directory and paste the following code:

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

This code has two bugs:

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

Build an agent that finds and fixes bugs

Create agent.py if you're using the Python SDK, or agent.ts for TypeScript. Use agent.mts instead if your existing project uses CommonJS:

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

import { query } from "@anthropic-ai/claude-agent-sdk";

// Agentic loop: streams messages as Claude works
for await (const message of query({
prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options: {
allowedTools: ["Read", "Edit", "Glob"], // Auto-approve these tools
permissionMode: "acceptEdits" // Auto-approve file edits
}
})) {
// Print human-readable output
if (message.type === "assistant" && message.message?.content) {
for (const block of message.message.content) {
if ("text" in block) {
console.log(block.text); // Claude's reasoning
} else if ("name" in block) {
console.log(`Tool: ${block.name}`); // Tool being called
}
}
} else if (message.type === "result") {
console.log(`Done: ${message.subtype}`); // Final result
}
}

This code has three main parts:

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.
prompt: what you want Claude to do. Claude figures out which tools to use based on the task.
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.

The async for loop keeps running as Claude thinks, calls tools, observes results, and decides what to do next. Each iteration yields a message: Claude's reasoning, a tool call, a tool result, or the final outcome. The SDK handles the orchestration (tool execution, context management, retries) so you just consume the stream. The loop ends when Claude finishes the task or hits an error.

The message handling inside the loop filters for human-readable output. Without filtering, you'd see raw message objects including system initialization and internal state, which is useful for debugging but noisy otherwise.

Run your agent

Your agent is ready. Run it with the following command:

npx tsx agent.ts

If you named your script agent.mts, run npx tsx agent.mts instead.

uv run agent.py

With your virtual environment still activated:

python agent.py

As it works, the agent prints its reasoning and each tool it calls, ending with Done: success. After running, check utils.py. You'll see defensive code handling empty lists and null users. Your agent autonomously:

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

This is what makes the Agent SDK different: Claude executes tools directly instead of asking you to implement them.

Try other prompts

Now that your agent is set up, try some different 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

You can modify your agent's behavior by changing the options. Here are a few examples:

Add web search capability:

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

const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob", "WebSearch"],
permissionMode: "acceptEdits"
}
};

Give Claude a 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 style guidelines.",
)

const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob"],
permissionMode: "acceptEdits",
systemPrompt: "You are a senior Python developer. Always follow PEP 8 style guidelines."
}
};

Run commands in the terminal:

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

const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob", "Bash"],
permissionMode: "acceptEdits"
}
};

With Bash enabled, try: "Write unit tests for utils.py, run them, and fix any failures"

Key concepts

Tools control what your agent can do:

Tools	What the agent can do
`Read`, `Glob`, `Grep`	Read-only analysis
`Read`, `Edit`, `Glob`	Analyze and modify code
`Read`, `Edit`, `Bash`, `Glob`, `Grep`	Full automation

Permission modes control how much human oversight you want:

Mode	Behavior	Use case
`acceptEdits`	Auto-approves file edits and common filesystem commands, asks for other actions	Trusted development workflows
`plan`	Runs read-only tools; file edits are never auto-approved and reach your `canUseTool` callback	Scoping a task before approving execution
`dontAsk`	Denies anything not in `allowedTools`	Locked-down headless agents
`auto` (TypeScript only)	A model classifier approves or denies each tool call	Autonomous agents with safety guardrails
`bypassPermissions`	Runs every tool without prompting, unless an explicit `ask` rule matches	Sandboxed CI, fully trusted environments
`default`	Requires a `canUseTool` callback to handle approval	Custom approval flows

The example above uses acceptEdits mode, which auto-approves file operations so the agent can run without interactive prompts. If you want to prompt users for approval, use default mode and provide a canUseTool callback that collects user input. For more control, see Permissions.

Next steps

Now that you've created your first agent, learn how to extend its capabilities and tailor it to your use case:

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

agent-sdk/quickstart.md +36 −19

37 Install the Agent SDK package for your language:37 Install the Agent SDK package for your language:

38 38

39 <Tabs>39 <Tabs>

~~40 <Tab title="TypeScript">~~40 <Tab title="TypeScript (new project)">

41 ```bash theme={null}

42 npm init -y

43 npm pkg set type=module

44 npm install @anthropic-ai/claude-agent-sdk

45 npm install --save-dev tsx

46 ```

48 Setting `"type": "module"` in `package.json` lets your agent script use top-level `await`, and [tsx](https://tsx.is) runs TypeScript files directly.

49 </Tab>

51 <Tab title="TypeScript (existing project)">

41 ```bash theme={null}52 ```bash theme={null}

42 npm install @anthropic-ai/claude-agent-sdk53 npm install @anthropic-ai/claude-agent-sdk

54 npm install --save-dev tsx

43 ```55 ```

57 [tsx](https://tsx.is) runs TypeScript files directly. If your project uses CommonJS, name your agent script `agent.mts` instead of `agent.ts`. The `.mts` extension makes tsx treat the file as an ES module, so top-level `await` works without converting your whole project to ES modules. Use `agent.mts` in place of `agent.ts` in the create and run steps later in this quickstart.

44 </Tab>58 </Tab>

45 59

46 <Tab title="Python (uv)">60 <Tab title="Python (uv)">

81 </Step>95 </Step>

82 96

83 <Step title="Set your API key">97 <Step title="Set your API key">

~~84 Get an API key from the [Claude Console](https://platform.claude.com/), then create a `.env` file in your project directory:~~98 Get an API key from the [Claude Console](https://platform.claude.com/), then set it as an environment variable in the shell where you'll run your agent:

85 99

100 <Tabs>

101 <Tab title="macOS / Linux">

86 ```bash theme={null}102 ```bash theme={null}

~~87 ANTHROPIC_API_KEY=your-api-key~~103 export ANTHROPIC_API_KEY=your-api-key

88 ```104 ```

105 </Tab>

106

107 <Tab title="Windows (PowerShell)">

108 ```powershell theme={null}

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

110 ```

111 </Tab>

112 </Tabs>

113

114 The SDK reads the key from the environment of the process that runs your agent; it doesn't load `.env` files automatically. If you keep the key in a `.env` file, load it yourself, for example with the `dotenv` package, before calling the SDK.

89 115

90 The SDK also supports authentication via third-party API providers:116 The SDK also supports authentication via third-party API providers:

91 117

125 151

126## Build an agent that finds and fixes bugs152## Build an agent that finds and fixes bugs

127 153

128Create `agent.py` if you're using the Python SDK, or `agent.ts` for TypeScript:154Create `agent.py` if you're using the Python SDK, or `agent.ts` for TypeScript. Use `agent.mts` instead if your existing project uses CommonJS:

129 155

130<CodeGroup>156<CodeGroup>

131 ```python Python theme={null}157 ```python Python theme={null}

208 ```bash theme={null}234 ```bash theme={null}

209 npx tsx agent.ts235 npx tsx agent.ts

210 ```236 ```

237

238 If you named your script `agent.mts`, run `npx tsx agent.mts` instead.

211 </Tab>239 </Tab>

212 240

213 <Tab title="Python (uv)">241 <Tab title="Python (uv)">

225 </Tab>253 </Tab>

226</Tabs>254</Tabs>

227 255

228After running, check `utils.py`. You'll see defensive code handling empty lists and null users. Your agent autonomously:256As it works, the agent prints its reasoning and each tool it calls, ending with `Done: success`. After running, check `utils.py`. You'll see defensive code handling empty lists and null users. Your agent autonomously:

229 257

2301. **Read** `utils.py` to understand the code2581. **Read** `utils.py` to understand the code

2312. **Analyzed** the logic and identified edge cases that would crash2592. **Analyzed** the logic and identified edge cases that would crash

234This is what makes the Agent SDK different: Claude executes tools directly instead of asking you to implement them.262This is what makes the Agent SDK different: Claude executes tools directly instead of asking you to implement them.

235 263

236<Note>264<Note>

237 If you see "API key not found", make sure you've set the `ANTHROPIC_API_KEY` environment variable in your `.env` file or shell environment. See the [full troubleshooting guide](/en/troubleshooting) for more help.265 If you see "API key not found", make sure you've set the `ANTHROPIC_API_KEY` environment variable in the shell where you run your agent. The SDK doesn't load `.env` files automatically. See the [full troubleshooting guide](/en/troubleshooting) for more help.

238</Note>266</Note>

239 267

240### Try other prompts268### Try other prompts

324**Permission modes** control how much human oversight you want:352**Permission modes** control how much human oversight you want:

325 353

327| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |355| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |

357| `plan` | Runs read-only tools; file edits are never auto-approved and reach your `canUseTool` callback | Scoping a task before approving execution |

331| `bypassPermissions` | Runs every tool without prompting, unless an explicit [`ask` rule](/en/agent-sdk/permissions#how-permissions-are-evaluated) matches | Sandboxed CI, fully trusted environments |360| `bypassPermissions` | Runs every tool without prompting, unless an explicit [`ask` rule](/en/agent-sdk/permissions#how-permissions-are-evaluated) matches | Sandboxed CI, fully trusted environments |

333 362

334The example above uses `acceptEdits` mode, which auto-approves file operations so the agent can run without interactive prompts. If you want to prompt users for approval, use `default` mode and provide a [`canUseTool` callback](/en/agent-sdk/user-input) that collects user input. For more control, see [Permissions](/en/agent-sdk/permissions).363The example above uses `acceptEdits` mode, which auto-approves file operations so the agent can run without interactive prompts. If you want to prompt users for approval, use `default` mode and provide a [`canUseTool` callback](/en/agent-sdk/user-input) that collects user input. For more control, see [Permissions](/en/agent-sdk/permissions).

335 364

336## Troubleshooting

~~337~~

338### API error `thinking.type.enabled` is not supported for this model

~~339~~

340Claude Opus 4.7 replaces `thinking.type.enabled` with `thinking.type.adaptive`. Older Agent SDK versions fail with the following API error when you select `claude-opus-4-7`:

~~341~~

342```text theme={null}

343API Error: 400 {"type":"invalid_request_error","message":"\"thinking.type.enabled\" is not supported for this model. Use \"thinking.type.adaptive\" and \"output_config.effort\" to control thinking behavior."}

344```

~~345~~

346Upgrade to Agent SDK v0.2.111 or later to use Opus 4.7.

~~347~~

348## Next steps365## Next steps

349 366

350Now that you've created your first agent, learn how to extend its capabilities and tailor it to your use case:367Now that you've created your first agent, learn how to extend its capabilities and tailor it to your use case:

agent-sdk/quickstart.md 2026-06-25 23:58 UTC to 2026-06-26 23:00 UTC

Quickstart

Prerequisites

Setup

Create a project folder

Install the SDK

Set your API key

Create a buggy file

Build an agent that finds and fixes bugs

Run your agent

Try other prompts

Customize your agent

Key concepts

Next steps