技术指南
Claude Agent SDK：功能介绍及评估方法
Claude Agent SDK 是一个开发者界面，用于构建允许 Claude 运行有界、使用工具的工作流的应用程序。该 SDK 可以管理会话、调用工具和协调工作，但它并不能取代应用程序权限、源代码控制、评估或人工审批。请将其视为代理运行时组件，而非完整的生产系统。
对于需要在不拥有代理运行时环境的情况下完成基于源代码的工作的团队，Ottermind 提供了一种托管工作区路径：在人员审核结果的同时，保持文件、研究背景、决策和交付成果之间的关联。SDK 和托管工作区分别解决了不同的操作问题。
研究与披露: 本指南基于 2026 年 9 月 3 日修订的 Claude Agent SDK 存储库、Anthropic 工具使用文档 和 AWS AgentCore Claude Agent SDK 文档。API 和限制正在不断变化；请在实施前验证当前版本。
核心构建模块
| 构建模块 | 职责 | 应用程序控制 |
|---|---|---|
| 会话 | 维护运行及其会话状态 | 过期、隔离和审计记录 |
| 模型 | 解释上下文并提出步骤 | 模型版本、预算和输出合同 |
| 工具 | 执行有界操作 | 模式、超时、权限和幂等性 |
| 子代理 | 处理一个完全独立的角色 | 范围、预算和升级规则 |
| 权限模式 | 控制代理可以访问或更改的内容 | 允许列表和人工确认 |
| 结果 | 返回文本、结构化数据或工件 | 验证和审阅者交接 |
从一个可逆任务开始
构建一个读取密集型工作流程原型，例如将已批准的存储库文件转换为变更简报。记录输入集、提示、模型版本、工具调用、输出、审阅者更正和最终决定。仅在跟踪信息清晰可辨且故障可恢复后才添加写入权限。
最小任务契约
目标：生成基于源代码的实施简报。
允许的源代码：仅限附件中的存储库文件。
允许使用的工具：列出文件和读取文件；禁止写入或网络调用。
输出：调查结果、建议的变更、证据、风险和未解决的问题。
停止条件：缺少必需的源代码或权限不明确。会话和子代理
当工作流需要在多个步骤之间保持连续性时，请使用会话。仅当角色、工具或评估标准确实不同时才使用子代理。代理越多，协调性越差，延迟越高，故障的可能性也越大。传递每个角色所需的最小上下文，并返回包含状态和证据的结构化结果。
实用架构
将 SDK 置于应用程序边界之后，并承担以下五项职责：
- 请求处理程序： 验证用户身份，选择允许的项目，并设置预算。
- 上下文加载器： 仅检索允许的文件，并记录其标识符和日期。
- 代理运行器： 启动会话，提供工具，并持久化每个工具请求和结果。
- 策略层： 验证参数，阻止不允许的操作，并请求确认。
- 结果适配器： 验证返回的形状，并将草稿交给审核员或下一个系统。
这种分离至关重要，因为 SDK 可以帮助模型请求工具，但您的应用程序决定是否允许该请求。请勿将授权逻辑放在提示中，也不要假设模型会自行维护租户边界。
会话、恢复和故障
为每次运行指定一个显式标识符和一个终止状态，例如 completed、needs_review、blocked 或 failed。持久化模型和 SDK 版本、提示修订、输入源、工具调用和审核员的决定。如果在写入后发生网络错误，请使用幂等键并在重试之前查询记录系统。如果会话在人工编辑后恢复，请包含已编辑的文件及其更改原因，而不是重放一段晦涩难懂的对话。
工具设计示例
建议使用类似 create_draft_task(title, owner, due_date) 的函数，而不是通用 shell 工具。功能更强大的函数可以强制执行日期格式、允许的所有者、项目范围以及仅限草稿状态。文件搜索工具应返回文件标识符和摘要，而不是静默地暴露整个驱动器。浏览器工具应使用允许列表，并在身份验证或付款之前停止访问。
成本和延迟
运行开始前设置预算：最大模型迭代次数、工具调用次数、令牌数、运行时间和子代理数量。在质量允许的情况下，将提取过程路由到较小的模型，并将复杂的推理留给模糊的步骤。记录实际使用情况以及结果，以确保成功的演示不会掩盖低效的工作流程。耗时较长的任务应该是异步的、可取消的，并且对用户可见。
SDK 与托管工作区
如果您的团队需要特定于应用程序的工具、部署控制或自定义运行时，并且能够负责安全性、可观测性和维护，则可以使用 SDK 进行构建。如果主要需求是连接文件、研究、决策和交付成果以供人工审核，则托管工作区是更好的起点。选择的关键在于运营责任，而不是哪个标签听起来更自主。
示例：研究到简报代理
想象一下，一个团队需要每周一份竞争对手简报。请求处理程序会检查分析师的身份，并选择已批准的项目。上下文加载器会检索源列表并记录检索日期。代理会话只能调用 search_approved_sources 和 draft_brief。策略层会拒绝任意 URL、外部帖子或项目外部文件的请求。结果适配器要求在将草稿提交给审阅者之前，包含发现、引用、不确定性和未决问题等部分。
有用的工件不仅仅是最终的文本。它还包括跟踪记录：哪些源可用、调用了哪些工具、哪些操作被阻止、审阅者做了哪些更改，以及简报是否被接受。当模型或 SDK 发生更改时，该跟踪记录支持调试、成本分析和可重复的评估集。
版本控制和升级
在每个环境中锁定 SDK 和模型版本。请阅读发行说明，了解权限模式、工具架构、会话行为和支持的模型方面的变更。升级前运行回归测试用例，包括确认禁用工具仍然禁用的测试。保留回滚版本，避免在没有迁移计划的情况下，在长时间运行的工作流中途进行升级。
生产环境准备清单
- 身份验证和租户检查在上下文检索之前进行。
- 每个工具都具有严格的模式、超时时间和授权检查。
- 会话具有预算、取消、过期和终止状态。
- 输出在到达记录系统之前会进行验证。
- 敏感操作需要明确的人工批准。
- 日志包含足够的溯源信息，可以在不存储密钥的情况下重现故障。
- 评估案例涵盖质量、安全性、成本和延迟。
权限和安全边界。
验证应用程序代码中的工具参数。将凭据信息保留在提示框之外，限制文件系统和网络访问权限，设置超时时间，并要求对发送、删除、购买或更改访问权限进行确认。记录每次重要的工具调用，包括操作者的身份和批准决定。
评估工作流程，而非演示。
构建包含正常、不完整、矛盾、对抗性和权限敏感案例的测试集。衡量正确完成率、安全升级、工具错误、延迟、成本和审阅者更正。每次评估运行都应固定模型和 SDK 版本。
常见问题解答
Claude Agent SDK 与 Claude API 工具的使用方式相同吗？
否。工具的使用是一种模型交互模式。SDK 为代理会话和工作流提供了更多应用级构建模块，而您的应用程序仍然拥有策略、存储、权限和评估的所有权。
我需要多个代理吗？
通常一开始不需要。一个配备功能精简的工具和明确检查点的代理更容易测试和操作。
SDK 可以安全地编辑文件或运行命令吗？
它可以连接到此类工具，但安全性取决于您的沙箱、允许列表、验证、审核和回滚设计。切勿将生成的命令视为预先批准的命令。
