本文信息来源于 Udacity，作者为 Sufian Kaki Aslam，发布于 2026 年 7 月 10 日，更新于 2026 年 7 月 13 日。原文是第三方商业教育平台发布的解释型文章，不是 Anthropic 官方文档；其中关于架构类比、生产判断和学习路径的建议，应理解为原作者观点。
每次使用 Claude，无论是通过浏览器、Claude Code，还是任何基于 Claude 的产品，你其实都在使用某种 harness。只是多数情况下，这个 harness 不是你自己构建的。
作者认为，很多工程师低估了 harness 的重要性。Harness 位于用户和底层模型之间，负责处理 prompt 如何发送、Claude 可以访问哪些工具、Claude 被允许做什么，以及它如何在推理和行动之间循环，最终返回结果。大多数人不用考虑 harness，是因为有人已经替他们构建好了。Claude Agent SDK 的作用，就是让你构建自己的 harness。
模型是引擎，harness 是车，驾驶员是你
大语言模型本身能力很强，但单独看是静止的。Claude Opus、Claude Sonnet 或其他模型，只有在你给它输入时才能响应。模型本身不能记住之前的 session，不能访问你的文件，不能发送邮件，不能调用 API，也不能在回答前主动决定去检查某个事实。它像一台引擎，但还不是一辆车。
Harness 就是那辆车。它提供底盘、控制系统、供能系统和安全能力，让模型可以在真实世界中可用。当你在 claude.ai 里对话时，浏览器界面就是 Anthropic 构建的 harness。当你使用 Claude Code 时，那也是一个 harness，只是它带有文件访问、终端命令、项目记忆和可配置 skills。其他 Claude 产品也可以理解为不同形态的 harness。它们暴露的是同一个底层模型，但塑造了模型能做什么，以及如何做。
用 Claude Agent SDK 构建自己的 harness，核心原因是：你希望自己定义这些规则。
Claude Agent SDK 提供什么
Claude Agent SDK 是 Anthropic 用来构建 Agent 的框架。它不是模型本身，而是包在模型外面的生产层。可以把它理解为 Claude 专用底盘：结构化、有明确取向，并允许你自己配置座椅、颜色和控制方式。
使用 Claude Agent SDK 时，作者认为主要要配置五件事。
System prompt
System prompt 是塑造 Claude 每次交互行为的指令，包括它的角色、约束、对运行上下文的了解，以及它要完成的目标。
Tools
Tools 是你交给 Agent 的能力。一个工具可以读取文件、查询数据库、调用外部 API，或发送通知。Claude Agent SDK 负责工具定义，并管理 Claude 如何决定何时以及如何使用这些工具。
这里的原则是最小权限：只给 Agent 完成工作实际需要的工具。一个只负责总结文档的 Agent，不需要访问你的邮箱。
Context management
Context management 负责 Agent 如何在 session 内保持状态、哪些信息继续携带、哪些信息总结、哪些信息丢弃。
原文说 “context management is not automatic”，这个表述需要谨慎理解。当前 Agent SDK 文档显示，SDK 会处理上下文管理和 retry，并会在对话接近上下文上限时自动 compaction；可恢复 session transcript 也默认本地持久化。另一方面，应用仍然需要主动设计上下文策略、持久化策略、保留期限、多主机存储和隔离方式。也就是说，SDK 有内置机制，但生产级上下文治理仍然是应用责任。
Agentic loop
Agentic loop 是 Agent 区别于 chatbot 的核心。这个循环通常包含感知、推理和行动。
例如面对“总结这份报告”这个任务，Agent 会先推理出自己需要读取文件，然后调用 Read tool，接收读取结果，再推理下一步要做什么。Claude Agent SDK 的 query() 是启动这个 loop 的入口：你给 Agent 指令，以及完成任务时可用的规则和工具。
更准确地说，query() 是导出的异步入口函数，而不是传统意义上的实例方法。它的高层作用是启动 agent loop。
Guardrails and evaluation
Guardrails 是实时执行层，用来阻止或约束不安全输入、工具调用和输出。Evaluation 是测量层，用来判断 Agent 是否达到你定义的标准。两者结合，才能把 Agent prototype 推向可生产使用的系统。
需要补充的是，SDK 并不会自动提供完整 evaluation program。权限、hooks、sandbox、预算和应用检查可以实现 guardrails，但评测标准、数据集、打分逻辑和发布 gate 仍然需要应用团队自己设计。
Claude API vs Claude Agent SDK：承包商还是员工？
原文用一个职场类比来区分 Claude API 和 Claude Agent SDK。
| Claude API | Claude Agent SDK | |
|---|---|---|
| 心智模型 | 承包商 | 员工 |
| 范围 | 一个任务、一次调用 | 持续、有状态、会用工具 |
| 记忆 | 默认没有 | 由你定义和管理 |
| 工具 | 你在外部处理 | 在 harness 内定义和管理 |
| 循环 | 单次响应 | 感知、推理、行动、观察、重复 |
| 适用场景 | 一次性生成任务 | 有持续职责的生产 Agent |
如果只是让 Claude 起草摘要、翻译文档、分类一批记录，API 就足够合适。它快速、无状态、直接：你给任务，它返回结果。
如果你要构建的系统会按计划运行、跨 session 维护上下文、决定使用哪些工具，并且需要在规模化场景中可靠表现，那就不再像一次性承包任务，而更像一个持续工作的员工。这时 Claude Agent SDK 的价值才会显现。
这张表是一个有用的教学简化，但不应过度理解。Messages API 默认不替调用方保留会话状态，但调用方可以自己提供对话历史、流式接收响应、实现多轮工具 loop，并持久化状态。Agent SDK 的关键区别，是它内置了自主 loop 和执行 harness。
为什么要构建自己的 harness
Anthropic 提供的 harness，例如 claude.ai 和 Claude Code，都是通用型产品。它们要覆盖大量使用场景，因此不会为任何单一场景完全优化。
当你用 Claude Agent SDK 构建自己的 harness 时，可以做到：
- 把 Agent 的 persona 和行为限制到具体职能，例如只处理账单问题的客服 Agent，或只从内部数据中抽取信息的分析 Agent。
- 连接通用 harness 无法访问的工具和数据源。
- 明确设计 context management，让 Agent 在长 session 中保持清晰。
- 加入该场景所需的审批步骤和 guardrails，而且只加入必要部分。
- 让 Agent 按计划运行、由其他系统触发，或嵌入已有产品。
代价是时间和复杂度。通用 harness 立刻可用；使用 Claude Agent SDK 构建自定义 harness 需要工程投入，但能得到更贴合具体工作流的 Agent。
构建自己的 harness 需要学习什么
用 Claude Agent SDK 构建 harness，原则上并不复杂，但需要充分理解五个组件，才能做出真实工程决策。
模糊的 system prompt 会让 Agent 行为不可预测。工具范围过宽，会让 Agent 做它不该做的事。Context window 如果从不管理，会变慢并发生漂移。Guardrails 如果最后才补上，通常就不是真正的 guardrails。
学习曲线不主要在语法，而在判断力：什么时候 Agent 应该暂停等待人工审批，如何写出 Claude 能正确调用的工具定义，如何设计 agentic loop，让它优雅失败而不是静默出错。这些能力区分了 prototype 和可生产运行的系统。
作者建议的路径是：先深入使用一个已有 harness，Claude Code 是最直接选择。用到你真正理解它替你做了什么、没有替你做什么。然后用 Claude Agent SDK 构建一个小系统：单 Agent、清晰任务、受限工具集。让它出错，修复 guardrails。等这个小系统稳定运行后，再继续扩展。
真正能用好 agentic AI 的工程师，不只理解模型，也理解模型外面的 harness。控制权主要就存在于这一层。
对评测框架的启发
这篇文章对 Claude Code / Agent SDK 层级评测框架的启发是：评测对象不应只是一条模型输出，而应包括模型外层 harness 是否可靠。
可以沉淀为几类评测维度：
- 目标与角色层： system prompt 是否清晰，Agent 是否能稳定维持角色和任务边界。
- 工具层： 工具是否按最小权限开放，Agent 是否会选择正确工具，工具 schema 是否能被正确调用。
- 上下文层： session 内哪些信息被保留、总结和丢弃，长任务中是否出现上下文漂移。
- 循环层： Agent 是否能完成感知、推理、行动、观察的闭环，失败时是否能停下而不是无限循环。
- 安全与评测层： guardrails 是否真实阻止危险动作，evaluation 是否能度量最终任务质量，而不只是记录 runner 成功。
因此，后续搭建 Claude Code 层级评测框架时，不能只用“模型回答对不对”作为指标。应该同时记录 harness 配置、工具调用轨迹、权限边界、上下文行为、失败终止方式和最终工件质量。
