你的AI代理的好坏取决于其周围的框架
内容提要
本文探讨AI代理在生产环境中的实际挑战，指出模型仅是服务的一部分，代理框架（harness）负责提供边界、工具契约、权限控制和上下文管理。通过账单变更等具体示例，强调工具定义、读写分离、权限验证、追踪记录和测试的重要性，并指出代理需明确停止条件，确保安全可靠运行。
延伸解读
工具契约：错误信息也是提示词
文章强调，工具定义中的错误状态分类至关重要。将错误分为可重试和终止性错误，并给出明确说明（如“需要审批”），能让模型知道下一步该做什么。相反，模糊的错误码（如ERR_422）对模型毫无帮助。这提醒开发者，工具的错误返回不仅是技术细节，更是模型决策的输入，设计时需考虑其引导作用。
权限边界：抵御提示注入的关键
文章指出，不能依赖模型抵抗所有嵌入在数据中的恶意指令，因此权限边界是安全的关键。通过为每个工具分配最小权限的服务身份，并传递可验证的用户令牌，可以限制提示注入成功后的影响范围。这强调了权限设计不仅是访问控制，更是安全防线，需在系统层面强制执行，而非依赖模型判断。
追踪记录：排查问题的审计日志
文章强调，详细的追踪记录（包括用户请求、上下文、工具调用、权限检查等）是排查问题的关键。没有追踪，调查只能靠猜测。追踪应包含时间戳、工具参数和结果，并遵循与数据相同的访问控制和保留规则。这提醒开发者，追踪不仅是调试工具，更是合规和审计的基础。
测试与停止条件：应对非确定性
文章指出，代理是非确定性的，测试需多次运行并设定阈值。同时，代理应设计明确的停止条件，如需要更多信息、需要审批或升级到人工，并给出具体路径。这提醒开发者，代理不必完成所有请求，安全退出和清晰转交是产品设计的一部分，能减少未授权变更和后续清理工作。
Q&A
什么是AI代理的harness（框架）？为什么它对生产环境很重要？
AI代理的harness是应用程序围绕模型构建的脚手架，负责提供边界、工具契约、权限控制和上下文管理。它决定了代理能看到什么数据、能执行哪些操作，以及在缺少必要信息时如何处理。生产环境中的代理需要这样的包装来捕获失败，确保安全可靠运行。
在定义工具时，为什么需要区分可重试错误和终止错误？
因为模型会读取工具返回的错误信息并据此行动。可重试错误（如RATE_LIMITED）告诉代理可以重试，而终止错误（如APPROVAL_REQUIRED）则明确告知代理需要人工审批或无法继续，避免代理盲目重试导致重复操作或无效尝试。
为什么在AI代理中要将读工具和写工具分离？
读工具只返回数据，而写工具会改变数据或启动流程。分离后，写操作需要额外的用户确认和权限检查，这样可以在错误应用到客户记录之前使其可见，降低风险。
如何通过权限设计来防范提示注入攻击？
通过为每个工具分配独立的服务身份，仅授予所需的最小权限，并传递经过验证的用户令牌，而不是让模型填写参数。这样即使模型被恶意指令诱导，也无法访问超出权限范围的数据或执行未授权的操作。
构建代理上下文时应该遵循什么原则？
构建上下文要有目的性：先包含系统规则，然后是用户请求和任务状态，接着是用户有权查看的证据，最后是必要的近期历史。同时要决定哪些记忆需要持久化，丢弃过时细节，并记录每个上下文片段被包含的原因和更新时间，以便追溯。
为什么代理的追踪记录（trace）很重要？它应该包含哪些信息？
追踪记录是代理的审计日志，能帮助团队确定代理在特定请求中看到了什么，以及它执行了哪些操作。它应包含用户请求、上下文、工具调用、权限检查、最终响应等详细信息，以便在出现问题时提供清晰的调查起点。
如何为AI代理设计有效的测试场景？
测试场景应基于用户实际工作，如支持工单、事件报告等。使用固定的文档和工具响应，预设账户状态，以便失败测试可重复。包含正常任务、不明确请求、过时数据、工具不可用、需要审批的情况，以及多轮任务。由于代理非确定性，每个场景需多次运行并设定阈值。
代理在无法完成任务时应该如何处理？
代理应明确停止条件，并提供下一步路径。例如，需要账号信息时，应提供输入方式；需要审批时，应发起审批请求；需要人工介入时，应转交并附带完整追踪记录。设计这些停止条件作为产品的一部分，并在用户界面中可见。
