Quickstart - Claude Code Docs
Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. 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.14+ or Python 3.10+ An Anthropic account .
If you don’t have one, sign up here . Setup 1 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. 2 Install the SDK Install the Agent SDK package for your language: TypeScript (new project) TypeScript (existing project) Python (uv) Python (pip) 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 prints added N packages when the install succeeds. 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. Install uv , a fast Python package manager that handles virtual environments automatically. Then initialize a project and add the SDK: 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. Both the TypeScript and Python SDKs bundle a native Claude Code binary, so most installs need no separate Claude Code install.
Some installs have no bundled binary: If pip installs the Python SDK’s source distribution instead of a platform wheel, for example on ARM64 Windows, no binary is bundled. Install Claude Code natively . The Python SDK finds it on your PATH . The TypeScript SDK installs its binary through npm optional dependencies, so an install that skips them, for example npm ci --omit=optional , gets no binary even on a supported platform.
Reinstall without skipping optional dependencies, or install Claude Code natively and set pathToClaudeCodeExecutable to its path. 3 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: macOS / Linux Windows (PowerShell) 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 Cloud’s Agent Platform : set CLAUDE_CODE_USE_VERTEX=1 environment variable and configure Google Cloud credentials Microsoft Foundry : set CLAUDE_CODE_USE_FOUNDRY=1 environment variable and configure Azure credentials See the setup guides for Amazon Bedrock , Claude Platform on AWS , Google Cloud’s Agent Platform , or Microsoft Foundry for details.
Unless previously approved, Anthropic does not allow third party developers to offer claude.ai login or rate limits for their products, including agents built on the Claude Agent SDK. Use the API key authentication methods described in this document instead. 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, and retries, so you 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. This example prints Claude�
The rest of this page is on the live site.