Claude Agent SDK：Python、TypeScript、定价与安装指南（2026）

先说结论： 当应用需要受控的多轮工具循环时，再使用 Claude Agent SDK。先锁定 SDK 版本，从只读权限开始，并为写文件、Shell、网络、MCP 工具设置审批、轮数和花费上限。

当一次模型调用无法完成任务时，Claude Agent SDK 提供的是一套 Agent 运行时：它可以围绕任务调用工具、等待审批、继续循环，并在需要时恢复会话。真正值得先回答的问题不是“如何让 Claude 调工具”，而是“这个 Agent 在什么边界内可以行动”。

本文聚焦 Agent 循环、工具权限、MCP、会话和模型网关。SDK 功能会随版本变化，安装或锁定版本前请核对 Anthropic 官方 Claude Code SDK 文档。

Agent SDK 与 Messages API 的区别

如果应用自己控制“请求模型—执行函数—把结果发回模型”的循环，Messages API 通常更合适。Agent SDK 面向更完整的 coding-agent 循环：工具编排、事件流、权限决定和可恢复会话都成为运行时的一部分。

这也改变了测试方式。普通 API 测试可以断言一次响应；Agent 测试还必须覆盖工具策略、最大轮数、文件范围、网络权限，以及用户拒绝动作时是否安全停止。

先把架构分成四层

1. 任务输入：用户请求和项目上下文。
2. Agent 运行时：SDK 循环、模型选择和会话状态。
3. 工具边界：文件、Shell、网页和 MCP 工具，以及明确的权限。
4. 模型/API 网关：鉴权、路由、预算和可观测性。

当应用需要统一接入多个 LLM，以及图片、视频或数据 API 时，可以把 SandBase 放在第四层。不要混淆职责：SDK 负责 Agent 行为，网关负责你配置的模型和 API 连接、路由与预算。

第一次运行应该限制权限

从只读或计划模式开始，只给 Agent 一个仓库和一个窄任务。设置最大轮数，记录每次工具请求，并要求 Shell、写文件和网络访问经过审批。一个很有价值的验收测试是“拒绝动作”：Agent 应该解释拒绝并继续或干净地停止，而不是悄悄扩大权限重试。

Anthropic 的 SDK 和 CLI 文档描述了非交互输出、允许/禁止工具、权限模式和会话继续等控制项。这些运行时控制比一段漂亮的 system prompt 更容易审计。

TypeScript 与 Python 快速开始

Anthropic 当前的 Agent SDK 文档同时列出 TypeScript 和 Python 包。请在项目环境中安装，并锁定你审核过的版本：

npm install @anthropic-ai/claude-agent-sdk
# 或在 Python 虚拟环境中
pip install claude-agent-sdk

第一次查询应当把权限边界写清楚。下面示例表达只读的计划模式；具体参数请以你锁定的 SDK 版本 quickstart 为准：

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

for await (const message of query({
  prompt: "检查这个仓库，并提出一个只读的小改动方案。",
  options: { permissionMode: "plan" }
})) {
  console.log(message);
}

如果当前版本的参数名称不同，不要直接复制运行，应以对应版本的官方文档为准。

安装包只是运行时层。你仍需配置鉴权、模型/供应商、工作目录和权限策略。安装成功只是依赖检查，不代表可以安全地对生产仓库运行 Agent；第一次查询和版本相关参数应以官方 quickstart为准。

定价时要把模型/API 使用成本和工具运行成本分开预算。多轮 Agent 不能等同于一次文本请求：工具调用、重试、上下文增长和子 Agent 都可能改变最终费用。如果应用使用 SandBase，应在网关层设置预算并记录 correlation ID。

使用 MCP，但不要把发现当授权

MCP 让外部工具更容易被发现，但“能发现”不等于“已授权”。把每个 MCP Server 当作需要审核的外部集成：检查工具、输入、侧 effect 和数据处理，只暴露当前任务所需的工具，并为返回数据做校验。

生产环境至少记录：Server 身份和版本、工具名及规范化参数、审批结果、延迟与重试、会话和请求标识。这样既能调试，也能分析成本。协议取舍可参考 MCP 与 Function Calling 对比。

会话恢复带来新的权限问题

恢复会话很方便，但也可能延长旧请求的权限。会话应设置过期时间，并绑定用户和项目；恢复后重新检查权限，不要默认此前批准过的目录或网络目标仍然有效。

存储摘要和标识符，不要无条件保存所有工具结果。日志可能含有密钥、个人数据或过时指令，持久化前应脱敏，并明确保留周期。

在 Agent 后面接入模型网关

当你需要路由、预算控制或统一 API 时，网关最有价值。可以在 Agent 运行前解析模型和 fallback，附加预算与关联 ID，在网关施加限流，记录 token、延迟，并在供应商不可用时安全失败。

但不要把“兼容接口”描述成“模型等价”。上下文限制、工具行为、安全过滤和流式语义仍可能不同。OpenAI API 替代方案指南 解释了这条兼容边界。

上线前检查清单

• 锁定并审核 SDK 版本；
• 使用最小权限工具集；
• 限制轮数、token、时间和花费；
• 破坏性或外部动作必须审批；
• 日志脱敏后再保存；
• 覆盖拒绝、超时、错误输出和供应商失败；
• 恢复会话时重新检查权限；
• 为模糊任务保留人工升级路径。

Agent SDK 是受控自治的运行时，不是应用安全的替代品。先从窄任务开始，测量失败模式，再根据证据扩大权限。

参考资料

• Anthropic Claude Code SDK 文档，检索日期：2026-08-23。
• Anthropic MCP 文档，检索日期：2026-08-23。
• Anthropic CLI 参考，检索日期：2026-08-23。