从一次 API 调用到完整 Agent Loop上下文到底如何流动摘要Agent Loop 常被简化成“模型返回工具调用就执行否则结束”的while True。这个 Demo 能解释主干却省略了生产最关键的部分供应商消息协议并不相同工具调用与结果必须正确关联最终文本不一定代表任务完成错误需要分类恢复循环还要受轮次、时间、token 和费用约束。本文从消息角色差异出发建立供应商无关的内部事件模型再给出包含校验、观测、恢复与安全停止的 Loop 状态机。关键词上下文工程、消息角色、工具调用、Agent Loop、调用轨迹、终止条件、max iterations、错误恢复CSDN 分类建议人工智能 / 大模型应用推荐标签AI Agent、LLM、智能体、大模型、Agent Engineering本文知识地图我们先拆“消息是什么”再看一次工具调用怎样往返最后把这个往返放进状态机。两张图分别回答谁产生什么消息以及循环在什么时候继续、恢复、完成或安全停止。图 1Agent 工具调用消息时序。来源作者依据 OpenAI 与 Anthropic 官方工具调用文档整理。读图重点是call_42模型输出的调用请求、执行器结果和下一轮上下文必须保持关联。由图可得的工程结论是工具结果不能作为一段无来源普通文本塞回模型否则并行调用、重试和审计都可能串线。先纠正“消息有四种角色”源稿以 OpenAI Chat Completions 风格说明system、user、assistant、tool四种角色。这对理解特定接口有用却不是跨供应商标准。Anthropic Messages API 的官方参考明确说明系统提示通过顶层system参数提供常规输入消息可用user与assistant并不存在把系统提示作为输入消息role: system的通用做法。事实Anthropic Messages API 工具调用则出现在内容块里模型返回tool_use应用执行客户端工具再用tool_result回传。事实Handle Tool CallsOpenAI Chat Completions、Responses API 和 Agents SDK 又有各自的消息或 Item 结构。工程结论不是发明一个“万能 role”而是在应用内部规范化少量语义事件再由适配器转换Instruction 开发者/系统约束 UserInput 用户或外部事件 ModelOutput 文本、结构化输出或调用请求 ToolCall call_id tool args ToolResult call_id result/error StateUpdate 任务进度、预算、环境状态这样业务状态机不依赖某家字段名。适配器负责遵守供应商的顺序、内容块、签名或调用 ID 规则日志层保存规范化事件与原始响应引用。上下文不是“消息列表”这么简单不论状态存在哪里模型在某个决策点实际可见的内容仍是关键。Anthropic 把上下文描述为采样时包含的 token 集合并强调它有限且需要策展。事实Effective Context Engineering 生产系统还要保存模型看不见但 Harness 必须知道的控制状态例如租户、授权票据、幂等键、剩余预算和审计元数据。这些不应全塞进 prompt。因此建议分成三层模型上下文模型决策需要的最小信息运行状态循环、预算、权限、取消信号、幂等和恢复点审计记录原始请求响应、策略判定、版本和环境证据。一次工具调用怎样完整往返以客户端工具为例通用时序是Harness 组装当前模型上下文和工具定义模型返回文本、工具调用或两者按协议允许的组合Harness 解析调用验证 Schema、业务语义、权限和预算执行器在受控环境运行工具记录耗时与副作用将结果或错误与原调用 ID 关联追加到下一轮上下文模型依据新观测给出最终输出或继续调用。Anthropic 官方工具文档区分客户端与服务端工具客户端工具由应用执行服务端工具由 Anthropic 基础设施执行。事实Tool Use Overview 所以“模型不执行工具”只对客户端工具这一层成立文章和代码应写清执行位置。OpenAI Function Calling 的 Structured Outputs 在strict: true时可保证参数匹配所给 JSON Schema。事实OpenAI Function Calling 但 Harness 仍必须验证订单属于当前用户吗金额在余额内吗此动作需要确认吗工具参数结构正确不等于动作安全。并行调用的关联规则模型可能一次请求多个无依赖工具。执行器可并行运行但结果返回顺序可能不同。不要按数组位置猜对应关系应以调用 ID 关联。上下文适配器还要遵守供应商对调用与结果相邻、顺序和内容块的要求。工具输出不要无限回灌网页、日志或数据库结果可能非常大也可能包含提示注入。工具层先做长度限制、结构化提取、来源标记和敏感信息处理原始结果保存到外部制品存储给模型的是任务所需摘要与可追溯引用。摘要是有损的涉及证据核验时允许模型按需读取原文片段。核心循环从 while 变成状态机图 2Agent Loop 状态机。来源作者依据 OpenAI Agents SDK 生命周期与生产错误处理模式整理。读图重点是两个出口完成与安全停止。由图可得的工程结论是“模型没有返回工具调用”最多表示一个最终输出候选不能自动证明外部任务完成相反预算耗尽时即使任务未完成也必须退出并报告可恢复状态。OpenAI Agents SDK 的官方运行文档说明Runner 会在模型输出最终结果时结束在产生工具调用时执行并追加结果后重跑超过max_turns会抛出MaxTurnsExceeded。事实Running Agents 这验证了轮次上限是当前生产 SDK 的一等概念但具体默认值与异常类型属于 SDK实现自己的 Loop 时不能照搬字段名。供应商无关的伪代码可以写成stateload_or_create_run()whileTrue:enforce_deadline_budget_and_max_turns(state)responsemodel(generate_context(state),available_tools(state))eventsadapter.normalize(response)ifevents.final_candidate:verdictverify_completion(events.final_candidate,state)ifverdict.accepted:returnfinalize(verdict,state)state.observe(verdict.as_error())forcallinevents.tool_calls:verdictpolicy.validate(call,state)resultexecutor.run(call)ifverdict.allowedelseverdict.as_error()state.observe(link(call.id,result))伪代码省略了并发、流式、取消和持久化却保留五个硬点每轮检查预算供应商响应先规范化最终输出独立验证调用先过策略成功与错误都成为观测。终止条件应该是组合条件只用if not tool_calls: break会产生两类错误模型过早给出文本或用文本询问澄清却被当作完成。生产 Loop 常组合以下条件完成信号模型返回指定结构、调用submit_result或工作流到达终态环境验证文件存在且测试通过、交易状态已提交、引用可访问用户交互需要澄清或审批时进入暂停而非完成安全停止达到max_turns、deadline、token、金额或调用预算不可恢复错误权限永久拒绝、资源不存在且无替代路径、策略禁止。完成信号是候选环境验证才决定能否交付。安全停止要返回当前状态、已发生副作用、未完成事项和恢复标识方便之后续跑。max iterations 不是随手填一个数字轮次上限过低会截断正常任务过高会放大循环成本和风险。工程经验是从任务族统计分布出发记录成功任务所需轮数、长尾失败和每轮成本为不同工具风险设置差异化预算。例如只读检索可以给更多轮高风险写操作不仅轮次更低还应限制每类工具次数。除了总轮次还要检测“无进展循环”同一工具与同一参数重复、错误签名重复、状态哈希不变、计划反复切换。检测到后可注入明确观测、切换策略、请求用户信息或停止。不要让模型自己数历史调用次数Harness 应用代码维护计数。错误恢复先分类再决定动作错误类别例子合理动作瞬时基础设施429、短暂超时、连接重置指数退避、抖动、遵守 Retry-After参数/格式Schema 失败、枚举值错误把精确错误送回模型限制纠参次数业务拒绝余额不足、状态不允许不盲目重试换方案或询问用户权限/策略越权、缺审批、高风险禁止停止执行走授权或人工路径部分成功邮件已发但数据库更新失败查幂等状态补偿或人工处置模型协议调用 ID 丢失、内容块非法适配器拒绝保存原始响应并回退恢复必须知道副作用是否已经发生。超时不等于失败支付请求可能服务端已成功只是客户端没收到响应。执行器应使用幂等键并先查询状态避免重复执行。上下文增长与恢复点长 Loop 不应只存在进程内存。每轮完成后持久化规范化事件、预算、工具副作用和可恢复游标。恢复时重建供应商上下文但不要把所有审计字段喂给模型。对非常长的轨迹使用结构化状态、压缩摘要与按需制品引用第四、五篇会继续讨论缓存、压缩和隔离。常见误区与修正误区一所有厂商都有四种相同角色。修正按官方规范实现适配器Anthropic Messages 的系统提示在顶层工具用内容块表达。误区二每次 API 调用都绝对无状态。修正客户端全量历史是一种方式当前接口也可续接服务端 response、conversation 或 session 状态权衡可编辑性与治理。误区三无工具调用就是完成。修正它只是最终输出候选结合结构、环境证据和业务终态验证。误区四工具错误直接变普通文本。修正保留调用 ID、错误类型、是否可重试和副作用状态。误区五max_iterations10能解决循环。修正还要有时间、费用、工具次数和无进展检测并按任务族校准。生产检查清单每家模型接口有独立适配器和契约测试不假设角色相同。内部事件区分指令、用户输入、模型输出、调用、结果和状态更新。并行工具调用以call_id关联不依赖返回顺序。工具输出限制长度、标记来源、脱敏并保留原始制品引用。最终输出经过结构、业务和环境证据验证。Loop 同时限制轮次、时间、token、费用和高风险工具次数。检测重复参数、重复错误和状态无进展。瞬时、业务、权限、部分成功和协议错误采用不同恢复策略。工具有超时、取消、幂等键与副作用查询接口。每轮持久化恢复点停止时报告已完成、未完成和已发生副作用。本文小结Agent Loop 的本质不是一个while而是一套消息协议适配、运行状态、策略校验、工具执行、环境观测和终止判定。供应商 API 的角色与内容块并不通用应用应规范化语义事件并保留原始关联。最终文本只是完成候选环境证据、硬预算和错误分类共同决定循环是交付、继续、暂停、恢复还是安全停止。下一篇将深入循环的推理成本Chat Template、KV Cache、跨请求 Prompt Cache 与前缀稳定性。延伸阅读与参考资料官方 API 与 SDK 文档Create a MessageAnthropic Messages API。V1-R015Tool use overviewAnthropic。V1-R003Handle tool callsAnthropic。V1-R017Running agentsOpenAI Agents SDK。V1-R018Function Calling in the OpenAI APIOpenAI。V1-R004官方工程文章Effective context engineering for AI agentsAnthropic。V1-R005系列导航上一篇真正拉开 Agent 差距的 Harness 工程编排、护栏与模型选型总目录深入理解 AI Agent从模型能力到生产级系统的完整路线图下一篇KV Cache 不是性能小技巧而是 Agent 上下文架构约束ture.md)