Getting Started with Claude Agent SDK | Implementation Guide for Python & TypeScript

What Is Claude Agent SDK?

Claude Agent SDK provides the same tools and context management features that power Claude Code as Python and TypeScript libraries. It was renamed from "Claude Code SDK" in 2026.

With a typical API client, your application must implement the loop of "call a tool → receive the result → call the API again." With Claude Agent SDK, a single call to query() lets Claude autonomously handle tool execution, result interpretation, and next-action decisions.

Supported platforms include the Anthropic API as well as Amazon Bedrock, Google Vertex AI, and Microsoft Azure AI Foundry.

Installation and Initial Setup

Installation is a single command.

# Python
pip install claude-agent-sdk

# TypeScript / Node.js
npm install @anthropic-ai/claude-agent-sdk

The TypeScript version bundles the native Claude Code binary, so there is no need to install the Claude Code CLI separately.

After installation, set the API key obtained from the Anthropic Console (https://platform.claude.com/) as an environment variable.

export ANTHROPIC_API_KEY=your-api-key

Basics of the query() Function

The entry point of Claude Agent SDK is the query() function. It returns an async iterator that streams messages in real time as Claude works.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="auth.py のバグを見つけて修正してください",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        print(message)

asyncio.run(main())

In TypeScript, you can write it the same way with a for await loop.

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

for await (const message of query({
  prompt: "Find and fix the bug in auth.ts",
  options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
  console.log(message);
}

The loop continues until Claude completes the task or encounters an error, streaming thoughts, tool calls, tool results, and the final output in sequence.

11 Built-in Tools

According to the official documentation (Agent SDK overview), Claude Agent SDK comes with the following built-in tools.

Simply pass the tool names you want to enable in allowedTools. Note that enabling the Agent tool allows the main agent to launch specialized sub-agents (see the "Distributing Complex Tasks with Sub-Agents" section below).

Customizing the Lifecycle with Hooks

Hooks let you inject arbitrary code before and after tool execution. Available hooks include PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, and UserPromptSubmit, among others.

The following example records the changed file path in an audit log every time Edit or Write is executed.

from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher
from datetime import datetime

async def log_file_change(input_data, tool_use_id, context):
    file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
    with open("./audit.log", "a") as f:
        f.write(f"{datetime.now()}: modified {file_path}\n")
    return {}

async def main():
    async for message in query(
        prompt="utils.py をリファクタリングしてください",
        options=ClaudeAgentOptions(
            permission_mode="acceptEdits",
            hooks={
                "PostToolUse": [
                    HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
                ]
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

Distributing Complex Tasks with Sub-Agents

With Claude Agent SDK, you can launch specialized sub-agents from the main agent to delegate work. Add "Agent" to allowed_tools and define sub-agents in the agents dictionary.

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="code-reviewer エージェントでコードレビューしてください",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "code-reviewer": AgentDefinition(
                    description="品質・セキュリティ専門のコードレビュアー",
                    prompt="コード品質を分析して改善点を提案してください。",
                    tools=["Read", "Glob", "Grep"],
                )
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

Messages within a sub-agent are tagged with a parent_tool_use_id field, making it easy to track what each sub-agent did.

Integrating with External Systems via MCP Servers

Connecting a Model Context Protocol (MCP) server enables integration with hundreds of services, including databases, browsers, and external APIs. The following example uses the Playwright MCP server to control a browser.

async for message in query(
    prompt="example.com を開いて内容を説明してください",
    options=ClaudeAgentOptions(
        mcp_servers={
            "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}
        }
    ),
):
    if hasattr(message, "result"):
        print(message.result)

Enabling Cross-Context Conversations with Session Management

By saving the session ID and passing it to the resume option, you can carry over the context from a previous conversation (files read, analysis results, conversation history) and continue working.

from claude_agent_sdk import SystemMessage

session_id = None
async for message in query(
    prompt="認証モジュールを読んでください",
    options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]),
):
    if isinstance(message, SystemMessage) and message.subtype == "init":
        session_id = message.data["session_id"]

# Continue in the same session
async for message in query(
    prompt="それを呼び出している箇所をすべて探してください",
    options=ClaudeAgentOptions(resume=session_id),
):
    ...

Controlling Safety with Permission Modes

The permission_mode option lets you change the agent's permission level (see Quickstart).

Differences from Client SDK, Claude Code CLI, and Managed Agents

The official documentation (Agent SDK overview) provides three comparisons.

Difference from Client SDK: With the Client SDK, your application implements the tool loop. With Claude Agent SDK, Claude autonomously manages the loop.

Difference from Claude Code CLI: They have equivalent capabilities, but the CLI is for interactive development while the SDK is for automating CI/CD pipelines and custom applications. Many teams use both for different purposes.

Difference from Managed Agents: Claude Agent SDK is a library where code runs on your own infrastructure. Managed Agents, on the other hand, is a hosted REST API where Anthropic manages the infrastructure. The recommended path is to prototype locally with the SDK, then migrate to Managed Agents for production.

In Practice: Building a Bug-Fix Agent

The official quickstart (Quickstart) walks through building a bug-fix agent in the following steps.

1. Install with pip install claude-agent-sdk or npm install @anthropic-ai/claude-agent-sdk
2. Set ANTHROPIC_API_KEY as an environment variable
3. Create a buggy sample file utils.py
4. Run a script that uses query() to request a bug fix

Claude reads the file with Read, analyzes the logic, and adds error handling with Edit. The biggest appeal is that the fix is complete without a human writing a single line of code.

If you are using Opus 4.7 (claude-opus-4-7), SDK version v0.2.111 or later is required. Older versions will produce a thinking.type.enabled API error. Note that as of the time of writing, the latest version is in the Opus 4.8 series (claude-opus-4-8), so 4.7 is not the latest. If you are using Opus 4.8, please use the latest version of the SDK (check the minimum supported version in the official release notes).

The full Claude Agent SDK documentation is available at https://code.claude.com/docs/en/agent-sdk/overview. For the Python reference, see Agent SDK reference - Python. For the TypeScript reference, see TypeScript SDK. GitHub samples are available at claude-agent-sdk-demos.