claude-agent-sdk

Claude Agent SDK

概述

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

安装

# Python
pip install claude-agent-sdk

# TypeScript
npm install @anthropic-ai/agent-sdk

核心架构：反馈循环模式

每个 Agent 都遵循以下循环：

1. 收集上下文 → 文件系统导航、子 Agent、工具
2. 采取行动 → 工具、bash、代码生成、MCP
3. 验证工作 → 基于规则、视觉、大模型裁判
4. 重复 → 持续迭代直至完成

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

执行机制（优先级排序）

根据任务要求选择机制：

1. 自定义工具 → 主要工作流（会在上下文中突出显示）
2. Bash → 灵活的一次性操作
3. 代码生成 → 复杂、可复用的输出（优先使用 TypeScript，以获得 lint 反馈）
4. MCP → 预构建的外部集成（Slack、GitHub、数据库）

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

快速入门模式

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：会话管理

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

核心组件

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

进程内工具，无需承担子进程开销，是构建 Agent 的主要基础组件。

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：

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] });

**相较于外部 MCP 的优势：**性能更好、更易调试、共享内存空间、无需 IPC 开销。

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

在特定时机拦截并修改 Agent 的行为。

可用钩子：

• PreToolUse → 在执行前验证／修改／拒绝工具调用
• PostToolUse → 处理／记录／修改工具结果
• Stop → 处理完成事件

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 日志记录示例：

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

3. 权限系统

提供四种限制程度逐步降低的模式：

• default → 每次使用工具时都提示
• plan → Agent 可自由读取／探索，修改时会提示
• acceptEdits → 自动批准文件编辑，使用 bash／执行破坏性操作时会提示
• bypassPermissions → 完全自主（请谨慎使用）

使用 canUseTool 进行动态控制：

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

4. 子 Agent

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

适用场景：

• 并行处理相互独立的任务
• 隔离上下文（防止某个任务让主上下文膨胀）
• 使用不同工具／模型的专用 Agent

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：

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

5. 上下文管理

Agent 式搜索（首选）： 使用 bash 和文件系统导航（grep、ls、tail），而不是一开始就使用语义搜索。这样更简单、更可靠。

自动压缩： 接近令牌限制时，SDK 会自动总结消息。此过程透明且自动。

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

验证模式

基于规则（首选）

明确的验证可支持自我纠正：

# In PostToolUse hook
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

视觉反馈

对于 UI 任务，截取屏幕截图并重新评估：

@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}]}

大模型裁判

仅用于规则无法处理的模糊标准（延迟较高）：

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

常见问题与解决方案

1. 系统提示词未加载

**症状：**CLAUDE.md 被忽略，自定义提示词未应用 **解决方案：**设置 setting_sources=["project"] 或 ["user", "project"]

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

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

2. 工具不可用

**症状：**出现“找不到工具”错误 **解决方案：**检查 MCP 工具命名：mcp__{server_name}__{tool_name}

3. 权限被拒绝

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

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

4. Python 关键字冲突

症状： 使用 async 或 continue 参数时出现语法错误 解决方案： 使用 async_ 和 continue_（SDK 会自动转换）

# Use async_ not async
hook_result = {"async_": True, "continue_": False}

5. 上下文溢出

症状： 出现令牌限制错误 解决方案： 使用子 Agent 实现隔离，或让自动压缩功能处理

6. 工具执行失败

症状： 工具静默失败或报错不明确 解决方案： 在工具响应中返回结构化错误消息：

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

7. 外部 MCP 服务无法连接

症状： stdio/SSE MCP 服务超时 解决方案： 确认服务可执行，并且可以访问日志：

# Check server stderr in context.mcp_server_logs
async def debug_hook(input_data, tool_use_id, context):
    print(context.mcp_server_logs.get("server_name"))

特定语言注意事项

Python 与 TypeScript

方面	Python	TypeScript
运行时	anyio.run(main)	原生 async/await
最低版本	Python 3.10+	Node.js 18+
类型安全	类型提示可选	使用 Zod 的严格类型
Hook 字段	async_、continue_	async、continue
CLI	已捆绑（无需安装）	需要单独安装
工具验证	基于 Dict 的模式	Zod 模式

TypeScript 的优势

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

Python 的优势

• 更适合数据科学工作流的简易设置
• 可直接集成 ML/数据工具
• 编写脚本任务时更简洁

决策框架

何时使用 Claude Agent SDK

✅ 适用于：

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

❌ 不适用于：

• 简单 API 调用即可满足需求时（使用 Messages API）
• 无需访问工具或计算机时
• 纯对话类应用
• 实时流式响应至关重要时

工具与 Bash 及代码生成的选择

适用于自定义工具的情况：

• 操作需要频繁重复
• 需要结构化输入/输出验证
• 希望工具在 Agent 上下文中更醒目
• 需要错误处理和重试逻辑

适用于 Bash 的情况：

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

适用于代码生成的情况：

• 需要结构化、可复用的输出
• 可以通过代码检查/编译进行验证
• 构建组件或模块
• 更看重反馈质量时优先选择 TypeScript

SDK MCP 与外部 MCP 的选择

适用于 SDK MCP（进程内）的情况：

• 为 Agent 构建自定义工具
• 性能很重要（无子进程开销）
• 需要与主进程共享状态
• 调试工具逻辑

适用于外部 MCP（stdio/SSE）的情况：

• 集成第三方服务
• 工具需要隔离
• 使用预构建的 MCP 服务
• 工具需要跨语言支持

会话管理

恢复会话

Python：

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

# Resume with new message
result2 = await query(
    user_message="Now modify it",
    working_dir=".",
    session_id=result1.session_id
)

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
});

分叉会话

从某个节点创建备选分支：

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

预算控制

设置美元支出上限：

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

超出预算后 Agent 将停止。适用于生产环境中的成本控制。

测试模式

用模拟工具进行测试

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：

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

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

集成测试

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

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

从 Claude Code SDK 迁移

如果要从已弃用的 claude-code-sdk 迁移：

1. 包已重命名： claude-code-sdk → claude-agent-sdk
2. 系统提示词不再是默认值： 必须显式设置，或通过 setting_sources 启用
3. 类型已重命名（Python）： ClaudeCodeOptions → ClaudeAgentOptions
4. 设置来源不再自动加载： 必须设置 setting_sources=["project"]

请参阅迁移指南：https://platform.claude.com/docs/en/agent-sdk/migration-guide

性能优化

1. 简单任务使用 Haiku → 成本降低 5 倍，适合更快地进行研究/探索
2. 优先使用 SDK MCP，而非外部 MCP → 无子进程开销
3. 批量操作 → 尽可能合并文件操作
4. 设置轮次限制 → 防止无限循环（turn_limit 参数）
5. 监控 token 用量 → 在生产环境中使用预算控制

安全最佳实践

1. 始终验证工具输入 → 切勿信任未经检查的输入
2. 使用权限回调 → 动态拒绝危险操作
3. 限制文件系统访问 → 使用 add_dirs 限定范围
4. 隔离外部 MCP 服务 → 隔离第三方工具
5. 设置预算 → 防止成本失控
6. 记录所有工具调用 → 通过 PostToolUse hooks 留存审计记录
7. 切勿将 API 密钥硬编码 → 使用环境变量

核心原则

1. 文件夹结构是上下文工程 → 有意识地组织
2. 基于规则的反馈可实现自我纠正 → 添加 lint 和验证
3. 从 Agent 式搜索开始 → 先用 Bash 导航，再进行语义搜索
4. 工具优先，Bash 次之 → 使用工具执行可重复的操作
5. 生成的代码使用 TypeScript → 额外的反馈层可提升质量
6. 验证可完成闭环 → 始终验证 Agent 的工作
7. 使用子 Agent 进行隔离 → 防止上下文膨胀并支持并行处理

其他资源

• API 参考（Python）： https://platform.claude.com/docs/en/agent-sdk/python
• API 参考（TypeScript）： https://platform.claude.com/docs/en/agent-sdk/typescript
• 示例仓库： https://github.com/anthropics/claude-agent-sdk-demos
• 工程博客： https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk