从Pi Agent到AIRUN：企业级Agent运行时的架构重构

1. 从能跑到能扛Pi Agent 给我的三记重拳1.1 第一记重拳Demo 级别的引擎进了生产就失灵Pi Agent 跑通第一个真实业务的时候我第一反应不是高兴而是慌。那个在本地能完美回答问题的 Agent一到生产环境就变成了定时炸弹任务不结束、日志爆炸、稍一并发就 OOM。AIRUN 这个项目就是被那几次事故逼出来的。如果你也在做 Agent 开发或者正打算把一个 Agent 引擎推向企业级运行时这篇文章建议看完再动手。先说清楚我为什么选中 Pi Agent。当时团队要做一个内部知识问答和工单自动处理的 Agent市面上框架一大堆但我只想找一个足够轻、没有过度封装的开源引擎做底座。Pi Agent 恰好满足模型无关、工具注册简单、核心循环一眼能看完。它更像一个Agent 执行内核不像 LangGraph 那样连编排都替你决定了。对一个想亲手掌控每一层行为的团队来说这是很好的起点。但坏也就坏在这个轻上。我拿它接了一个内部工单系统让 Agent 根据用户描述查知识库、调工单 API、生成处理建议。本地联调十分钟出结果日志干净。上线灰度第一天就露馅同一时间进来 20 个工单前几个还能出结果第五个开始整体卡住第九个直接超时最后进程被 OOM Killer 带走。那一刻我意识到Pi Agent 是一台能点火的发动机但 AIRUN 需要的是一台有刹车、有仪表盘、有安全气囊的整车。1.2 第二记重拳你以为的并发其实是串行第一次事故的根因说出来有点丢人Pi Agent 的执行循环里所有状态都挂在一个全局的 session dict 上。单用户跑没问题多用户同时进来大家的 messages 队列互相覆盖工具调用结果串到了别人的会话里。我在日志里看到 A 用户的查询被 B 用户的知识库结果污染整个人是懵的。这反映出一个很根本的问题引擎当初是按一个进程里跑一个 Agent设计的根本没想过一个进程里跑一万个会话这件事。企业级运行时和 Demo 引擎的第一个分水岭就在这里你要不要为每个会话做隔离要不要为每次并发做资源限制要不要为每个用户的上下文做独立存储我当时用最简单的方式验证了一把把会话粒度从进程级改成对象级用 Redis 做会话状态持久化每个 Agent 实例绑定一个 session_id。改造后并发不再互相污染但新的问题又来了Pi Agent 的执行模型是同步的一个 Agent 在等工具返回时整个进程都在等。用户感受到的并发其实只是排队根本不是并行处理。这逼着我去思考运行时必须自己有一套调度器而不是依赖引擎的天然行为。1.3 第三记重拳Agent 失控时谁都叫不停它最让我脊背发凉的事故发生在一次演示上。现场让 Agent 做一份数据分析它的工具调用链突然陷入循环反复读同一份文件、反复调用同一个统计函数每次都把同样的结果写进上下文然后继续调用。Pi Agent 原生的 max_steps 参数设的是 10按理说 10 轮就该停了但它在第 8 轮调了一个写文件的工具工具返回值把上下文撑大随后每轮都在膨胀最后请求超时连带拖垮了同一进程里的其他任务。这次事故教会我一件事循环上限不是保险丝是最后一道没有意义的闸门。Agent 可以在上限之内反复做无效调用也可以在上限之外因为工具副作用而让系统内存爆炸。叫停必须是运行时的基本能力不能靠引擎里的一个数字。你得能随时查看每个会话在干什么能强行终止一个任务能从外部改变它的下一步行为。这些能力 Pi Agent 一概没有。这三记重拳打完之后我做了个决定不修修补补直接基于 Pi Agent 的执行思想重写一个企业级运行时代号 AIRUN。2. 引擎、框架、运行时先把边界划清楚再造轮子2.1 为什么 AIRUN 不叫框架而叫运行时很多做 Agent 的朋友喜欢把框架和运行时混着用结果讨论了半天发现说的不是一回事。我自己的划分很简单框架解决代码怎么写。它给你一套脚手架、抽象类、工具函数帮你组织 Agent 的逻辑。比如你定义几个 Tool、写一个 Prompt Template、挂一个 Memory 对象这是框架的活。引擎解决执行怎么跑。它负责把模型调用、工具调用、上下文拼装、多步推理这些核心动作真正执行起来。Pi Agent 的价值在这层。运行时解决系统怎么扛。它在引擎之外负责进程生命周期、并发调度、超时熔断、资源隔离、可观测性、异常恢复、热更新、安全审计。引擎决定一个 Agent 能不能跑运行时决定一万个 Agent 能不能稳定跑。打个比方框架是汽车的维修手册引擎是发动机运行时是整车。你可以有好发动机但没有刹车、没有仪表盘、没有安全气囊这车上不了路。AIRUN 这个名字就是 AI Runtime 的缩写团队内部叫它爱 run说得很直白我们不做框架不写业务编排就专门解决把 Agent 执行放进企业系统里还能正常运转这件事。2.2 Pi Agent 的引擎部分哪些留着、哪些必须拆重写不是推翻重来。我梳理了 Pi Agent 的执行核心把有价值的部分保留下来把有问题的部分彻底拆掉。保留的模型无关的 Model Adapter。Pi Agent 对模型接口的抽象写得不错底层是 OpenAI 还是本地模型对上层是透明的。这个设计直接继承到 AIRUN。工具注册表。它的工具注册方式很干净函数 schema不需要额外定义复杂的 protocol。这个也留着。多步推理的消息循环。系统提示词、用户消息、工具返回、中间推理结果按顺序拼装这个循环本身没有大问题问题在循环外面的控制。必须拆的全局 session 状态。Pi Agent 把会话上下文存在模块级 dict 里这就是并发污染的根源。AIRUN 改成每个会话一个独立的状态存储序列化之后进 Redis。同步执行链。原引擎的所有步骤在同一个 async 函数里串行跑一个工具卡住全链路卡住。AIRUN 把每一步抽象成可调度的工作单元交给任务队列去跑。无观测的日志。原引擎只有 print出事之后只能靠猜。AIRUN 从第一步就开始打结构化日志每次模型调用、工具调用都有 trace_id 贯穿。固定循环上限。替换成了步骤预算 token 预算 墙钟时间三重限制。改造后的执行核心大概是这个样子# AIRUN 里一个会话的一次执行迭代简化版 async def execute_step(session): budget session.budget if budget.remaining_steps() 0: return session.terminate(reasonstep_budget_exceeded) if budget.remaining_tokens() 0: return session.terminate(reasontoken_budget_exceeded) if session.deadline.exceeded(): return session.terminate(reasonsession_timeout) # 记录 trace方便事后回放 with tracer.start_span(fexecution_step-{session.step_id}) as span: response await session.model_adapter.chat(session.messages) tool_calls parse_tool_calls(response) if not tool_calls: return session.finish(response.content) for call in tool_calls: # 工具调用单独走超时和熔断不再和模型调用混在一起 result await dispatch_tool_call(session, call) session.messages.append(tool_result_message(call, result))2.3 一条界线引擎负责跑得动运行时负责停得下我后来给自己总结了一条判断标准一个组件该放引擎还是放运行时就看它是在帮助 Agent 跑得更聪明还是在防止 Agent 跑得更危险。模型调用、工具解析、上下文拼装这些是让 Agent跑得动的能力留在引擎层。超时、熔断、降级、资源控制、权限校验、审计日志这些是让系统停得下的机制全部提到运行时层。这个界线一划清楚很多争论就不存在了。比如给 Agent 加一个循环上限这种需求如果你在引擎层写一个参数那只是多了个开关但如果你在运行时层做一个 step budget 的强制校验它就成了所有会话的统一约束任何 Agent 都没法绕过去。AIRUN 里我采用了后者每个会话在创建时就绑定一个 budget 对象执行迭代的第一步就是检查预算而不是等引擎自己想起来要停。3. AIRUN 核心设计用状态机管住每一个会话3.1 会话状态机把 Agent 的一次执行拆成 9 个状态没有状态机的 Agent 运行时本质上就是在裸奔。Pi Agent 时代我根本不知道一个任务执行到哪一步了出了错也没法恢复。AIRUN 里我给每个会话定义了一套显式状态机所有状态转换都经过运行时统一管理。状态含义可进入的来源CREATED会话已创建等待调度-QUEUED已进入任务队列等待执行CREATEDRUNNING正在执行 LLM 调用或推理QUEUED, PAUSEDWAITING_TOOL正在等待某个工具调用返回RUNNINGWAITING_HUMAN需要人工介入才能继续RUNNING, TOOL_ERRORRECOVERING发生可重试错误正在恢复TOOL_ERROR, API_ERRORSUCCEEDED正常完成RUNNINGFAILED不可恢复的错误RUNNING, RECOVERINGTERMINATED被外部强制终止任意运行时状态这里有个细节值得说道WAITING_HUMAN 状态是我后来加的。早期测试里 Agent 遇到权限不足的工具会反复尝试浪费预算。后来在设计上规定Agent 遇到人类才能决策的情况必须把会话挂起推到人工审批队列而不是自己瞎猜。这个设计让运行时天然拥有了人机协作的能力也让权限边界从技术上变得可执行。状态不是图个好看它必须落到存储里。AIRUN 的做法是每次状态迁移都写成一条 event 记录写进 PostgreSQL。任何时刻你问某个会话现在在干什么都能从事件表里还原出来。这也为断点恢复提供了基础进程重启后把 RUNNING 状态的会话捞出来根据 events 重建上下文重新入队继续跑。3.2 三道保险超时、熔断、降级状态机解决了看得见的问题但真正要命的是停不下来。我给 AIRUN 上了三道保险对应三个不同层面的失控风险。第一道是三级超时。单次 LLM 调用 30 秒必须返回单次工具调用 60 秒必须返回整个会话最长 15 分钟。任何一个超时都会触发相应处理而不是无声无息地卡住。比如工具调用超时先记录一次 timeout 事件然后根据策略决定是重试一次还是直接把会话切到 FAILED再或者联系人工处理。第二道是熔断。熔断用于保护下游系统不被 Agent 的疯狂调用打垮。AIRUN 里每个外部依赖都有一个独立的断路器以 60 秒为窗口统计调用失败率超过 50% 就打开断路器接下来 30 秒内所有发往该依赖的请求直接快速失败不再真正发起调用。这个机制在「外部 API 抖动」的场景里救了我很多次后面我会具体讲。第三道是降级。降级的核心思想是Agent 不是所有任务的最优解。有一些简单重复的动作直接用规则引擎处理比走大模型更快更稳。AIRUN 允许在任务进队列之前先过一个规则匹配器命中规则的任务根本不进 Agent 引擎。比如工单分类这种活正则表达式就能搞定 80%没必要让 Agent 跑一遍。配置大概是这样的runtime: timeouts: llm_call: 30s tool_call: 60s session: 15m human_wait: 24h circuit_breaker: window: 60s failure_rate: 0.5 cooldown: 30s fallback_rules: enabled: true prefilter: true3.3 记忆工程化短期、中期、长期记忆各归其位Agent 的记忆是热搜词里被问烂的问题也是实际做起来最容易踩坑的地方。很多团队把记忆理解为把历史消息全部拼进 prompt结果上下文越滚越长钱越花越多效果还越来越差。AIRUN 里我把记忆分成三级每一级有明确的存储介质和生命周期。记忆类型存储位置生命周期典型用途短期记忆当前会话上下文字段会话结束即销毁多轮对话中的用户意图、临时变量中期记忆PostgreSQL pgvector按项目/任务维度保留该业务领域的历史决策、常用工具选择长期记忆数据仓库 向量化归档按组织策略保留用户偏好、组织知识沉淀、策略模板实践中我发现一个原则不要把检索出来的所有记忆都塞给模型每个层级只取 Top-K而且要带时间衰减。比如中期记忆按相关度排序后取前 5 条每条附上这是三个月前的一次类似工单的处理方式。模型有这些锚点就足够做出稳定决策不需要把历史全部灌进去。记忆工程还有一个容易忽略的点写记忆比读记忆更难。Agent 不能自己决定这个信息很重要我要记住那会导致记忆库被垃圾塞满。AIRUN 的做法是Agent 产生的所有信息先进临时缓冲区由运行时的一个记忆过滤器决定哪些值得沉淀到中期库哪些值得进长期库。过滤器目前是一套规则 关键字段提取后续可以升级成一个小模型判断但核心原则不变记忆的写入权在运行时不在 Agent。4. 从单 Agent 到多 Agent编排层、Skill 和权限边界4.1 Harness 与 Agent 的区别谁是大脑谁是项目经理做 Agent 平台化的过程中很多同事会问既然每个 Agent 都能自主决策那还要编排层干嘛我通常这么解释Agent 是那个干活的大脑Harness编排器是那个盯着截止日期、分配任务、处理突发状况的项目经理。单 Agent 场景下你不太容易感觉到 Harness 的必要性因为所有决策都发生在 Agent 内部。但一旦上了多 Agent 协作问题立刻复杂多个 Agent 之间是串行还是并行某个 Agent 失败后是重跑还是换一个任务之间的数据依赖怎么传递谁来决定整个工作流已完成AIRUN 的编排层是一个独立于 Agent 引擎的组件。它定义任务 DAG、执行优先级、重试策略和条件分支。Agent 只负责当前这一步怎么做Harness 负责整个流程怎么走。这个分工带来一个明显的好处你可以单独升级某个 Agent 的能力而完全不用改动编排流程反过来你也可以调整编排顺序而不用动 Agent 的内部逻辑。一个容易犯的错误是把编排逻辑写死在 Agent 的 prompt 里。比如让 Agent 先查库存再下单如果失败就换供应商这串逻辑看起来没问题但一旦角色复杂化prompt 会膨胀到失控而且无法做精细的重试和审计。AIRUN 里这些全都提到 Harness 层用代码表达Agent 只负责执行单个已经定义好的动作。4.2 Skill 不是 Agent能力复用与控制权分离另一个高频问题是 Skill 和 Agent 的区别。我自己踩过的弯路是把 Skill 当成微缩版 Agent给每个 Skill 都配了一套 prompt 和决策逻辑结果就是一个 Skill 里又藏了一个小 Agent系统复杂度直接爆炸。后来我定了规矩Skill 是能力包不是决策主体。一个 Skill 可以是一个 Python 函数、一个 API 封装、一套知识库检索逻辑。它只负责把一件事做对不负责决定要不要做这件事。决策权永远在 Agent 手里Agent 根据任务目标选择合适的 Skill调用之后把结果拿回来自己判断下一步。AIRUN 里 Agent 与 Skill 的关系是显式注册的。Agent 创建时声明自己能调哪些 SkillSkill 不能反过来决定流程。这种单向依赖让权限控制变得非常简单一个 Skill 能被哪些 Agent 调用在白名单里写清楚运行时强制校验。如果是双向依赖权限就会变成一团乱麻。4.3 工具权限与审计Agent 能调什么必须谁说了算企业里做 Agent最敏感的就是工具权限。一个能自主执行工单操作的 Agent如果权限设计不当可能做出不可逆的操作。AIRUN 里我把工具分成三类只读类查询知识库、读取业务数据、搜索日志。这类工具 Agent 可以任意调用。写入类创建工单、修改配置、发送消息。这类工具要求 Agent 携带明确的操作意图并且每条记录都写审计日志。高危类删除数据、批量操作、资金相关操作。这类工具默认禁止 Agent 直接调用必须转人工审批也就是前面说的 WAITING_HUMAN 状态。权限模型的落地不只是在代码里加 if 判断。我的经验是把权限校验放到运行时的一个独立中间件里而不是让 Agent 引擎自己去判断。这样任何 Agent、任何 Skill 都没法绕开权限机制因为运行时根本不把高危工具暴露给引擎层调用链。审计这一块同样不能省。每次工具调用都要记录谁哪个 Agent、在哪个会话、为了什么任务、调了哪个工具、传入什么参数、返回什么结果、耗时多少、成功还是失败。这些日志统一存到单独的审计存储和应用日志物理隔离。等真的出问题时这套审计链能让你回溯到每一个决策点。5. 生产环境迁移实录三道坎以及完整的排查链路5.1 坎一写个二叉树程序Agent 却卡死了 47 分钟上线后遇到的第一个大 Bug是我印象最深刻的运行时错误。业务方让 Agent 写一段二叉树的层序遍历代码并在沙箱里执行验证Agent 很快给出了代码然后卡在验证环节。AIRUN 控制台显示会话停留在 WAITING_TOOL 状态从开始到被发现整整 47 分钟。我当时的排查链路是这样的先看会话事件表确认停在哪个工具上——一个叫run_sandbox_code的执行工具。看工具的超时配置发现这轮部署时我改过配置但新配置没有生效旧配置里 tool_call 超时是默认值而这个默认值依赖引擎的 max_steps恰好没有对这个工具做单独限制。手动复现把 Agent 生成的那段二叉树代码拿到沙箱里跑发现while root or stack:这个循环条件写错了root永远不为空死循环。确认根因后修了两个层面沙箱执行必须带 CPU 指令数限制工具层加独立的强制超时不再依赖引擎默认参数。补了一条测试用例所有沙箱执行类工具运行前必须做静态循环检测运行中必须有指令数上限。这个坑的本质是Agent 写出来的代码可能死循环而你的运行时没防住这一层。很多人防了模型不返回结果却没防工具返回结果但工具本身在死循环。AIRUN 后来给所有执行类工具加了一层 wrapper传入的代码执行脚本统一带上ulimit -t 5之类的限制从根本上杜绝无限循环。5.2 坎二外部 API 一抖动全线 Agent 跟着殉葬有一次外部 CRM 系统做版本升级API 响应变得极慢。我们的 Agent 调度了大量查客户资料的任务结果所有任务都卡在同一类查询上。更糟糕的是Agent 的默认行为是没拿到数据就重试于是每个会话都在无限重试把 CRM API 打得雪上加霜形成雪崩。这个问题靠三层解决。第一层是每个外部 API 都进熔断器这是 AIRUN 自带的能力但早期为了快速上线我跳过了熔断配置这是教训。第二层是重试要带指数退避和抖动不能用固定间隔。第三层是Agent 的 prompt 里约定工具调用失败超过一次就放弃该路径转而向用户报告暂时不可用而不是无限重试。这轮的修复代码后来被抽成了公共组件async def call_with_resilience(session, func, *, max_retries2, breakerNone): for attempt in range(max_retries 1): if breaker and not breaker.allow_request(): raise CircuitOpenError(下游服务熔断中快速失败) try: result await func() if breaker: breaker.record_success() return result except (RemoteTimeout, RemoteUnavailable) as e: if attempt max_retries: # 不再重试把控制权交回 Agent 决策层 return ToolUnavailable(reasonstr(e)) if breaker: breaker.record_failure() backoff (2 ** attempt) * 0.5 # 指数退避 await asyncio.sleep(backoff random.uniform(0, 0.1)) # 加抖动经历过这次之后我把外部 API 依赖策略写进了 AIRUN 的部署检查项凡是接入的新工具必须明确声明重试次数、超时时间和是否允许降级。不允许工具默默重试。5.3 坎三热更新把新技能推给了一半旧会话上线运行稳定后我开始给 Agent 更新技能包。第一次热更新后观察到一个诡异现象测试环境完全正常生产环境却出现同一类任务结果忽好忽坏看日志发现有一部分会话加载的是新技能代码另一部分还在跑旧技能代码而这两类会话混在同一个队列里。根因是AIRUN 直接改动了技能模块的函数引用已经运行中的会话在下一次工具调用时拿到的可能是新代码。对于有状态的长会话来说这会造成不可预期的行为一个会话前一半跑在旧版本上后一半跑在新版本上中间的逻辑就可能对不上。修复方案是版本快照 会话粘滞。每个会话在创建时记录一个技能包版本号和代码快照指针执行过程中始终加载这个快照对应的代码。更新技能包时新会话用新版本旧会话继续用旧版本直到结束。只有重启整个运行时时才允许所有会话强制迁移到新版本。这有点类似 K8s 滚动更新的思路但粒度从 Pod 细化到了会话。这个设计带来的副作用是存储占用变大了因为要保留多个版本的技能包。但这是值得的一致性比省存储重要得多。一个诡异的线上问题排查成本够你买十倍的存储。6. 留给后来者的验收清单和经验6.1 一份可以复用的企业级 Agent 运行时验收清单如果你也在做 Agent 运行时或者正打算把某个开源引擎推上生产我建议你拿这份清单自查一遍检查项标准常见失败表现会话隔离不同会话的状态存储物理隔离并发后上下文互相污染强制超时模型调用/工具调用/整会话都有独立超时一个卡住的工具拖死全链路熔断保护下游依赖故障时快速失败依赖抖动导致全线雪崩状态可观测每个会话当前状态可查、历史可回放出问题只能靠猜日志资源限制步骤数、token 数、内存都有上限单个 Agent 打爆整个进程权限边界高危工具必须有独立审批链路Agent 私自执行不可逆操作审计完整性每次模型调用和工具调用都留痕无法回溯错误决策源头热更新一致性运行中会话绑定旧版本快照新旧代码混跑产生诡异结果逃生通道任何会话都可被外部强制终止失控任务无法停止这张表不是设计文档里写写就完的每一条都应该有对应的自动化检查。比如会话隔离这一项AIRUN 里我写了一个压力测试用例同时开 100 个会话每个会话发不同的任务最后校验每个会话拿到的结果是否等于它自己任务对应的答案。这个用例在每次 CI 里都会跑。6.2 最后一句实话先解决失控再追求智能做完了从 Pi Agent 到 AIRUN 的迁移我最大的体会是Agent 的智能是锦上添花可控才是雪中送炭。一个偶尔答偏但永远 3 秒内返回、状态清晰、能随时终止的 Agent比一个聪明但偶尔失控的 Agent 有价值得多。企业系统里正确地失败比华丽地成功更重要。如果让我重新来一遍我会从画状态机开始而不是从调 prompt 开始。跑通 Pi Agent 只是拿到了发动机AIRUN 让它成为一台能上路、能刹车、能被安全拦下来的车。这份迁移记录如果能帮你少踩一个坑那就值了。