claude-agent-sdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Agent SDK

Overview

概述

The Claude Agent SDK enables building autonomous AI agents with Claude through a feedback loop architecture. Available for Python (3.10+) and TypeScript (Node 18+).

Repository:

Python: https://github.com/anthropics/claude-agent-sdk-python
TypeScript: https://github.com/anthropics/claude-agent-sdk-typescript

Documentation: https://platform.claude.com/docs/en/agent-sdk/overview

Claude Agent SDK 支持通过反馈循环架构基于Claude构建自主AI Agent，支持Python（3.10+）和TypeScript（Node 18+）版本。

代码仓库：

Python: https://github.com/anthropics/claude-agent-sdk-python
TypeScript: https://github.com/anthropics/claude-agent-sdk-typescript

官方文档： https://platform.claude.com/docs/en/agent-sdk/overview

Installation

安装

bash

undefined

bash

undefined

Python

pip install claude-agent-sdk

TypeScript

npm install @anthropic-ai/agent-sdk

undefined

npm install @anthropic-ai/agent-sdk

undefined

Core Architecture: Feedback Loop Pattern

核心架构：反馈循环模式

Every agent follows this cycle:

Gather Context → filesystem navigation, subagents, tools
Take Action → tools, bash, code generation, MCP
Verify Work → rules-based, visual, LLM-as-judge
Repeat → iterate until completion

This pattern applies whether you're building a simple script or a complex multi-agent system.

所有Agent都遵循以下执行周期：

收集上下文 → 文件系统导航、子Agent、工具调用
执行动作 → 工具调用、bash命令、代码生成、MCP
验证结果 → 基于规则校验、可视化校验、LLM-as-Judge校验
循环迭代 → 重复上述步骤直到任务完成

无论你是构建简单脚本还是复杂的多Agent系统，都适用该模式。

Execution Mechanisms (Priority Order)

执行机制（优先级排序）

Choose mechanisms based on task requirements:

Custom Tools → Primary workflows (appear prominently in context)
Bash → Flexible one-off operations
Code Generation → Complex, reusable outputs (prefer TypeScript for linting feedback)
MCP → Pre-built external integrations (Slack, GitHub, databases)

Rule: Use tools for repeatable operations, bash for exploration, code generation when you need structured output that can be validated.

根据任务需求选择对应执行机制：

自定义工具 → 核心工作流（会在上下文中优先展示）
Bash命令 → 灵活的一次性操作
代码生成 → 复杂可复用输出（优先使用TypeScript获取linting反馈）
MCP → 预构建的外部集成（Slack、GitHub、数据库）

规则： 可重复操作使用工具，探索性操作使用bash，需要可验证结构化输出时使用代码生成。

Quick Start Patterns

快速入门示例

Python: Basic Query

Python：基础查询

python

from claude_agent_sdk import query

result = await query(
    model="claude-sonnet-4-5",
    system_prompt="You are a helpful coding assistant.",
    user_message="List files in current directory",
    working_dir=".",
)
print(result.final_message)

python

from claude_agent_sdk import query

result = await query(
    model="claude-sonnet-4-5",
    system_prompt="You are a helpful coding assistant.",
    user_message="List files in current directory",
    working_dir=".",
)
print(result.final_message)

TypeScript: Session Management

TypeScript：会话管理

typescript

import { ClaudeSdkClient } from '@anthropic-ai/agent-sdk';

const client = new ClaudeSdkClient({ apiKey: process.env.ANTHROPIC_API_KEY });

const result = await client.query({
  model: 'claude-sonnet-4-5',
  systemPrompt: 'You are a helpful coding assistant.',
  userMessage: 'List files in current directory',
  workingDir: '.',
});

console.log(result.finalMessage);

typescript

import { ClaudeSdkClient } from '@anthropic-ai/agent-sdk';

const client = new ClaudeSdkClient({ apiKey: process.env.ANTHROPIC_API_KEY });

const result = await client.query({
  model: 'claude-sonnet-4-5',
  systemPrompt: 'You are a helpful coding assistant.',
  userMessage: 'List files in current directory',
  workingDir: '.',
});

console.log(result.finalMessage);

Key Components

核心组件

1. Custom Tools (SDK MCP Servers)

1. 自定义工具（SDK MCP 服务器）

In-process tools with no subprocess overhead. Primary building block for agents.

Python:

python

from claude_agent_sdk.mcp import tool, create_sdk_mcp_server

@tool(
    name="calculator",
    description="Perform calculations",
    input_schema={"expression": str}
)
async def calculator(args):
    result = eval(args["expression"])  # Use safe eval in production
    return {"content": [{"type": "text", "text": str(result)}]}

server = create_sdk_mcp_server(name="math", tools=[calculator])

TypeScript:

typescript

import { createSdkMcpServer, tool } from '@anthropic-ai/agent-sdk';
import { z } from 'zod';

const calculator = tool({
  name: 'calculator',
  description: 'Perform calculations',
  inputSchema: z.object({ expression: z.string() }),
  async execute({ expression }) {
    const result = eval(expression); // Use safe eval in production
    return { content: [{ type: 'text', text: String(result) }] };
  },
});

const server = createSdkMcpServer({ name: 'math', tools: [calculator] });

Benefits over external MCP: Better performance, easier debugging, shared memory space, no IPC overhead.

进程内工具，无子进程开销，是构建Agent的核心基础模块。

Python示例：

python

from claude_agent_sdk.mcp import tool, create_sdk_mcp_server

@tool(
    name="calculator",
    description="Perform calculations",
    input_schema={"expression": str}
)
async def calculator(args):
    result = eval(args["expression"])  # 生产环境请使用安全eval
    return {"content": [{"type": "text", "text": str(result)}]}

server = create_sdk_mcp_server(name="math", tools=[calculator])

TypeScript示例：

typescript

import { createSdkMcpServer, tool } from '@anthropic-ai/agent-sdk';
import { z } from 'zod';

const calculator = tool({
  name: 'calculator',
  description: 'Perform calculations',
  inputSchema: z.object({ expression: z.string() }),
  async execute({ expression }) {
    const result = eval(expression); // 生产环境请使用安全eval
    return { content: [{ type: 'text', text: String(result) }] };
  },
});

const server = createSdkMcpServer({ name: 'math', tools: [calculator] });

相比外部MCP的优势： 性能更好、调试更简单、内存空间共享、无IPC开销。

2. Hooks (Lifecycle Callbacks)

2. 钩子（生命周期回调）

Intercept and modify agent behaviour at specific points.

Available hooks:

```
PreToolUse
```
→ Validate/modify/deny tool calls before execution
```
PostToolUse
```
→ Process/log/modify tool results
```
Stop
```
→ Handle completion events

Python validation example:

python

async def validate_command(input_data, tool_use_id, context):
    if "rm -rf" in input_data["tool_input"].get("command", ""):
        return {
            "hookSpecificOutput": {
                "permissionDecision": "deny",
                "permissionDecisionReason": "Dangerous command blocked"
            }
        }

TypeScript logging example:

typescript

const loggingHook = {
  matcher: (input) => input.toolName === 'bash',
  async handler(input, toolUseId, context) {
    console.log(`Executing: ${input.toolInput.command}`);
  }
};

在特定执行节点拦截和修改Agent行为。

可用钩子：

```
PreToolUse
```
→ 工具执行前校验/修改/拒绝工具调用
```
PostToolUse
```
→ 工具执行后处理/日志记录/修改工具返回结果
```
Stop
```
→ 处理任务完成事件

Python校验示例：

python

async def validate_command(input_data, tool_use_id, context):
    if "rm -rf" in input_data["tool_input"].get("command", ""):
        return {
            "hookSpecificOutput": {
                "permissionDecision": "deny",
                "permissionDecisionReason": "Dangerous command blocked"
            }
        }

TypeScript日志示例：

typescript

const loggingHook = {
  matcher: (input) => input.toolName === 'bash',
  async handler(input, toolUseId, context) {
    console.log(`Executing: ${input.toolInput.command}`);
  }
};

3. Permission System

3. 权限系统

Four modes with progressively less restriction:

```
default
```
→ Prompt for each tool use
```
plan
```
→ Agent can read/explore freely, prompts for modifications
```
acceptEdits
```
→ Auto-approve file edits, prompt for bash/destructive ops
```
bypassPermissions
```
→ Fully autonomous (use carefully)

Dynamic control with
canUseTool
:

python

async def permission_callback(tool_name, tool_input, context):
    if tool_name == "bash" and "git push" in tool_input.get("command", ""):
        return False  # Deny
    return True  # Allow

四种权限模式，限制逐级降低：

```
default
```
→ 每次工具调用都需要用户确认
```
plan
```
→ Agent可自由读取/探索内容，修改类操作需要确认
```
acceptEdits
```
→ 自动批准文件编辑操作，bash/破坏性操作需要确认
```
bypassPermissions
```
→ 完全自主运行（谨慎使用）

通过
canUseTool
动态控制权限：

python

async def permission_callback(tool_name, tool_input, context):
    if tool_name == "bash" and "git push" in tool_input.get("command", ""):
        return False  # 拒绝执行
    return True  # 允许执行

4. Subagents

4. 子Agent

Isolated agents with separate context windows and specialised capabilities.

When to use:

Parallel processing of independent tasks
Context isolation (prevent one task from bloating main context)
Specialised agents with different tools/models

Python:

python

from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    subagent_definitions={
        "researcher": {
            "tools": ["read", "grep", "glob"],
            "model": "claude-haiku-4",
            "description": "Fast research agent"
        }
    }
)

TypeScript:

typescript

const options = {
  subagentDefinitions: {
    researcher: {
      tools: ['read', 'grep', 'glob'],
      model: 'claude-haiku-4',
      description: 'Fast research agent'
    }
  }
};

具备独立上下文窗口和专属能力的隔离Agent。

适用场景：

独立任务的并行处理
上下文隔离（避免单个任务占用主上下文空间）
配备不同工具/模型的专用Agent

Python示例：

python

from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    subagent_definitions={
        "researcher": {
            "tools": ["read", "grep", "glob"],
            "model": "claude-haiku-4",
            "description": "Fast research agent"
        }
    }
)

TypeScript示例：

typescript

const options = {
  subagentDefinitions: {
    researcher: {
      tools: ['read', 'grep', 'glob'],
      model: 'claude-haiku-4',
      description: 'Fast research agent'
    }
  }
};

5. Context Management

5. 上下文管理

Agentic Search (Preferred): Use bash + filesystem navigation (grep, ls, tail) before reaching for semantic search. Simpler and more reliable.

Automatic Compaction: SDK automatically summarises messages when approaching token limits. Transparent and automatic.

Folder Structure as Context Engineering: Organise files intentionally—directory structure is visible to the agent and influences its understanding.

主动搜索（推荐方案）： 在使用语义搜索前优先使用bash+文件系统导航（grep、ls、tail），实现更简单也更可靠。

自动压缩： 当接近Token上限时，SDK会自动总结历史消息，该过程透明且自动执行。

文件夹结构作为上下文工程： 有意识地组织文件结构，目录结构对Agent可见，会影响Agent对任务的理解。

Verification Patterns

校验模式

Rules-Based (Preferred)

基于规则校验（推荐方案）

Explicit validation enables self-correction:

python

undefined

明确的校验规则可支持Agent自我修正：

python

undefined

In PostToolUse hook

在PostToolUse钩子中

if tool_name == "write": # Run linter on generated file lint_result = run_linter(tool_output) if lint_result.has_errors: return {"continue": True} # Let agent fix errors

undefined

if tool_name == "write": # 对生成的文件执行lint检查 lint_result = run_linter(tool_output) if lint_result.has_errors: return {"continue": True} # 让Agent修复错误

undefined

Visual Feedback

可视化反馈

For UI tasks, screenshot and re-evaluate:

python

@tool(name="check_ui", description="Verify UI matches requirements")
async def check_ui(args):
    screenshot = take_screenshot(args["url"])
    # Return screenshot to agent for evaluation
    return {"content": [{"type": "image", "source": screenshot}]}

针对UI任务，可截图后重新评估：

python

@tool(name="check_ui", description="Verify UI matches requirements")
async def check_ui(args):
    screenshot = take_screenshot(args["url"])
    # 返回截图给Agent进行评估
    return {"content": [{"type": "image", "source": screenshot}]}

LLM-as-Judge

Only for fuzzy criteria where rules don't work (higher latency):

python

judge_result = await secondary_model.evaluate(
    criteria="Does output match tone guidelines?",
    output=agent_output
)

仅适用于规则无法覆盖的模糊判断场景（延迟更高）：

python

judge_result = await secondary_model.evaluate(
    criteria="Does output match tone guidelines?",
    output=agent_output
)

Common Pitfalls & Solutions

常见陷阱与解决方案

1. System Prompt Not Loading

1. 系统提示词未加载

Symptom: CLAUDE.md ignored, custom prompts not applied Solution: Set

setting_sources=["project"]

["user", "project"]

python

undefined

症状： CLAUDE.md被忽略，自定义提示词未生效 解决方案： 设置

setting_sources=["project"]

或

["user", "project"]

python

undefined

Python

options = ClaudeAgentOptions(setting_sources=["project"])

TypeScript

const options = { settingSources: ['project'] };

undefined

const options = { settingSources: ['project'] };

undefined

2. Tool Not Available

2. 工具不可用

Symptom: "Tool not found" errors Solution: Check MCP tool naming:

mcp__{server_name}__{tool_name}

症状： 报“Tool not found”错误 解决方案： 检查MCP工具命名格式：

mcp__{server_name}__{tool_name}

3. Permission Denied

3. 权限被拒绝

Symptom: Agent can't access directories Solution: Add directories explicitly:

python

options = ClaudeAgentOptions(add_dirs=["/path/to/data"])

症状： Agent无法访问目录 解决方案： 显式添加允许访问的目录：

python

options = ClaudeAgentOptions(add_dirs=["/path/to/data"])

4. Python Keyword Conflicts

4. Python关键字冲突

Symptom: Syntax errors with

async

continue

parameters Solution: Use

async_

and

continue_

(SDK auto-converts)

python

undefined

症状： 使用

async

或

continue

参数时报语法错误 解决方案： 使用

async_

和

continue_

（SDK会自动转换）

python

undefined

Use async_ not async

请使用async_而非async

hook_result = {"async_": True, "continue_": False}

undefined

hook_result = {"async_": True, "continue_": False}

undefined

5. Context Overflow

5. 上下文溢出

Symptom: Token limit errors Solution: Use subagents for isolation or let automatic compaction handle it

症状： 报Token上限错误 解决方案： 使用子Agent做上下文隔离，或交由自动压缩机制处理

6. Tool Execution Failures

6. 工具执行失败

Symptom: Tools fail silently or with unclear errors Solution: Return structured error messages in tool responses:

python

return {
    "content": [{
        "type": "text",
        "text": "Error: Invalid input. Expected format: ...",
        "isError": True
    }]
}

症状： 工具静默失败或报错信息不清晰 解决方案： 在工具返回结果中返回结构化错误信息：

python

return {
    "content": [{
        "type": "text",
        "text": "Error: Invalid input. Expected format: ...",
        "isError": True
    }]
}

7. External MCP Server Not Connecting

7. 外部MCP服务器连接失败

Symptom: stdio/SSE MCP servers timeout Solution: Verify server is executable and logs are accessible:

python

undefined

症状： stdio/SSE MCP服务器超时 解决方案： 验证服务器可执行，且日志可访问：

python

undefined

Check server stderr in context.mcp_server_logs

查看context.mcp_server_logs中的服务器错误日志

async def debug_hook(input_data, tool_use_id, context): print(context.mcp_server_logs.get("server_name"))

undefined

async def debug_hook(input_data, tool_use_id, context): print(context.mcp_server_logs.get("server_name"))

undefined

Language-Specific Considerations

语言特定注意事项

Python vs TypeScript

Python 与 TypeScript 对比

Aspect	Python	TypeScript
Runtime	`anyio.run(main)`	Native async/await
Min Version	Python 3.10+	Node.js 18+
Type Safety	Type hints optional	Strict types with Zod
Hook Fields	`async_` , `continue_`	`async` , `continue`
CLI	Bundled (no install)	Separate install needed
Tool Validation	Dict-based schemas	Zod schemas

对比项	Python	TypeScript
运行时	`anyio.run(main)`	原生async/await
最低版本	Python 3.10+	Node.js 18+
类型安全	可选类型提示	Zod严格类型校验
钩子字段	`async_` , `continue_`	`async` , `continue`
CLI	内置（无需额外安装）	需要单独安装
工具校验	基于字典的Schema	Zod Schema

TypeScript Advantages

TypeScript优势

Linting provides extra feedback layer for generated code
Stronger type safety catches errors earlier
Better IDE integration

Linting为生成代码提供额外反馈层
更强的类型安全可更早发现错误
更好的IDE集成

Python Advantages

Python优势

Simpler setup for data science workflows
Direct integration with ML/data tools
More concise for scripting tasks

数据科学工作流配置更简单
可直接集成ML/数据工具
脚本任务写法更简洁

Decision Frameworks

决策框架

When to Use Claude Agent SDK

何时使用Claude Agent SDK

✅ Use when:

Building autonomous agents that need computer access
Iterative workflows with verification loops
Multi-step tasks requiring context and tool use
Custom tool integration requirements
Need for permission control and safety

❌ Don't use when:

Simple API calls sufficient (use Messages API)
No tool/computer access needed
Purely conversational applications
Real-time streaming responses critical

✅ 适用场景：

构建需要访问计算机资源的自主Agent
带校验循环的迭代工作流
需要上下文和工具调用的多步骤任务
自定义工具集成需求
需要权限控制和安全保障的场景

❌ 不适用场景：

简单API调用即可满足需求（请使用Messages API）
无需工具/计算机访问的场景
纯对话类应用
对实时流式响应要求极高的场景

Tool vs Bash vs Code Generation

工具 vs Bash vs 代码生成

Use Custom Tools when:

Operation repeats frequently
Need structured input/output validation
Want prominent placement in agent context
Require error handling and retry logic

Use Bash when:

One-off exploration or debugging
System operations (git, file management)
Flexible scripting without formal structure

Use Code Generation when:

Need structured, reusable output
Can validate with linting/compilation
Building components or modules
TypeScript preferred for feedback quality

使用自定义工具的场景：

操作频繁重复
需要结构化输入/输出校验
需要在Agent上下文中优先展示
需要错误处理和重试逻辑

使用Bash的场景：

一次性探索或调试
系统操作（git、文件管理）
无需正式结构的灵活脚本

使用代码生成的场景：

需要结构化、可复用的输出
可通过lint/编译验证的场景
构建组件或模块
优先使用TypeScript获得更高质量的反馈

SDK MCP vs External MCP

SDK MCP vs 外部MCP

Use SDK MCP (in-process) when:

Building custom tools for your agent
Performance matters (no subprocess overhead)
Need shared state with main process
Debugging tool logic

Use External MCP (stdio/SSE) when:

Integrating third-party services
Tool needs isolation
Using pre-built MCP servers
Cross-language tool requirements

使用SDK MCP（进程内）的场景：

为你的Agent构建自定义工具
对性能有要求（无子进程开销）
需要和主进程共享状态
调试工具逻辑

使用外部MCP（stdio/SSE）的场景：

集成第三方服务
工具需要隔离运行
使用预构建的MCP服务器
跨语言工具需求

Session Management

会话管理

Resuming Sessions

恢复会话

Python:

python

undefined

Python示例：

python

undefined

First run

首次执行

result1 = await query(user_message="Create a file", working_dir=".")

Resume with new message

传入会话ID恢复会话，继续发送新消息

result2 = await query( user_message="Now modify it", working_dir=".", session_id=result1.session_id )


**TypeScript:**
```typescript
// First run
const result1 = await client.query({ userMessage: 'Create a file' });

// Resume
const result2 = await client.query({
  userMessage: 'Now modify it',
  sessionId: result1.sessionId
});

result2 = await query( user_message="Now modify it", working_dir=".", session_id=result1.session_id )


**TypeScript示例：**
```typescript
// 首次执行
const result1 = await client.query({ userMessage: 'Create a file' });

// 恢复会话
const result2 = await client.query({
  userMessage: 'Now modify it',
  sessionId: result1.sessionId
});

Forking Sessions

分叉会话

Create alternative branches from a point:

python

undefined

从指定节点创建备选分支：

python

undefined

Fork for different approach

分叉会话尝试不同的实现方案

result_fork = await query( user_message="Try different implementation", session_id=original_result.session_id, fork_session=True )

undefined

result_fork = await query( user_message="Try different implementation", session_id=original_result.session_id, fork_session=True )

undefined

Budget Control

预算控制

Set USD spending limits:

python

options = ClaudeAgentOptions(budget={"usd": 5.00})

Agent stops when budget exceeded. Useful for cost control in production.

设置USD消费上限：

python

options = ClaudeAgentOptions(budget={"usd": 5.00})

预算超支后Agent会自动停止，适合生产环境的成本管控。

Testing Patterns

测试模式

Mock Tools for Testing

测试用Mock工具

Python:

python

import pytest
from unittest.mock import AsyncMock

@pytest.fixture
def mock_tool():
    return AsyncMock(return_value={
        "content": [{"type": "text", "text": "mocked"}]
    })

async def test_agent(mock_tool):
    server = create_sdk_mcp_server(name="test", tools=[mock_tool])
    # Test with mocked tool

TypeScript:

typescript

import { jest } from '@jest/globals';

const mockTool = {
  name: 'test',
  execute: jest.fn().mockResolvedValue({
    content: [{ type: 'text', text: 'mocked' }]
  })
};

Python示例：

python

import pytest
from unittest.mock import AsyncMock

@pytest.fixture
def mock_tool():
    return AsyncMock(return_value={
        "content": [{"type": "text", "text": "mocked"}]
    })

async def test_agent(mock_tool):
    server = create_sdk_mcp_server(name="test", tools=[mock_tool])
    # 使用Mock工具进行测试

TypeScript示例：

typescript

import { jest } from '@jest/globals';

const mockTool = {
  name: 'test',
  execute: jest.fn().mockResolvedValue({
    content: [{ type: 'text', text: 'mocked' }]
  })
};

Integration Testing

集成测试

Test with real tools in isolated environment:

python

import tempfile
import os

async def test_file_operations():
    with tempfile.TemporaryDirectory() as tmpdir:
        result = await query(
            user_message="Create test.txt with content 'hello'",
            working_dir=tmpdir,
            permission_mode="bypassPermissions"
        )
        assert os.path.exists(f"{tmpdir}/test.txt")

在隔离环境中使用真实工具测试：

python

import tempfile
import os

async def test_file_operations():
    with tempfile.TemporaryDirectory() as tmpdir:
        result = await query(
            user_message="Create test.txt with content 'hello'",
            working_dir=tmpdir,
            permission_mode="bypassPermissions"
        )
        assert os.path.exists(f"{tmpdir}/test.txt")

Migration from Claude Code SDK

从Claude Code SDK迁移

If migrating from the deprecated

claude-code-sdk

Package renamed:
```
claude-code-sdk
```
→
```
claude-agent-sdk
```
System prompt not default: Must explicitly set or enable via
```
setting_sources
```
Type renamed (Python):
```
ClaudeCodeOptions
```
→
```
ClaudeAgentOptions
```
Settings sources not automatic: Must set
```
setting_sources=["project"]
```