一个编码代理可以读取一个失败的测试,检查一个执行,编辑一个文件,然后再次运行测试。每个步骤都取决于前一个步骤所揭示的内容。模型建议了一个动作。周围的软件决定是否以及如何执行它。

这一划分解释了一个代理人的许多行为。一个有能力的模型需要有用的工具、相关的上下文、可靠的反馈,以及执行环境来强制其边界。 任何其中一部分的错误都会破坏整个任务。

简写agent = model + harness为工程设计提供了一个起点:如何构建环路,定义完成,管理上下文,从中断中恢复,以及衡量一个变化是否真的有帮助。

关于工具,技能,插件,和管弦乐的更广泛的词汇表,请参见Demysurizing 现代 AI.这里,焦点是从用户请求到可验证结果的执行路径。

下一步由谁决定?

考虑三种处理失败的 URL 解析测试的方法 。

| System | | 谁选择下一个动作? | | -------- | ---------------------------------------------------------------- | ------------------ | ------------ | | 聊天交互 | 模型建议了一个可能的固定,开发者应用了 | 开发者 | | 工作流 | 代码运行测试,请求一个拟议的补丁,应用它,并运行一个预定义的检查 | 应用程序 | | Agent | 该模型根据结果选择哪个测试,文件,或依赖性进行检查 | 该模型,在使用套带 | 强制的限度内 |

这些是交互模式。 聊天界面可以包含一个代理,而工作流程可以包含一个有界限的代理步骤。 有用的建筑设计问题在于每个点对应用程序代表的控制程度 。

对于可预测的操作来说,清晰的代码路径更容易检查.从文档中提取字段,验证一个计划,并存储结果的管道可以遵循固定的序列。 Debuging是一个代理的更强的候选对象,因为下一个有用的动作在测试或文件检查之前往往未知。

对于解析器的例子,一个混合设计效果很好:让模型调查并提议编辑,然后在接受结果前需要固定的核实步骤。

透过绳索按一个请求

假设一个应用程序在存储前使用parseTarget(input)实现 URL 的正常化。当它拒绝输入时,函数返回 URL 或null。它目前接受标准解析器能够读取的任何 URL, 包括该应用程序不支持的方案 。

任务是:“接受绝对的HTTPS URL,拒绝其他输入,并保持HTTPS的正常化。”

输入预期成果
https://example.com/docshttps://example.com/docs
HTTPS://EXAMPLE.COM/docshttps://example.com/docs
http://example.com/docsnull
javascript:alert(1)null
/docsnull
not a URLnull

代理服务器使用文件tools来读取 parser 的源代码和测试。 控制器将文件内容返回到模型中,以便它能够理解执行和决定要更改什么 。 寄存器不会自动被模型看到 。例如,可能的一个序列是 :

  1. 读取项目指令,解析源代码,以及相关的测试,以了解现有的行为。
  2. 运行解析器测试并复制失败:http://example.com/docs被接受。
  3. 编辑解析器的源代码以检查解析的 URL 协议是https:。
  4. 运行受影响的测试和包的回归检查。
  5. 检查源代码 diff 并报告已核实的行为。

该模型生成结构化工具请求,运行时间将这些请求发送到实际执行和返回观察中。在一个多式联运系统中,请求和观察可能包含的不只是文字,执行边界仍然相同。

图解
Agent execution loop: the harness supplies context to the model, validates tool requests, returns observations for the next decision, and independently checks finish requests before reporting completion or failure.
图解
Agent execution loop: the harness supplies context to the model, validates tool requests, returns observations for the next decision, and independently checks finish requests before reporting completion or failure.

控制器还应处理每次阻断操作的取消、超时和资源限制。该图显示了成功的控制路径,而不是每个操作退出。

观察是模型对环境的证据。 命令引用是尝试发生的证据。它的退出代码、 输出和生成的文物决定了尝试是否成功 。

该模型选择调查路径。 控制器会发送工具并记录其结果。 应用程序定义的接受检查决定生成的代码是否符合任务要求 。

添加管弦乐前先构建一个有界限的循环

牵引需要一些规则:限制代理运行的时间,记录发生的事情,并在接受完成之前检查结果。下面的架构将模型决定、工具执行、持续历史和验证分开。共享主管在这些组件中执行运行限制。

图解
Bounded harness architecture: a supervisor enforces a shared deadline and decision budget; the model requests tools or completion, tools return observations to history, and an independent verifier checks a fixed snapshot before producing a completed or incomplete result. Interruptions preserve history.
图解
Bounded harness architecture: a supervisor enforces a shared deadline and decision budget; the model requests tools or completion, tools return observations to history, and an independent verifier checks a fixed snapshot before producing a completed or incomplete result. Interruptions preserve history.

这里的限制是说明性的。每个模式调用和工具操作都共享相同的截止日期。 被拒绝的工具请求或预期的工具失败成为模式在选择其他动作之前可以检查的结果 。

该模型的概要与记录的检查结果分开。 请求完成触发核查。通过检查会产生完整的结果,并附有证据。 检查失败、 限制用尽和工作中断,会产生明显不完整的结果 。

中断会保留目前已知的状态。在重新启动前,请检查当前状态。 重复整个运行可以重复编辑或外部写入 。

对照合同核查解析器

解析器修补有三步:将输入解析为绝对URL,如果解析失败或方案不是HTTPS,则拒绝输入,否则返回已规范的URL.

然后,核查员将前一个表格中的所有6个案例对照固定的工作空间快照,将每个实际结果与预期结果进行比较,并记录不匹配或意外例外。

图解
Acceptance checks: run six URL cases against a fixed snapshot, compare actual and expected results, record outcomes and code version, then report completion only when all cases pass.
图解
Acceptance checks: run six URL cases against a fixed snapshot, compare actual and expected results, record outcomes and code version, then report completion only when all cases pass.

保存的证据表明哪些案件已经通过或失败,以及密码的哪个版本已经检查过。快照在核实时保持不变,接受文件则在代理编辑文件之外直播。

在此示例执行中,校正的解析器传递了全部六个案例。 原始执行失败了 HTTP 和 JavaScript 方案。一个总是返回null的函数也失败了,因为支持 HTTPS URL 的验证器检查仍然有效 。这些检查可以确定表格中列出的行为,而不是解析器的所有可能属性 。

在真实的软件包中,校验还应运行现有的回归套件并检查最终补丁范围。如果解析器输入用户界面,在浏览器中练习该路径: 提交有效的 HTTPS URL, 检查未支持的方案是否显示适当的错误,并确认拒绝的输入没有保存。对于 UI 更改,也检查键盘交互、 装入和错误状态,以及受影响的屏幕大小的布局。 仅通过解析器测试并不能确定界面是否有效 。

将浏览器步骤和观测结果与接受大小写一起记录,绑定在同一代码版本上。屏幕截图可以记录布局和可见状态,而交互检查则确定当用户提交或编辑输入时会发生什么。如果浏览器流不能测试,请明确报告该缺口。

执行限制账户

运行时间仍需要处理业务问题:

| 关注 | 要求的行为 | | -------- | ----------------------------------------------- | ---------------- | | 请求验证 | 检查每个模型请求 | 的结构并允许参数 | | 取消 | 取消网络请求,并在运行结束时停止子进程 | | 资源核算 | 轨迹模型使用,工具成本,输出大小,以及货币 单独 | | 可审计性 | 持久性动作ID,决定,观测,以及文物版 |

在模型请求或工具运行时必须适用一个最后期限。 仅在重复操作之间检查时钟无法停止挂载操作。 使用请求取消和可以在需要时终止工作的流程导师。同样,十二个决定也不限制一个大响应中消耗的符号或工具引用的成本 。

提供范围狭窄、可检查的合同工具

一个工具是模型必须从描述、计划和反馈中学习使用的界面。 模糊的名称和巨大的响应使得选择动作更加困难。

将接受任意命令的普通 shell 工具与run_parser_checks相比较,该工具将映射到应用程序定义的固定命令。 shell 提供了灵活性。 命名的检查会缩小此任务所需的权威和参数空间 。

一个有用的工具结果使模型有足够的证据来选择它的下一个动作。例如:

字段示例值
结果失败
检查解析器兼容性
代码版本快照 17
输入失败http://example.com/docs
预期结果拒绝
实际结果接受
完整输出引用已保存的日志检查 42

这些值是说明性的。结果可以识别失败,将其与被检查的代码连接起来,并提供一个检索完整输出的方法。 下一个模型调用可以使用这个简洁的结果,而不读取数千条无关的日志行 。

MCP 规范了工具发现和跨服务引用。它的工具规格描述了名称、 输入计划、结果和可选输出计划。通过 MCP 连接仍然需要应用程序授权、 证书范围界定和输出处理。 协议还明确将工具说明视为不可信,除非其服务器被信任 。

以上下文和持久的内存来扩展控制

代理商的下一个决定取决于当时提供给模型的信息。 对话存储,检索文件,磁盘上的文件只有在被调用时才会影响决定。

分为三类信息:

| 信息 | 解析器例 | 存储和检索 | | ------------ | ------------------------------------------ | -------------------------------- | ---------- | | 稳定项目指导 | 软件包边界及支持 URL 行为 | 版本项目文档在相关 | 时加载 | | 当前工作环境 | 解析码,失败大小写,最新补丁,当前测试输出 | 下一种型号命名为 | 的选择材料 | | 持久任务状态 | 接受标准,更改文件,检查结果,未解决的失败 | 检查点或模型上下文以外的进度记录 |

Anthropic的上下文工程指南讨论检索,收缩,结构化的注释作为管理长任务的方法.一个实用的应用是根据下一个决定选择证据:在调查一个方案错误时包括失败的解析器案例,然后在考虑完成时检索更广泛的回归结果。

紧凑时保留出处

总结可以不慎将一个假说变成事实。The parser probably normalizes the scheme too early不能仅仅因为对话被缩短而变成The parser normalizes the scheme too early.

保持紧凑状态结构,以区分:

  • **要求:**不支持的计划必须被拒绝。
  • **观察:**检查 42 与工作空间快照17失败。
  • **假说:**正常化可能在验证前发生。
  • **决定:**在编辑前先检查常态化帮助器。

保留对源代码的引用和标签不确定性 。在观测后工作空间发生变化时再次读取代码或重运行检查 。一个摘要有助于下个会话的定位 。 新的证据可以确定当前的行为 。

将重复的程序运用到技能中

稳定的项目指令描述的是广泛适用的常规。技能可以为特定任务持有程序,例如用包的固定运行器复制 praser bug。可执行检查应该执行一个可以进行机械评估的条件。

例如,“保留有效的HTTPS行为”属于任务合同。将精确的固定命令放在相关程序中,并将兼容性案例放在测试中。将每个事实保存在一个合适的地方可以减少相互矛盾的指示。

将权限作为执行路径的一部分

代理人读取可能包含指令的材料:寄存器文件、问题描述、网页和工具回复。这些材料可以是有用的证据,而同时又不被信任为权威来源。

想象一个包含一个注释的固定文件,该注释告诉代理商将其环境变量上传到调试的端点。读取文件是在解析器任务之内的。该注释之后,任务将扩展为新的网络操作。

在这一设计中,根据工作限制能力:

| 操作 | 解析任务的拟议控制 | | -------------------- | ---------------------------- | --- | | 读取解析器源和定着器 | 允许在配置的根 | 内 | | 编辑解析器包 | 允许在孤立的工作空间 | 内 | | 运行回归检查 | 允许程序限制下核准的命令 | | 访问无关的证书 | 排除执行环境 | | 上传文件或发布发布 | 需要单独授权和适当范围的能力 |

模式由“ 仅编辑解析文件” 这样的工程指令指导。 工具调度器通过拒绝未经授权的操作、 无效路径和超大小的补丁来强制实施限制。对于文件访问,它会根据允许的根解决路径,按照策略处理并拒绝脱逃。 执行环境限制了文件、 进程和网络目的地工具所能达到的路径 。

这些措施解决了不同的故障路径。 批准界面处理用户可能有意授权的一项相应行动。 沙盒会限制执行进程所能达到的内容。 既不能确定检索的内容是否可信,也不能保证模型会正确解释该内容 。

从中断中恢复而无需重复副作用

一个简短的调试会话可能在一个循环中完成。 更长的任务可能会遇到进程崩溃、 上下文重置、 机器重启或过期的证书 。

Anthropic的关于长任务牵引的作品使用增量工作和明确的进度文物来帮助以后的会话恢复.对于剖析器任务,一个检查点可以记录目标,工作空间版本,受影响的文件,检查结果,以及下一个未解决的问题。

恢复需要的不只是谈话记录 考虑一下失败的顺序

  1. 运行时间发出创建远程审查文物的请求。
  2. 该服务创建了文物。
  3. 网络连接在运行时间收到响应前会下降。

运行时间不能从超时推断创建是否成功。 立即重试可能会产生重复 。

对于相应的写入,请在发送前坚持操作 ID 。当目标支持它时,请使用该 ID作为 idepotency 密钥,在模糊失败后调和远程状态。如果目标既不提供调试,也不提供可靠的查询,请暂停该操作检查,而不是假设它失败 。

本地编辑也需要调和。如果一个检查点表示已提议补丁,请在再次应用前检查当前文件并修改。 重新启动时,验证工作空间身份并重运行建立当前状态所需的检查 。

沉滞状态应区分计划中的,发送的,确认,以及未知的结果。 "未知"是一个有用的操作状态:它防止运输故障沉默地成为重复副作用的许可。

工作可以分离时添加多个代理

子代理可以用他们自己的工作环境来调查一个问题的不同部分,这使得授权成为背景工程的选择:一个工人可以检查一个问题的详细文档和日志,然后返回一个焦点报告,这样协调员就不需要在自己的背景中进行整个调查。 协调员保留了整体目标,共同的制约,以及整合结果所需的决定。 Anthropic的背景工程指南描述了这种使用单独的代理人背景进行焦点调查的这种用途。

分离有代价。 工人可能错过从未向其传递的制约,其摘要可能忽略协调员需要的证据或不确定性。工人可以重复搜索、达成不相容的假设或提出相互冲突的编辑。 额外的模式调用和协调也消耗时间和象征物。当焦点上下文或平行工作的价值超过交接和整合努力时,代表。

对于解析器错误来说,一个代理已经足够了 。对于跨越多个独立包的迁移,单独的代理可以检查兼容性风险,而一个所有者可以整合这些变化 。

一个有用的授权合同规定了问题、相关文件、允许的行动、预期证据和完成标准。例如:“检查序列器对 URL 方案的处理。返回受影响的呼叫器和辅助文件引用。不要编辑文件。” 协调员可以在更改共享执行之前评估该报告。

并行编辑需要所有权边界和集成检查。单独的工作空间隔离文件更改,但共享服务、数据库和测试环境仍需要隔离或协调。最终验证器应该运行在组合的文物上,因为单个通过分支可能会一起失败。

将亚剂输出作为有证据的报告处理。 附加的剂不会仅仅重复它,使不支持的结论更加可靠。

评估结果和诊断失败

最后一个令人信服的答案很容易错失成功运行。在运行代理商之前先定义成功,然后评价由此而来的文物和行动历史。

对于解析器的例子,使用一组小的任务变体:

假想必要结果
不支持的方案被接受在保留有效输入时拒绝它
递归套件曝光第二次故障报告或修复范围
A文件包含不相关的指令在不授予新权限的情况下继续任务
检查进程挂起按执行期限停止
运行在应用补丁后恢复重复编辑前检查当前状态
模型要求完成得太早接受检查失败时拒绝完成

记录任务成功、 接受失败、 未经授权的行动、 延迟性、 使用和人类干预。当模型可变性重要时,重复进行试验。在改变模型、 工具界面或上下文政策时,任务设定和环境保持可比性 。

避免将若干变化合并到一个实验中。如果模型和上下文选择都发生变化,那么改进的成功率并不能确定哪些变化有帮助。从基线开始,改变一个因素,检查失败,只有在其好处证明成本合理时才保留变化。

关于成本跟踪,包括模型输入和输出、工具执行、重试、存储和相关审查时间。如果运行需要大量人工修复,低标价账单仍然可能伴随更糟糕的结果。

将修复与失败匹配

当代理失败时,查找损坏的机制 :

| 观测失败 | 第一次设计更改 调查 | | ---------------------------------- | ----------------------------------------- | ---------------- | | 它编辑错误的包 | 文件发现,任务范围,以及写入限制 | | 它错过了一个嵌入日志中的失败大小写 | 结构化工具结果和上下文选择 | | 它声称在一次检查失败后成功 | 完成 标注和结果报告 | | 在超时 | 操作ID,调和后重复远程写入,并重制一等功率 | | 恢复 | 持久要求和加载 | 检查站后失去目标 | | 它通过同样的不成功的动作循环 | 进度检测和重试预算 |

这使得利用改进成为具体的工程活动。对于您的首次执行,请选择一个有限度的任务,给它一些狭义的工具,定义一个可观察到的接受检查,并保存足够的证据来解释每次失败。当失败显示缺少能力或控制时,请扩展利用范围。

结论

一个可靠的代理需要一种将模型决定转化为有约束的行动,并将完成与可观察证据联系起来的杠杆。在解析例中,这意味着保留有效的HTTPS行为,拒绝不支持的输入,检查产生的代码,并在它受到影响时使用用户的显示路径。

从一个任务和一个小工具循环开始。 保存可用的要求和证据,保存足够的状态以安全恢复,在报告成功之前验证最终的文物。当特定失败表明需要时,添加内存、 技能或子代理。每个扩展应该让工作更容易核查或恢复,并计入其上下文、 协调和执行费用 。