2026-07-24·SDK 与工具

如何用 Claude Agent SDK 把 Claude Code 的 Agent 循环嵌入你自己的程序——安装、最小异步示例、通过 MCP 接自定义工具、用工具限制和 hooks 控制循环，以及生产中经得起检验的模式。

用 Claude Agent SDK 搭建自主工作流

Claude Code 是一个很棒的交互式工具，但一旦你想在真实产品里用一个 Agent——一条给失败测试分流分类的 CI 流水线、一个处理工单的客服机器人、一个读仓库并写报告的研究助手——你就需要同样的 Agent 循环以可编程方式提供。这正是 Claude Agent SDK 提供的：驱动 Claude Code 的那一套工具、Agent 循环和上下文管理，以 Python 和 TypeScript 库的形式暴露出来。本指南涵盖安装、一个最小可运行示例、如何接入自定义工具、如何控制 Agent 循环，以及在生产中经得起检验的模式。

Agent SDK 是什么

Agent SDK 以库的形式，提供 Claude Code 交互式提供的那些能力。它为你的平台绑定了一个原生的 Claude Code 二进制，所以背后跑的是同一个久经考验的 Agent 循环——而不是重新实现。这点很重要，因为你继承了工具实现（Read、Write、Bash、Grep 等）、上下文管理行为和权限模型，而不需要重建任何东西。

SDK 推荐用于 CI/CD 流水线、自定义应用和生产自动化。交互式开发和一次性任务，用 Claude Code CLI 本身更合适。把 SDK 理解成「把 Claude Code 嵌进你自己程序」的那条路。

它以两种语言提供一等支持：

Python —— pip install claude-agent-sdk（或 uv add claude-agent-sdk）
TypeScript —— npm install @anthropic-ai/claude-agent-sdk

对其他语言，官方文档的做法是用 -p 标志和 --output-format json 以编程方式运行 Claude Code CLI，再用你所用语言解析 JSON 流。

安装与认证

把 Python SDK 装进一个使用 Python 3.10 及以上版本的项目：

pip install claude-agent-sdk

认证沿用 Claude Code：SDK 用你的 ANTHROPIC_API_KEY 环境变量（或你已登录 Claude Code 时所用的同一套认证）。在运行程序前设好 key：

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

你还需要机器上能用 Claude Code CLI，因为 SDK 在背后驱动它。在一台全新的 CI 机器上，安装 SDK 并确保 CLI 在 PATH 上就是全部准备；在已经跑 Claude Code 的开发机上，通常你什么都不缺。

一个最小的 Agent

SDK 暴露一个异步的 query 函数，把消息流式回传给你。下面是最小可用的程序——它让 Agent 列出当前目录下的文件，并允许 Bash 和 Glob 工具，这样它才能真干活：

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 运行里的一个事件：助手文本、工具调用、
        # 工具结果，以及最终结果。.result 属性标记本次运行的最终助手消息。
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

几点值得注意：

query(...) 是一个异步生成器。 你迭代它，对到来的消息做出反应。这是流式接口——你能实时看到工具调用和结果，而不只是最终答案。
ClaudeAgentOptions 控制本次运行。 allowed_tools 是最重要的旋钮：它限制 Agent 能做什么，作用和交互式 Claude Code 里的权限规则一样。从窄开始，随着你建立信任逐步放宽。
Agent 循环是隐式的。 你不需要自己写「调模型、解析工具调用、执行、回填结果」的循环——SDK 替你跑。你的代码只是对流做反应。

TypeScript 版本形态相同：对一个 query() 调用做异步迭代，选项里包含允许的工具和其他设置。

自定义工具与 MCP

真实工作流需要内置之外的工具。Agent SDK 继承了 Claude Code 的 MCP 支持，所以你可以像在 .mcp.json 里那样连任何 MCP 服务器。在 SDK 读取的配置里定义你的服务器，或通过选项传入服务器定义，Agent 就能用同样的工具使用循环调用你的自定义工具。

这就是 Agent SDK 和更广阔 MCP 生态之间的桥梁：把一个工具写成 MCP 服务器（TypeScript 用 @modelcontextprotocol/sdk，Python 用 Python MCP SDK），它就同时对交互式 Claude Code 和你写的任何 Agent SDK 程序可用。这种可移植性是把自定义能力以 MCP 服务器而非临时函数暴露的主要原因。

控制循环

自主性很强大，但在生产里你通常想要护栏。Agent SDK 提供了几种把 Agent 拴住的办法：

限制工具集。 单一最有效的控制。一个只能读和 grep 的 Agent，构造上就无法改变状态。只有当任务真需要时才授予写工具。
设定工作目录和权限模式。 像交互式 Claude Code 一样，SDK 尊重权限模式。对自动化运行，预先批准任务正好需要的工具和命令模式，这样不会有交互式提示阻塞运行。
给运行设上限。 给轮数或墙上时钟设上限，这样困惑的 Agent 不会无限循环。长跑的 Agent 会漂移，这是一个真实的失败模式；上限把它变成一个可重试的错误。
用 hooks 做策略。 SDK 在生命周期事件上支持 hooks，所以你可以确定性地阻止危险工具调用或校验输出——和交互式 Claude Code 一样的 PreToolUse/PostToolUse 模型。
流式并观察。 因为 query 是个生成器，你可以把每次工具调用和结果实时记进审计轨迹。对任何生产 Agent，这种可观测性不是可选项——它是事后唯一能回答「Agent 做了什么？」的办法。

一个真实场景：PR 分流

为了让这具体一点，下面是一个真实工作流的形态——给失败的 CI 构建分流分类。Agent 读取失败测试输出、看相关源码、发一条总结可能原因的评论。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def triage(failing_test_log: str, repo_dir: str):
    prompt = f"""
A CI build is failing. Here is the test output:

<failing_log>
{failing_test_log}
</failing_log>

Investigate the likely cause: read the failing test, read the source it
exercises, and write a 3-5 sentence summary of the probable root cause and
the file:line where the fix likely belongs. Do not modify any files.
"""
    async for message in query(
        prompt=prompt,
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Grep", "Glob"],
            cwd=repo_dir,
        ),
    ):
        if hasattr(message, "result"):
            return message.result
    return ""

# 在 CI 步骤里：读日志、调 triage()、把结果作为评论发出去。

让它在生产中安全的那些决策：工具集是只读的（Read、Grep、Glob——没有 Bash、没有 Write），所以 Agent 字面上无法改变任何东西。工作目录钉死在检出的仓库上。输出是有边界的总结，不是自由代码。这就是模式：窄工具、钉死范围、结构化输出、任何真实改动都人在环里。

什么时候用 SDK、CLI、还是裸 API 调用

三个相关工具，三种不同适配：

Claude Code CLI —— 交互式开发、终端里的一次性任务。人在驱动时最佳。
Claude Agent SDK —— 生产自动化、自定义应用、CI/CD。你想把完整 Agent 循环（工具、上下文管理全套）嵌入自己程序时最佳。
裸 Claude API（anthropic SDK） —— 你需要对消息、工具使用和模型调用本身的直接控制，且愿意自建 Agent 循环。适合不匹配 Claude Code 循环的自定义设计。

一条有用的规则：如果你的第一反应是「我希望 Claude Code 能自动做 X」，就用 Agent SDK。如果你的第一反应是「我想用这一组确切的消息和工具调模型」，就用裸 API。

生产注意事项

Agent 无人值守运行后，有几点很重要：

幂等性。 Agent 会被重试。确保你工具的副作用是幂等的，或者给它加守卫，这样重试不会重复应用一个改动。
成本监控。 每次 Agent 运行都烧 token，而 Agent 式运行比单次调用贵。给 token 用量加监控并设预算告警。失控的 Agent 也是失控的账单。
密钥。 当心你通过工具结果或文件读暴露给 Agent 的东西。一个有广泛读权限的 Agent 可能把密钥泄进它的输出。应用和交互式 Claude Code 里一样的 deny 规则。
确定性边界。 Agent 是非确定性的。把判断类活儿（分流分类、总结、探索）交给它，把确定性逻辑留在普通代码里。别让 Agent 决定要不要部署——让它为人或规则收集信息。
评估。 发布前，用一组固定输入跑 Agent 并抓取输出。当你改提示词、工具或模型时，重跑并对比。没有这步，Agent 质量会悄无声息地漂移。

常见问题

什么是 Claude Agent SDK，它和 Claude Code 有什么不同？

Claude Agent SDK 把驱动 Claude Code 的那套 Agent 循环、工具和上下文管理，以 Python 和 TypeScript 库的形式暴露出来。Claude Code 是你在终端运行的交互式 CLI；Agent SDK 是你嵌入自己程序用于 CI/CD、自定义应用和生产自动化的东西。背后 SDK 驱动的是一个内置的 Claude Code 二进制，所以你继承的是同一套久经考验的行为。

怎么安装 Claude Agent SDK？

用 pip install claude-agent-sdk（Python 3.10 及以上）或 uv add claude-agent-sdk 装 Python SDK，用 npm install @anthropic-ai/claude-agent-sdk 装 TypeScript SDK。你还需要机器上能用 Claude Code CLI，并设好 ANTHROPIC_API_KEY 环境变量。其他语言请用 -p 标志加 --output-format json 以编程方式运行 Claude Code CLI。

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

通过 ClaudeAgentOptions（或其 TypeScript 等价物）传一个 allowed_tools 列表。限制工具集是让 Agent 安全最有效的单一手段——一个只能 Read 和 Grep 的 Agent 构造上就无法改变状态。只有当任务真需要时才授予写工具或 shell 工具，并配合权限模式和 hooks 一起做策略。

我该用 Agent SDK，还是直接调 Claude API？

想把你程序里整套 Claude Code Agent 循环（工具、上下文管理全套）嵌入而不重建时，用 Agent SDK。想直接控制消息和工具使用、且愿意自建 Agent 循环时，用裸 Claude API（anthropic SDK）。经验法则：如果你希望 Claude Code 能自动做某事，就用 Agent SDK；如果你想用确切的一组消息调模型，就用裸 API。

官方参考资料

本文基于截至 2026 年 7 月的公开信息，相关 API 可能演进。