Claude Agent SDK Tutorial: Build Your First Agent

Steps

1. 01

   Install the SDK

   Pick your language. The TypeScript package is @anthropic-ai/claude-agent-sdk (it pulls in the Claude Code CLI as a dependency). The Python package is claude-agent-sdk — note the rename from the old claude-code-sdk, which is frozen and no longer updated.

   # TypeScript / Node
   npm install @anthropic-ai/claude-agent-sdk
   
   # Python
   pip install claude-agent-sdk

2. 02

   Set your Claude credential

   The SDK needs Claude model access. The simplest path is an API key from console.anthropic.com exported as an environment variable. Alternatively, if you already pay for Claude, run the Claude Code CLI once (claude) and complete the browser login — the SDK reuses that session.

   export ANTHROPIC_API_KEY="sk-ant-..."

3. 03

   Write your first agent (TypeScript)

   Create agent.ts. The query() function takes a prompt plus an options object and returns an async stream of messages — the agent's text, its tool calls, and a final result message. Here we just print the final result.

   import { query } from "@anthropic-ai/claude-agent-sdk";
   
   for await (const message of query({
     prompt: "Summarize what this project does, then list any TODO comments.",
     options: { model: "claude-opus-4-8" },
   })) {
     if (message.type === "result") {
       console.log(message.result);
     }
   }

4. 04

   Write your first agent (Python)

   Or create agent.py. The Python query() is an async generator with the same shape: pass a prompt and a ClaudeAgentOptions object, then iterate the messages it yields.

   import anyio
   from claude_agent_sdk import query, ClaudeAgentOptions
   
   async def main():
       async for message in query(
           prompt="Summarize what this project does, then list any TODO comments.",
           options=ClaudeAgentOptions(model="claude-opus-4-8"),
       ):
           print(message)
   
   anyio.run(main)

5. 05

   Run it

   Run from the directory you want the agent to work in — it reads and acts on files relative to your current working directory. The agent will explore the project and stream back its result.

   # TypeScript (via tsx, or compile first)
   npx tsx agent.ts
   
   # Python
   python agent.py

6. 06

   Give the agent a role and scope its tools

   For real work, set a system prompt, restrict which tools the agent may use, and keep the permission mode on so risky actions are gated. The options below make a read-only reviewer that cannot edit files. (The option names model, systemPrompt, allowedTools and permissionMode are verified against @anthropic-ai/claude-agent-sdk 0.3.185; see the SDK reference for the full list.)

   const result = query({
     prompt: "Review the auth module and suggest fixes. Do not edit files.",
     options: {
       model: "claude-opus-4-8",
       systemPrompt: "You are a meticulous senior code reviewer.",
       allowedTools: ["Read", "Grep", "Glob"],
       permissionMode: "default",
     },
   });

7. 07

   Where to go next

   From here you can connect MCP servers to give the agent external tools (GitHub, Figma, databases), and delegate focused work to subagents to keep context lean and run tasks in parallel. The model is configurable too — claude-opus-4-8 for the hardest agentic work, claude-sonnet-4-6 for a balance of speed and cost, claude-haiku-4-5 for fast, simple tasks.

Troubleshooting

Error: the claude binary / Claude Code was not found

The SDK drives the Claude Code agent harness. The npm package installs it as a dependency; for the Python SDK install it yourself with npm i -g @anthropic-ai/claude-code and confirm claude --version works, so the binary is on your PATH.

401 / authentication error when you run the agent

No Claude credential was found. Export ANTHROPIC_API_KEY (from console.anthropic.com), or run the claude CLI once and complete the login so the SDK can reuse the session. Make sure the variable is set in the same shell that runs the script.

404 / model not found

Use a current model id in your options: claude-opus-4-8, claude-sonnet-4-6, or claude-haiku-4-5. Do not append date suffixes to these aliases.

ModuleNotFoundError: No module named 'claude_agent_sdk'

Install the renamed package: pip install claude-agent-sdk. If you installed the old claude-code-sdk, its import path is claude_code_sdk and it is frozen at 0.0.25 — migrate to claude-agent-sdk (import claude_agent_sdk).