2026-09-01·SDK 与工具

Claude Agent SDK 2026 实战——把 Claude Code 同一套 agent 循环以 Python / TypeScript 库形式暴露出来。覆盖 query() 异步生成器核心 API、ClaudeAgentOptions 全部字段、MCP server 接入、hooks 与审计、asyncio.gather 多 agent 扇出编排、五条生产护栏（幂等 / 成本 / 密钥 / 确定性 / 评估），以及 3 种官方部署形态（managed-agents-observe、自托管 sandbox、worker dispatch）。

Claude Agent SDK 实战：从首次 query 到生产级 multi-agent 编排（2026）

Q: Agent SDK 与 Claude Code 到底什么关系？

Agent SDK 是 Claude Code 同一套 agent 循环的可编程封装——SDK 在内部驱动本机 Claude Code CLI 二进制，所以你继承的是 Claude Code 完整能力：所有内置工具、上下文管理、权限模型、hooks、subagent。区别：Claude Code 是你终端里跑的交互式 CLI；Agent SDK 是你嵌入程序用于 CI / 自定义应用 / 生产自动化。

Q: 怎么控制 agent 能用哪些工具？

通过 ClaudeAgentOptions.allowed_tools 传白名单。限制工具集是让 agent 安全的最有效手段——一个只能 Read / Grep 的 agent 构造上无法改变状态。生产模式：白名单 + 黑名单 + permission_mode='bypassPermissions' + max_turns 兜底防 runaway。只在任务真需要时才授予 Write / Bash，并配合 hooks 做策略。

Q: Agent SDK 能并行跑多个 subagent 吗？

能。asyncio.gather(*queries, return_exceptions=True) 同时拉起多个 query() 调用，每个跑自己的 subagent，互相上下文隔离。return_exceptions=True 防单点拖垮。实战模式：扇出式研究（3 个 subagent 同时调研不同方向，主线程只在最后拿回 3 段浓缩报告）。subagent 的内部上下文不占主线程预算——这是 token 层面的真正回报。

Q: 怎么给 Agent SDK 加确定性安全护栏？

用 ClaudeAgentOptions.hooks 接 Claude Code 的 hooks 系统——PreToolUse 阻断危险工具调用、PostToolUse 跑 linter 把错误反馈回 Agent、Stop 触发通知。审计：async for message in query(...) 让你流式拿到每个事件（助手文本、工具调用、工具结果），写到结构化 JSON 日志。生产模式：「绝不能错」放 hook（确定性逻辑），「需要判断」放 Agent（概率性逻辑）——两者职责分明、互不干扰。

Claude Agent SDK 是 Anthropic 在 2025 年发布、2026 年全面成熟的可编程 agent 框架——把驱动 Claude Code 的同一套工具、agent 循环、上下文管理、权限系统，以 Python 和 TypeScript 库的形式暴露出来。本文基于官方 Agent SDK 文档与 claude-quickstarts managed-agents，讲清楚：核心 API（query() 异步生成器）、ClaudeAgentOptions 全部字段、MCP server 接入、hooks 与审计、多 agent 编排、生产级护栏，以及 2026 年最常见的踩坑。

TL;DR

Agent SDK = Claude Code 同款 agent 循环的可编程封装（Python / TS）

安装：pip install claude-agent-sdk 或 npm install @anthropic-ai/claude-agent-sdk

核心 API：query(prompt, options) 返回异步生成器——迭代消息流（助手文本、工具调用、工具结果）

关键选项：allowed_tools / permission_mode / cwd / model / hooks

MCP server、hooks、subagent、bypassPermissions 都是 Agent SDK 的一等公民

2026 现状：官方 managed-agents 三种部署形态——Anthropic 托管、自托管 sandbox、worker pool dispatch

Claude Agent SDK 是什么

Claude Code 是终端里的交互式 CLI；Claude Agent SDK 是同一套 agent 循环的可编程版本。它通过内置的 Claude Code 二进制运行（Python / TypeScript SDK 都依赖本机 Claude Code CLI），所以你继承的不是重新实现的简化版——是 Claude Code 完整的能力：所有内置工具（Read / Write / Edit / Bash / Glob / Grep / WebSearch 等）、上下文管理、权限模型、hooks、subagent。

什么时候用 Agent SDK：

| 场景 | 用什么 | |---|---| | 终端交互、个人开发 | Claude Code CLI（直接） | | CI / 自动化脚本 / 后台 worker | Agent SDK | | 自定义应用里嵌入 agent | Agent SDK | | 需要直接控制 messages / tools / 模型 | 裸 anthropic SDK（自建循环） | | 多 agent 编排 / 长时间任务 | Agent SDK + subagent + hooks |

经验法则：想要 Claude Code 整个循环嵌入程序而不重建 → Agent SDK。想要直接控制 message 流且愿意自己写循环 → 裸 API。

安装与认证

# Python（3.10+）
pip install claude-agent-sdk
# 或 uv
uv add claude-agent-sdk

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

前置依赖：机器上必须能用 Claude Code CLI。SDK 通过调用本机 Claude Code 二进制来执行 agent 循环——没有 Claude Code 就跑不起来。

认证沿用 Claude Code 的环境变量：

export ANTHROPIC_API_KEY="sk-ant-..."  # 注意是 sk-ant- 前缀

CLI 第一次跑时引导账号登录；登录后 SDK 自动复用同一套认证。生产推荐：API key 走环境变量 / Vault 注入——别把 key 写进源码。

一个最小可运行的 agent

Python SDK 暴露一个异步生成器 query()，迭代收到的消息：

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="What files are in this directory? Summarize the project structure.",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        # 每条 message 是 Agent 运行中的一个事件
        # AssistantTextMessage / ToolUseBlock / ToolResultBlock / ResultMessage
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

TypeScript 版形态相同：

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

for await (const message of query({
  prompt: "What files are in this directory? Summarize the project structure.",
  options: new ClaudeAgentOptions({ allowedTools: ["Bash", "Glob"] }),
})) {
  if ("result" in message) {
    console.log(message.result);
  }
}

关键 API 行为：

query() 是异步生成器——必须异步迭代才能逐条拿到消息
消息分四类：AssistantMessage（文本）、UserMessage（tool_result）、SystemMessage（元数据）、ResultMessage（最终结果）
agent 循环隐式——你只对消息流做反应，SDK 自动跑工具 → 回填结果 → 再调模型

ClaudeAgentOptions：全部字段详解

ClaudeAgentOptions 是 Agent SDK 的总开关。常用字段：

| 字段 | 类型 | 作用 | |---|---|---| | allowed_tools | list[str] | 工具白名单——["Read", "Bash", "Glob"] | | disallowed_tools | list[str] | 工具黑名单（在白名单之上禁用） | | permission_mode | str | default / acceptEdits / plan / bypassPermissions | | cwd | str | Agent 工作目录 | | model | str | 模型 ID，如 claude-sonnet-4-5 | | system_prompt | str | 顶层 system prompt | | mcp_servers | dict | MCP server 配置（项目级 + 用户级 + 内联） | | hooks | dict | PreToolUse / PostToolUse / Stop / SubagentStop 等 hook | | max_turns | int | 最大工具调用轮数（防 runaway） | | max_budget_usd | float | 美元预算上限（超限 throw） | | fallback_model | str | 主模型 5xx 时 fallback 模型 | | extra_args | dict | 透传给 Claude Code CLI 的额外参数 |

最小可用 vs 生产可用的差距：

# 最小：只允许 Read + Grep 的只读 Agent
options = ClaudeAgentOptions(
    allowed_tools=["Read", "Grep"],
    cwd="/path/to/repo",
)

# 生产：含 MCP + hooks + 模型 fallback + 预算上限
options = ClaudeAgentOptions(
    allowed_tools=["Read", "Grep", "Bash(git diff:*)"],
    permission_mode="bypassPermissions",
    cwd="/path/to/repo",
    model="claude-sonnet-4-5",
    fallback_model="claude-haiku-4-5",
    max_turns=20,
    max_budget_usd=2.0,
    mcp_servers={
        "github": {
            "command": "docker",
            "args": ["run", "-i", "--rm", "-e", "GITHUB_TOKEN", "ghcr.io/github/github-mcp-server"],
        }
    },
    hooks={
        "PreToolUse": [{
            "matcher": "Bash",
            "hooks": [{"type": "command", "command": "python3 .claude/hooks/audit.py"}],
        }],
    },
)

接入 MCP server

Agent SDK 继承 Claude Code 的 MCP 支持——任何 MCP server 都能用：

options = ClaudeAgentOptions(
    mcp_servers={
        # stdio server（最常见）
        "github": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-github"],
            "env": {"GITHUB_TOKEN": "${GITHUB_TOKEN}"},
        },
        # HTTP server（远程）
        "remote-tools": {
            "url": "https://mcp.example.com/sse",
            "headers": {"Authorization": "Bearer ${TOKEN}"},
        },
    }
)

实战模式：把 .mcp.json 项目级配置 + SDK options 合并——SDK 自动用 Claude Code 加载顺序（MDM > 项目级 > 用户级）。好处：同一个 MCP server 配置在交互式 Claude Code 和你写的 Agent SDK 程序里通用——团队共用一套配置。

hooks 与审计轨迹

Agent SDK 完整继承 Claude Code 的 hooks 系统——async for message 让你拿到每个事件（文本、tool_use、tool_result），叠加 hooks 实现确定性安全护栏：

import json, logging
audit = logging.getLogger("agent.audit")

async def logged_query(prompt: str):
    async for message in query(
        prompt=prompt,
        options=ClaudeAgentOptions(
            allowed_tools=["Bash", "Read", "Write"],
            hooks={
                "PreToolUse": [{
                    "matcher": "Bash",
                    "hooks": [{
                        "type": "command",
                        "command": "python3 .claude/hooks/block_rm.py",
                    }],
                }],
            },
        ),
    ):
        # 流式记录每个事件 → 这是审计轨迹
        audit.info(json.dumps({
            "type": type(message).__name__,
            "data": getattr(message, "data", None),
        }))
        if hasattr(message, "result"):
            yield message.result

实战分类：

确定性安全护栏：PreToolUse hook 阻断 rm -rf / curl | sh / 敏感路径写
审计日志：流式记录所有 message 到结构化日志（JSON），CI 失败时直接查
质量门：PostToolUse hook 跑 ruff / tsc / 测试，发现错反馈回 Agent 让它自修
Stop 通知：长跑任务完成时发 Slack / webhook

多 agent 编排

Agent SDK 让你在同一进程里并行起多个 subagent 做扇出式研究。配合 permission_mode="bypassPermissions"（subagent 没有交互能力，自动化任务必须跳过提示）：

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def fan_out_research(topics: list[str]) -> list[str]:
    subagents = [
        query(
            prompt=f"调研 {topic} 在 2026 年的最佳实践。返回 3-5 条要点。",
            options=ClaudeAgentOptions(
                allowed_tools=["Read", "Grep", "WebSearch"],
                permission_mode="bypassPermissions",
                max_turns=10,
            ),
        )
        for topic in topics
    ]
    streams = await asyncio.gather(*subagents, return_exceptions=True)
    results = []
    for stream in streams:
        if isinstance(stream, Exception):
            continue
        async for message in stream:
            if hasattr(message, "result"):
                results.append(message.result)
    return results

关键模式：

每个 subagent 自己的 context window（隔离）
return_exceptions=True 防单点拖垮
max_turns 兜底防 runaway
主线程只在最后拿浓缩报告——subagent 内部几千 token 上下文不占主线程预算

生产护栏：5 个硬性规则

无人值守的 agent 跑起来有 5 个铁律：

幂等性：agent 会重试——工具副作用必须幂等或加守卫
成本监控：max_budget_usd + 外部 token 用量监控 + 预算告警
密钥保护：deny 规则 + 别把密钥写到 agent 能读到的地方
确定性边界：agent 处理判断类活儿（分流 / 总结 / 探索），确定性逻辑留在普通代码
评估先行：固定输入集 + 重跑对比，没这一步质量会悄悄漂移

# 幂等工具的范例
def send_email(to: str, subject: str, body: str) -> str:
    # 用 idempotency key 防重发
    idempotency_key = hashlib.sha256(f"{to}{subject}{body}".encode()).hexdigest()
    return email_client.send(to, subject, body, idempotency_key=idempotency_key)

2026 年三种部署形态

claude-quickstarts managed-agents 给出的官方部署模式：

managed-agents-observe-tool-calls.py：Anthropic 托管后端，自动观察、审计、计费
managed-agents-self-hosted-sandbox-worker.py：自托管 sandbox worker，把 Agent SDK 跑在容器里
managed-agents-worker-dispatch.py：worker pool + 任务分发——适合高 QPS 后台任务

实战选型：

早期项目：managed-agents 托管后端，省运维
企业 / 合规：自托管 sandbox worker，数据不出本机
生产规模：worker pool + 任务队列，水平扩展

常见问题

Agent SDK 与 Claude Code 到底什么关系？

Agent SDK 是 Claude Code 同一套 agent 循环的可编程封装——SDK 在内部驱动本机 Claude Code CLI 二进制，所以你继承的是 Claude Code 完整能力：所有内置工具、上下文管理、权限模型、hooks、subagent。区别：Claude Code 是你终端里跑的交互式 CLI；Agent SDK 是你嵌入程序用于 CI / 自定义应用 / 生产自动化。

怎么控制 agent 能用哪些工具？

通过 ClaudeAgentOptions.allowed_tools 传白名单。限制工具集是让 agent 安全的最有效手段——一个只能 Read / Grep 的 agent 构造上无法改变状态。生产模式：白名单 + 黑名单 + permission_mode="bypassPermissions" + max_turns 兜底防 runaway。只在任务真需要时才授予 Write / Bash，并配合 hooks 做策略。

Agent SDK 能并行跑多个 subagent 吗？

能。asyncio.gather(*queries, return_exceptions=True) 同时拉起多个 query() 调用，每个跑自己的 subagent，互相上下文隔离。return_exceptions=True 防单点拖垮。实战模式：扇出式研究（3 个 subagent 同时调研不同方向，主线程只在最后拿回 3 段浓缩报告）。subagent 的内部上下文不占主线程预算——这是 token 层面的真正回报。

怎么给 Agent SDK 加确定性安全护栏？

用 ClaudeAgentOptions.hooks 接 Claude Code 的 hooks 系统——PreToolUse 阻断危险工具调用、PostToolUse 跑 linter 把错误反馈回 Agent、Stop 触发通知。审计：async for message in query(...) 让你流式拿到每个事件（助手文本、工具调用、工具结果），写到结构化 JSON 日志。生产模式：「绝不能错」放 hook（确定性逻辑），「需要判断」放 Agent（概率性逻辑）——两者职责分明、互不干扰。

Agent SDK 怎么接入 MCP 服务器？

通过 ClaudeAgentOptions 的 mcp_servers 字段传配置：stdio 服务器写 command + args + env，远程 HTTP 服务器写 url + headers（如 Bearer 令牌）。SDK 沿用 Claude Code 的加载优先级（企业 MDM > 项目级 > 用户级），所以同一份 MCP 配置能在交互式 Claude Code 和你的 SDK 程序之间通用，团队共享一套服务器定义。

怎么防止 Agent SDK 的 agent 失控烧钱或陷入死循环？

三个内建旋钮加两条外部护栏。内建：max_turns 限制工具调用轮数、max_budget_usd 设美元预算上限（超限抛错）、fallback_model 在主模型 5xx 时降级。外部：token 用量监控加预算告警，以及要求工具副作用幂等（如带 idempotency key），这样 agent 重试也不会重复扣款或重发邮件。

官方参考资料

本文基于截至 2026 年 8 月的 Claude Agent SDK 官方文档与官方 quickstarts；SDK API 可能演进，建议每 6 个月查一次规范版本号。