这两年聊 Agent 的人很多但真正把 Agent 做大、做稳、做出可用性的团队并不多。市面上大量项目都能在本地跑通一个“会调工具”的 Demo可一旦放进生产环境问题就全冒出来了上下文越滚越长导致费用失控、多步调用之间状态错乱、工具返回格式一换模型就懵、偶发重试引发重复扣款或重复下单。这些问题大多不是模型的锅而是出在支撑 Agent 运行的 Runtime 上。Agent Runtime 到底是什么简单说它就是一个把“大模型 工具 记忆 外部系统”串起来的执行环境和编排底座。模型负责生成想法Runtime 负责让想法安全、稳定、可重复地落地。这篇文章不聊某个框架的用法而是把编排技术的底层原理、关键抽象、工程取舍和落地代码完整拆开讲一遍。我的目标很直接你看完能自己设计出一套真正好用的 Agent Runtime而不是被玩具 Demo 困住。1. 先拆清楚Agent Runtime 到底在解决什么问题1.1 模型不是主角Runtime 才是长期工程的主战场我见过不少团队把精力全押在模型调优上觉得“换一个更强的模型Agent 就能变好用”。这个想法只对了一半。模型决定的是“聪明程度”Runtime 决定的是“能跑多远、多稳、多安全”。打个比方模型像是发动机Runtime 是整个底盘和驾驶系统。发动机再好没有方向盘、刹车、仪表盘、变速箱的配合你也跑不了长途更别说上路载客。很多团队试点失败不是模型不够聪明而是 Runtime 太简陋没有状态管理没有重试策略没有权限控制没有可观测性出了问题只能看日志猜测。所以如果你正在设计一套 Agent 系统第一件事不是选模型而是先定义 Runtime 的边界和职责。它至少要管住四件事怎么循环决策、怎么调用工具、怎么管理记忆和状态、怎么控制成本和风险。1.2 Agent 的五个核心抽象循环、工具、记忆、状态、边界拆开市面所有 Agent 框架底层抽象其实就是五样东西抽象职责最常见的坑循环Loop决定 Agent 下一步做什么是“推理→行动→观察”的重复过程死循环没人管Token 烧光才发现工具Tools让 Agent 与外部系统交互的接口包括函数调用、API、数据库查询参数校验不严模型返回错误格式直接崩溃记忆Memory短期上下文窗口内的对话历史以及长期持久化的用户偏好、业务事实无限塞上下文费用和延迟一起涨状态StateAgent 当前运行到哪一步、携带了什么变量、计划是什么多轮并发时状态互相污染边界Boundary权限、配额、可调用范围、人工审核节点越权调用高危工具出安全事故五者缺一不可。很多轻量框架只实现了循环和工具把记忆直接塞进 prompt状态放在内存变量里边界完全不做这样的东西 demo 可以生产环境分分钟出事。1.3 好用的 Runtime 需要同时满足的硬指标有了抽象之后我们可以给“好用”下一个更工程化的定义。我在实际项目里会拿五条硬指标来评估一套 Runtime 是否合格确定性同样的条件下Agent 的行为模式应该是可预期的而不是每次跑出来的流程都不一样。可恢复性中途失败后能从上一步继续不需要整个任务推倒重来。可观测性每一步的输入、输出、耗时、费用都记录在案能回放、能定位问题。资源可控Token、调用次数、并发数都有上限不会被一次异常任务拖垮整个系统。边界安全Agent 只能访问它该访问的资源高危操作必须经过审批或二次确认。从这五条指标往回看很多框架的设计其实是不合格的。比如只暴露一个run()方法内部细节全封装起来出了问题不知道该从哪里查再比如循环没有次数限制模型陷入自我对话时只能靠人工 kill。这些都不是模型问题是 Runtime 设计问题。2. 底层原理主循环是怎么设计出来的2.1 两种典型主循环形态Agent 的核心是循环。主循环的形态决定了整个系统的工作方式。现在主流的有两种一种是 ReAct 风格的反应式循环另一种是 Plan-and-Execute 风格的先规划再执行循环。反应式循环的逻辑很直接把当前状态和可用工具描述交给模型模型决定调用哪个工具得到结果后再次进入推理如此循环直到模型判定任务完成。它像一个人边想边做。优点是灵活遇到意外情况能及时调整缺点是每次都要把全部历史塞进上下文Token 消耗大而且容易走一步看一步缺乏全局规划。先规划再执行则分为两个阶段模型先面对任务输出一份完整计划然后 Runtime 按照计划逐步执行工具最后汇总结果。它像项目经理先出方案再分派任务。优点是全局视角好上下文占用相对稳定缺点是一旦实际情况偏离计划Agent 需要重新规划灵活性差。实际工程里纯用一种的很少。我的做法是把两者做一种嵌套用 Plan-and-Execute 生成高层计划在每一步计划执行时再用反应式循环处理细节。这就像你先规划好旅行路线路上遇到封路再临时调整而不是一出门就靠直觉乱走。维度ReAct 反应式Plan-and-Execute灵活度高随时调整低计划变更成本高Token 消耗高历史全程在上下文里低计划固定在上下文步骤局部化崩溃风险容易绕进死循环计划跑偏后结果偏差大适合场景客服对话、动态决策数据流水线、批处理任务2.2 每一步发生了什么一条 Agent 消息的完整旅程要设计好 Runtime先要把一次普通调用的生命周期拆到足够细。我习惯把它拆成八个阶段接收用户输入解析出任务和对话上下文。从状态库加载当前会话状态包括长期记忆。组装 prompt把所有可用工具的描述按统一格式注入。调用模型拿到原始输出。解析模型输出识别是最终回答还是工具调用请求。如果是要调用工具先做参数校验再执行工具。把工具结果写回上下文更新状态。回到步骤 3直到满足终止条件。看起来简单但每一步都有坑。比如第三步工具描述怎么写会影响模型判断第五步模型输出不一定是合法的 JSON有的是 Markdown 包着的有的带多余前缀第六步工具可能抛异常也可能返回超长结果这些都要预处理。这也是为什么我不建议直接在一个团队的核心业务里裸调模型接口。没有 Runtime 这层包装你需要在业务代码里反复处理这些脏活最后代码会膨胀到没法维护。2.3 上下文管理短期记忆的读写原则上下文管理是 Runtime 最容易做崩的环节。很多初版实现就是“把所有消息都塞进 messages”结果对话超过二十轮后每轮请求的吃 Token 量成倍增长费用和延迟一起失控。我踩过坑之后总结出一个原则上下文里只保留“对下一步决策有影响的信息”其他都丢到外部记忆里。具体做法是这样把上下文分成三个区域。第一个区域是系统指令包含角色设定和任务约束基本固定不变。第二个区域是工作上下文指当前任务的实时状态、最近的模型输出、最近若干轮工具结果。第三个区域是压缩后的历史摘要由之前的对话总结生成放在工作上下文之后作为背景信息。工作上下文设置一个 Token 预算我用的是总窗口的三分之一超过就触发压缩策略。压缩不是粗暴地截断而是让模型做一次摘要把关键结论、已确认事实、未完成事项提炼出来替换掉原始对话。你需要维护一个上下文管理器伪代码逻辑是这样的class ContextManager: def __init__(self, budget): self.budget budget self.working [] self.summary def add_message(self, msg): self.working.append(msg) if self.estimate_tokens(self.working) self.budget: self.summary self.summarize([self.summary] self.working) self.working [] def build_messages(self): return self.system_prompt self.working [self.summary]这里的summarize可以调用一次廉价的摘要模型。不要小看这一层设计它在长会话场景下能直接砍掉一半以上的 Token 成本。2.4 状态机与状态持久化Agent 的主循环本质是一个状态机。状态至少包括未开始、计划中、执行中、等待工具结果、已完成、失败、终止。很多 Runtime 把状态写成一个简单的布尔变量任务开始置 True结束置 False这是不够的。真实场景中我需要知道 Agent 当前在计划中的哪一步、等待哪个工具、已有哪些结果。所以状态对象应该包含三个部分阶段标识、运行步骤序号、关键变量快照。状态持久化同样重要。如果 Agent 执行到一半进程崩溃重启后没有状态恢复整个任务就要重跑。对于长耗时任务我会在每次工具调用前后都做一次快照把状态序列化成 JSON 存到外部这样即使服务器重启也能从最近一次快照继续。请记住状态是运行时的心脏。状态设计得好Agent 才能被监控、被恢复、被调试。状态设计得烂你连“现在到底发生了什么”都说不清楚。3. 工程落地从能跑通到能上线3.1 可观测性要前置没有 tracing 的 Agent 等于盲飞Agent 的调试难度远超普通应用。普通接口出错报错信息直接指向某一行Agent 出错却可能是多轮推理一路累积出来的偏差。没有可观测性排查 Agent 问题就像在黑暗里修一个不断变化的装置。我的做法是给每次 Agent 运行分配一个全局唯一 ID并把整个运行过程记录成树状结构。根节点是一次完整任务子节点是每一轮循环孙节点是具体的工具调用。每一层都记录输入摘要、输出摘要、耗时、Token 用量、费用。具体的日志结构长这样我用 JSON 存储每个 span{ run_id: agent_20250914_abc123, step: 3, parent: agent_20250914_abc123, type: tool_call, tool_name: query_order, input: {order_id: A123}, output_preview: 订单状态: 已发货, token_usage: {prompt: 2180, completion: 340}, latency_ms: 1204, error: null }每个工具调用都记录一次即使失败也不跳过。这样当运营反馈“某个任务结果不对”时我可以直接拉出该任务的完整回放看到底是模型在第三步做出了错误判断还是第五步工具返回了脏数据。3.2 并发与隔离多 Agent 协作时的常见事故Agent 系统一旦上线很快就会面临并发场景。多个用户同时发起任务或者一个复杂任务内部产生多个并行子任务。这时候最容易翻车的是共享状态。我有一次线上事故就是典型的全局变量串数据。代码里有一个current_context全局字典每个 Agent 运行时都要读写它结果两个用户的任务互相覆盖A 用户看到的执行结果其实是 B 用户的。修复方式是把所有状态都放进一个按 run_id 隔离的上下文对象里并且通过依赖注入传给每一步执行函数而不是在代码里读全局变量。隔离设计有几条硬规则。第一运行时上下文必须永远是局部变量只允许显式传递。第二模型的 API Key、用户 ID、业务参数都从上下文读取不允许放在模块级别共享。第三并发调度采用单任务单执行器的模型每个任务独立一个状态机实例。class AgentExecutor: def __init__(self, state_store, tool_registry): self.state_store state_store self.tool_registry tool_registry async def run(self, run_id, initial_input): state await self.state_store.load(run_id) if state is None: state AgentState(run_idrun_id, current_inputinitial_input) while not state.is_terminal: step_result await self.execute_step(state) state step_result.new_state await self.state_store.save(state) return state.output每个 run_id 对应一个状态实例互不干扰也方便做限流和配额管理。3.3 失败重试与补偿模型不稳编排要稳大模型的输出天然具有不确定性。工具调用时可能遇到网络超时、服务 5xx、参数格式错误、业务校验不通过。Runtime 要做的不是指望模型不犯错而是把错误变成可控流程。重试策略分三个级别。第一级是网络层重试针对超时和 5xx使用指数退避间隔从 1 秒递增到最多 30 秒。第二级是解析层重试模型输出格式不规范时把错误信息反馈给模型让它重新生成一次。第三级是业务层补偿工具调用成功但业务结果异常时触发回滚或人工介入。这里最关键的是幂等性设计。Agent 调用“创建订单”“扣款”“发短信”这类操作时如果重试导致重复执行后果很严重。我要求每个工具都实现一个幂等键机制入参里带一个由 run_id 和步骤序号生成的唯一键服务端记录已执行过的键重复请求直接返回上次结果。async def call_with_retry(tool_func, payload, max_retries3): delay 1 for attempt in range(max_retries): try: return await tool_func(payload) except TransientError as e: if attempt max_retries - 1: raise await asyncio.sleep(delay) delay * 2 except ParseError as e: payload[correction] str(e)3.4 权限与安全边界给 Agent 戴上笼头Agent 能主动调用工具这件事本身就意味着安全边界需要比传统系统更严格。我见过一个 DemoAgent 能直接查数据库、发邮件、改配置所有操作一把梭。平时没问题一旦某个用户的 prompt 诱导模型调用高危工具就出大事了。防范的核心是“最小权限”和“分级审批”。先按工具的危险程度分级。只读工具如查询订单、搜索文档Agent 可以自主调用。写操作如更新数据库、发送消息必须有权限策略校验。高危操作如删除数据、转账、批量修改必须进入“人工审批”状态给用户发送确认请求用户确认后任务才继续。在每轮工具调用前Runtime 都要过一遍权限矩阵。这个矩阵包含三行信息当前用户角色、目标工具、操作类型。命中高危规则时工具不会被执行而是返回一个“待确认”状态给模型由模型向用户提问。另外工具返回的内容不能直接无条件塞进上下文。我在执行工具后加了一层输出清洗过滤掉敏感字段和超长文本。这里的逻辑是上下文越干净Agent 越不容易被误导。4. 最小可用 Runtime 的落地样板附代码前面讲了很多原则现在给一个可以直接抄作业的最小实现骨架。这个骨架不针对特定业务但把循环、工具、状态、观测点都串起来了。4.1 核心数据结构定义我习惯用数据类来定义核心对象清晰且不容易出错。from dataclasses import dataclass, field from typing import Any, Callable, Optional dataclass class Tool: name: str description: str parameters_schema: dict func: Callable dataclass class AgentState: run_id: str history: list field(default_factorylist) current_task: Optional[str] None plan: list field(default_factorylist) step_index: int 0 terminal: bool False output: Any NoneTool里的parameters_schema是模型决定参数格式的依据也是 Runtime 校验参数的标准。状态对象包含了所有运行信息可以整体序列化保存。4.2 一个可运行的主循环主循环最核心的就是控制终止条件。我在实现时设置了两层保护最大循环次数和最大连续失败次数。class MinimalAgentRuntime: def __init__(self, tools, max_steps10): self.tools {t.name: t for t in tools} self.max_steps max_steps async def run(self, state, model_call): while not state.terminal and state.step_index self.max_steps: messages self.build_messages(state) response await model_call(messages) intent parse_response(response) if intent.type final_answer: state.terminal True state.output intent.content break if intent.type tool_call: result self.execute_tool(intent) state.history.append({ role: tool, name: intent.tool_name, content: result }) state.step_index 1 return statebuild_messages会把系统提示、当前任务和近几轮历史拼出来parse_response负责把模型的非结构化输出解析成final_answer或tool_call。4.3 工具注册与参数校验工具不能直接执行模型给的参数必须先校验。校验方式很简单用 JSON Schema 检查参数结构。如果校验失败把错误信息作为工具结果返回给模型让它修正参数。def execute_tool(self, intent): tool self.tools.get(intent.tool_name) if tool is None: return {error: f工具 {intent.tool_name} 不存在请检查工具名} errors validate_parameters(tool.parameters_schema, intent.arguments) if errors: return {error: f参数校验失败: {errors}} try: return tool.func(**intent.arguments) except Exception as e: return {error: f工具执行异常: {type(e).__name__}: {e}}这样做的好处是工具函数本身不需要防御非法参数Runtime 已经在入口处拦住了大部分错误。4.4 异步化与超时控制真实环境不能允许一个工具调用无限期卡住。我给每个工具调用都包了一层超时控制。async def execute_tool_async(self, intent, timeout30): tool self.tools.get(intent.tool_name) if tool is None: return {error: unknown tool} try: return await asyncio.wait_for( tool.func(**intent.arguments), timeouttimeout ) except asyncio.TimeoutError: return {error: f工具 {intent.tool_name} 执行超时}异步化之后整个 Runtime 就可以很好地接入队列系统。任务进来后先落库再异步执行执行完再回调通知结果而不是让 HTTP 请求一直占着连接。4.5 可观测性埋点在最小实现阶段不需要一上来就接完整的分布式链路系统但至少要埋好点。我在循环的每个关键节点都打一条结构化日志包含 run_id、步骤号、事件类型、耗时。这已经能满足 90% 的排查需要。def log_step(self, state, event, detail): print(json.dumps({ run_id: state.run_id, step: state.step_index, event: event, detail: detail, ts: time.time() }))等业务规模大了再把这个函数替换成真正的日志上报和链路追踪 SDK。换的时候只改一个函数其他逻辑都不受影响。5. 常见故障与排查技巧实录5.1 死循环与 Token 开销失控现象Agent 半天不结束费用飙升日志显示反复输出同样的内容或者不断调用同一个工具。排查思路先看是否设置了最大步数保护没有就立刻补上。再看连续几轮的输出如果 tool_call 结果和上一轮重复说明 Agent 陷入某种“原地打转”。我在 Runtime 里加了一个重复检测机制如果连续三轮输出相同就强制终止当前循环并通过上下文提示模型换一个策略。还有一个高频原因工具返回的错误信息太简单模型看不懂只能反复尝试同一种方法。解决方案是让工具错误信息更明确比如“订单号不存在请检查订单号长度是否为 12 位”这样模型才知道怎么修正。5.2 工具调用参数格式翻车现象模型生成了一段文本里面包含工具调用但格式不对可能带 Markdown 代码块也可能是 JSON 里多了一个逗号。我的处理顺序是先清洗把代码块标记剥掉提取 JSON 片段再解析如果失败就把原始输出返回给模型并附带一条提示“你上次输出的不是合法 JSON请只输出 JSON”。修两三次之后基本都能恢复正常。更推荐的做法是在系统提示里写清楚工具调用格式并给出一个正例和一个反例。模型对“必须输出 JSON”的遵循度远高于“尽量用 JSON”。5.3 多轮会话中的状态错乱现象用户在对话里说“按我刚才的意思办”Agent 完全不知道刚才发生了什么或者更糟被另一个会话的上下文污染。原因通常是会话 ID 没有贯穿整个链路。HTTP 接口接收了用户请求带着用户 ID但 Agent 内部没有把用户 ID 和 run_id 绑定到状态存储。我要求所有接口入参都显式传递session_id并在加载长期记忆和恢复工作状态时都以它为 key。客户端请求里没有 session_id 的直接拒绝或者新开会话不能自动默认使用全局上下文。5.4 性能瓶颈慢不一定是模型慢现象单次工具调用模型只需要一两秒但整个 Agent 任务跑了半分钟。排查方式是把每个 step 的耗时打点通过看板对比。模型调用有时确实慢但更多时候瓶颈在工具调用之间是串行的。比如 Agent 要查三个订单如果工具函数本身支持批量就应该给模型提供一个query_orders而不是query_order这样能省掉两次循环。另一个常见瓶颈是每次工具调用后都要等待工具结果返回如果工具是同步函数会阻塞事件循环必须改成异步版本。我之前遇到过一个案例Agent 卡在自动重试里每次超时 30 秒、重试三次总耗时 90 秒。问题根源是下单接口不稳定应该改为失败后进入人工队列而不是无限重试。后来把超时缩短到 10 秒重试降到一次再配合熔断逻辑整个流程快了不止一倍。最后再分享一点个人体会。做 Agent Runtime 最忌讳的是一开始就追求花哨功能比如复杂的规划器、自适应的 Prompt 工程、花里胡哨的 UI。我踩过最大的坑就是先加了太多抽象层导致排障时连“这一个工具到底有没有被调用”都要翻三张表。先用最小骨架跑通真实业务把观测、状态恢复、参数校验、失败重试这些基本功做扎实后面再逐步加智能化功能系统才会越走越稳。这个内容后续还可以扩展的方向很多动态工具发现、多 Agent 通信协议、基于历史反馈的自动 Prompt 优化、更细粒度的成本配额控制。但无论扩展到哪里底层那套循环加状态加工具加边界的基础模型都不会变。把基础打好后面加什么都顺。