1. 从 Demo 到生产级智能体平台最容易被忽略的三个差距过去两年我见过太多智能体项目死在能跑和能上线之间。团队花两周写出一个能调工具、能跑任务的智能体 Demodemo 汇报时灵光乍现一到生产环境就原形毕露任务跑到一半卡死没人知道某个工具突然返回异常格式导致整条链路崩溃模型把工具 API Key 当参数传给下游引发安全事故。这些问题不是模型能力不够而是平台设计压根没往生产级靠。所谓生产级智能体平台核心不在于智能多高而在于三个能力任务编排的可靠性、工具管理的规范性、运行监控的可观测性。换句话说你不但要让智能体能做事还要让它在无人值守时不出岔子出了岔子能自动恢复或告警并且所有行为有据可查。我这次分享的是一套在企业内部从零搭建的智能体平台的设计思路和落地经验。平台定位是给业务团队提供通用任务执行能力——用大模型做规划调用内部工具和 API 完成任务。下面我会围绕任务编排、工具管理、运行监控这三个核心模块把设计取舍、踩坑过程和最终的方案讲透。如果你正准备把智能体从 Jupyter Notebook 搬到生产环境这篇应该能帮你避开不少弯路。2. 任务编排层的设计DAG 状态机、重试策略与人工审批位任务编排是智能体平台的骨架。模型生成的不只是一个回答而是一系列需要落地执行的动作序列——调用哪个工具、传什么参数、结果如何衔接下一步。生产级编排要解决的问题是动作序列如何定义、如何执行、失败后怎么办、是否需要人工介入。2.1 编排模型选型为什么最终选了 DAG 而不是纯链式早期我们试过最朴素的方式每次模型生成一条工具调用指令平台执行完把结果再喂回模型循环往复。这种对话式循环的问题很明显——一旦中间某步失败整个会话状态就乱了想回退、想跳过某个步骤都非常麻烦而且无法并发执行相互独立的子任务。后来我们改为DAG有向无环图任务模型。模型在规划阶段一次性输出完整的任务图节点代表工具调用或子任务边代表依赖关系。平台拿到图后先做拓扑排序按序执行互相没有依赖的节点可以并行跑。这是业界比较成熟的做法本质上是把让模型自由发挥变成让模型提交可执行计划。从平台角度看DAG 意味着任务状态可枚举、进度可追踪、失败可定位三个词恰好对应生产环境的硬需求。任务定义的 JSON 结构大致是这样的{ task_id: task_8f3a1c9e, dag: { nodes: [ {id: n1, type: tool_call, tool: order_query, params: {order_id: {{input.order_id}}}, retry: {max_attempts: 3, backoff: exponential}}, {id: n2, type: tool_call, tool: user_profile, params: {user_id: {{output.n1.user_id}}}, depends_on: [n1]}, {id: n3, type: condition, condition: {{output.n2.vip_level}} gold, branches: {true: [n4], false: [n5]}}, {id: n4, type: tool_call, tool: coupon_issue, params: {amount: 50}}, {id: n5, type: tool_call, tool: coupon_issue, params: {amount: 10}} ] }, timeout_seconds: 300, on_failure: abort }模板里的{{input.xxx}}和{{output.n1.xxx}}是参数引用用来把前一个节点的输出传给后一个节点。condition节点负责分支判断这是给智能体加结构约束的关键你不能让模型随心所欲地决定执行路径但可以给它一组合法路径去选择。2.2 状态机一张表管住所有任务生命周期DAG 定义好之后接下来是执行期的状态管理。我用一张表来设计任务节点的状态流转这张表也是后面监控系统设计的基础状态含义可迁移状态触发条件PENDING等待执行RUNNING, CANCELLED调度器下发 / 用户取消RUNNING执行中SUCCEEDED, FAILED, RETRYING工具返回 / 超时RETRYING等待重试RUNNING重试间隔结束SUCCEEDED成功终态工具正常返回FAILED失败终态超过最大重试次数WAITING_APPROVAL等待人工审批RUNNING, CANCELLED审批通过 / 拒绝SKIPPED跳过终态前置条件不满足CANCELLED取消终态用户取消每个节点有独立的 state整个任务有整体状态任一节点 FAILED 则任务 FAILED视on_failure策略可 abort 或 continue。状态变更必须写进事件日志每一条状态迁移都记录谁触发的、什么时间、原状态、新状态这是后期排查问题时最重要的线索。这里有一个容易忽略的坑任务图可能是模型生成的模型的输出天然具有不确定性。同一个 prompt 两次生成的 DAG 结构可能不同导致你无法统一做依赖分析。我们的做法是加一层规范器模型输出原始规划后由一个规则引擎做校验和修正——检查节点 id 是否唯一、依赖是否成环、参数类型是否匹配工具 schema。不合法就直接拒绝执行并让模型重新规划而不是带着脏数据往下跑。2.3 重试、超时与幂等生产级和玩具级的真正分水岭开发环境调工具失败了无非重新跑一遍生产环境里一次重试可能意味着重复扣费、重复发短信、重复写数据库。所以我在设计重试机制时定了三条铁律第一条必须区分可重试错误和不可重试错误。工具超时、网络抖动、限流返回 429这些是可重试的参数校验失败、权限不足 403、业务逻辑报错这些重试一万次也没用。我们在工具返回结构里强制要求每个工具声明error_type编排引擎看到transient才启动重试看到permanent直接标记节点失败。为了避免重试风暴下游宕机时所有任务同时疯狂重试所有节点的重试都带指数退避 随机抖动基础间隔 1 秒起步最多重试 3 次。第二条每个工具调用必须幂等。方法是在工具注册表里声明该工具是否支持idempotency_key。编排引擎每次发起调用时生成一个request_id作为幂等键传给工具方工具方缓存这个键和对应执行结果重复请求直接返回缓存结果。没有这一步任何自动重试都是在赌人品。第三条必须有超时熔断不能无限等下去。我在平台层给每个节点配了硬超时同时给每个工具配了并发上限和熔断阈值——某个工具连续错误超过 20 次熔断器打开后续调用不再进入该工具直接返回失败。再补一个生产环境必须考虑的特殊节点类型人工审批位。高风险的敏感动作比如给用户发大额券、删除数据、对外转账我不会让模型自动执行。DAG 支持在敏感节点前插入WAITING_APPROVAL执行到此处任务挂起通过企业微信/钉钉推送审批请求人工审批通过后任务才继续。这套机制在业务侧接受度极高也让平台敢在更多场景放权给模型。2.4 执行引擎选型自研调度器 vs 专用工作流引擎聊到这里你可能想问为什么不直接用现成的 Airflow、Temporal 这类工作流引擎我的回答是可以用但要看团队情况。Temporal 确实在状态持久化、重试、定时方面做得很成熟省掉你大量底层工作。但我们最终选择了自研轻量调度器原因有三一是项目初期任务量不大日均几千个 DAG上 Temporal 反而引入额外的运维复杂度二是我们大量任务节点是工具调用需要与平台内部的工具注册中心、鉴权模块深度交互这些逻辑放在工作流引擎外部会变得很别扭三是团队需要完全掌控执行语义尤其是模型动态生成 DAG这种工作流引擎不太擅长的场景。如果你们团队之前没有太多消息队列和分布式系统的经验我建议直接用 Temporal它把复杂的状态持久化问题都解决了你只需要关注业务定义。自研调度器还要解决任务队列、Worker 负载均衡、故障恢复、状态持久化一堆问题踩坑周期至少三个月起步。做架构决策时团队熟悉度往往比技术先进性更重要。3. 工具管理层的实现注册中心、鉴权沙箱与版本一致性智能体平台第二根支柱是工具管理。模型本身不直接接触工具平台作为手和脚去调用工具。工具一多你立刻会面临这些问题工具能力如何描述给模型工具的 API Key 放在哪里安全工具版本升级了正在执行的任务用新版本还是旧版本一个恶意 prompt 诱导模型调用高权限工具怎么办3.1 工具如何自我介绍给模型开放API规范 描述工程生产级平台里工具不是简单给模型一个函数名而是要通过结构化的方式自我描述。我用的是 OpenAPI 规范也就是曾经的 Swagger作为工具注册中心的元数据格式。每个工具在接入时需要提交name工具唯一名称下划线命名description这个工具干什么用的什么时候该用、什么时候不该用用自然语言写清楚parameters参数 JSON Schema包括类型、必填、枚举、示例returns返回结构 schemaerror_types可重试错误枚举rate_limit调用频控模型通过读取这些元数据来理解有哪些工具可用、每个工具怎么用。这一层的工作质量直接影响模型的工具调用准确率。我见过不少团队把工具描述写得特别简单比如根据用户 ID 查信息结果模型经常传错参数或者压根不知道什么时候该用这个工具。正确的做法是把描述写成使用说明而不是名词解释。比如一个订单查询工具描述可以写为当用户询问订单状态、物流信息、商家信息时使用。需要先通过 user_id 定位用户再通过 order_id 精确查询。订单 ID 通常以字母 O 开头。如果用户未提供订单 ID不要臆测可以反问用户。 这段描述包含了触发条件、参数来源、常见错误模型照着用工具选择的准确率会明显提升。3.2 版本管理为什么你的工具也要像代码一样做版本控制工具更新是生产事故的高发区。运营同事把某个工具的参数格式改了下或者新增了必填字段正在跑的任务全部 500 报错。要解决这个问题必须有工具版本管理。我们在注册中心为每个工具维护了多个版本默认情况下新任务使用latest版本但正在执行的任务在启动时就已经把工具版本钉死了。执行引擎会为任务创建一个执行上下文其中记录了每个节点实际调用的工具版本快照。这样即使工具在任务执行过程中升级了已生成的任务也不受影响只有新任务才使用新版本。这就涉及到热词里面提到的除了 SVN还有什么 Web 端的工具能查看不同版本了。工具注册中心的版本管理后台本身就需要一个能对比版本差异的界面。我们这里直接集成了开源 Git 服务Gitea想功能更重一点可以上 GitLab把每个工具的元数据和描述文件做成一个 Git 仓库每次工具更新就是一次 commitweb 端直接 diff 查看不同版本的元数据变化。相比 SVNGitea 和 GitLab 的 web 端口体验好得多天然支持分支、PR 评审权限管理也更细——这些能力对工具变更审计非常有用。平台自身的配置、Prompt 模板、规则引擎文件也全部纳入同一套 Git 管理形成一个完整的平台即代码链路。这套设计带来的好处很直接某次线上事故后想回溯当时任务用的工具是什么版本只要查任务上下文的版本快照一秒定位不用去翻 release 记录。3.3 鉴权与沙箱工具凭据不能出现在对话历史里工具调用涉及大量敏感凭据——数据库密码、短信 API Key、支付接口密钥。我们的铁律是凭据永不进入模型上下文。工具注册中心存的是凭据的引用 ID执行引擎在发起调用时通过内部服务拉取真实凭据并直接附加到 HTTP 请求上模型看不见、也调用不到真实的密钥字符串。另一道防线是工具调用沙箱化。所有工具调用在统一执行节点中完成工具返回结果会经过脱敏层过滤掉返回结果中的邮箱、手机号、身份证号等敏感信息打上掩码后再进入模型上下文。这个动作保护用户的隐私也避免大模型无意识地把敏感信息复述到其他地方。工具权限按最小授权原则设计每个工具声明自己需要的最小权限范围执行节点按工具分配短期动态密钥而不是给所有工具一把万能钥匙。动态密钥有效期十分钟超时自动失效从机制上压缩了密钥泄露的破坏时限。3.4 工具的沙箱运行与资源隔离有一部分工具不是外部 API而是平台内置的 Python 函数或脚本。这类工具的沙箱运行我们用容器隔离。每个工具调用跑在一个超时受限、内存受限、无网络权限默认的容器里只暴露必要的标准输入输出。容器镜像里提前装好依赖启动耗时控制在 200ms 内用轻量镜像预热。虽然现在大模型平台上直接写代码执行的场景很多但生产环境我的态度很明确——不能直接让模型生成的代码裸奔在工作节点上必须隔离运行否则一次提示注入攻击就能拿下整个平台。4. 运行监控的落地Prometheus 指标采集、Grafana 看板与告警闭环任务编排和工具管理解决的是能不能做运行监控解决的是做得怎么样、出问题了怎么知道。生产级平台的监控体系我分成四个层次指标监控、日志追踪、告警通知、可视化看板。这一层也是热词里提到的 Prometheus Grafana 最常见落地场景。4.1 监控哪些指标四个维度一张表先讲清楚接入 Prometheus 之前先把要观测的指标定义清楚。我们分了四个维度维度核心指标采集方式任务层任务提交总数、成功率、失败率、各状态分布、任务耗时P50/P95/P99、排队时长、重试次数分布平台侧埋点counter/histogram工具层工具调用次数、调用耗时、错误率、被熔断次数、Token 消耗量工具网关统一拦截系统层工作节点 CPU/内存/磁盘、并发数量、队列深度node_exporter模型层每次请求的输入/输出 Token 数、单次推理耗时、重试率LLM 网关侧埋点这里特别想强调任务 P95/P99 耗时。我们试过自定义业务指标task_seconds按任务类型打 label然后通过 histogram 计算分位数。实际运行中发现有一个强烈的长尾——绝大多数任务几百毫秒跑完但偶尔会有任务卡到 30 秒以上。P95 看不出问题P99 能稍微察觉真正抓到元凶是后面加了queue_wait_seconds指标发现长尾集中在调度器排队上。所以我的原则是监控要细到能拆出时间花在哪一层否则出了问题只能猜。4.2 Prometheus 指标设计避坑指南Prometheus 用下来最大的坑就是高基数列爆炸。一开始我们图方便给任务耗时指标标了task_id的 label结果任务量一大Prometheus 内存直线飙升最后不得不重构数据模型。正确的做法是给指标的 label 收窄到有限的、可枚举的维度比如task_type、tool_name、node_name、status。那些需要精确到某个任务实例的明细数据不应该进 Prometheus而应该走日志系统或专门的时序数据库如 VictoriaMetrics 或 ClickHouse。指标的保留期也不用太长明细维度保留 30 天足够聚合维度保留更久。埋点方式上我强烈建议不要在每个业务代码里手动打点。平台侧做一个统一的 SDK 或者依托中间件自动采集——如果用的是 Python/FastAPI直接用 Prometheus Client 提供的中间件挂上去内部自研逻辑则写一个MetricRecorder装饰器统一处理异常、耗时、状态码避免指标遗漏或命名不统一。Prometheus 告警规则的示例部分groups: - name: agent-platform-alerts rules: - alert: TaskFailureRateHigh expr: | sum(rate(task_completed_total{statusfailed}[10m])) / sum(rate(task_completed_total[10m])) 0.2 for: 10m labels: severity: warning annotations: summary: 任务失败率超过20% - alert: ToolErrorRateBurst expr: | sum(rate(tool_call_errors_total{tool_name~.}[5m])) / sum(rate(tool_calls_total{tool_name~.}[5m])) 0.3 for: 5m labels: severity: critical annotations: summary: 工具调用错误率超过30% - alert: QueueDepthTooHigh expr: | avg(agent_task_queue_depth) 200 for: 5m labels: severity: warning annotations: summary: 任务队列积压超过200配置里有个容易被忽略的关键动作告警表达式避免裸奔的静态阈值。任务失败率 20% 在凌晨低峰期可能只是几个任务重试导致的抖动但在高峰期就是真实故障。所以告警规则里我都加了for: 5m或for: 10m的持续时间条件并且设置了分级warning 先通知值班群critical 才打电话。这一条防止了狼来了效应不然两次误报之后真出大事大家也不看了。4.3 Grafana 看板从有图表到一看就知道哪里出了问题Grafana 负责把 Prometheus 的数据变成可读的界面。我分享三个最实用的看板设计思路。第一个是任务总览看板放一组红绿灯指标最近一小时的 QPS、成功率、P95 耗时、失败任务 Top5 的原因排行。值班同学打开这个看板5 秒内能判断平台健康状况。红灯亮起立刻进入下一个看板定位。第二个是工具调用看板按工具名展示调用量、耗时、错误率热力图。这个看板用来发现某个工具开始变慢或开始报错方便提前干预。比如我们对一个短信工具做了监控发现它的 P99 从 800ms 涨到 3 秒提前联系了供应商排查避免了一次短信发送高峰期的大面积阻塞。第三个是调度系统看板展示任务队列积压数、Worker 并发水位、节点资源利用率。任务编排系统的瓶颈往往不在单机性能而在调度策略这个看板帮我们发现了不少调度算法的问题。比如任务大量积压在队列但不触发新的 Worker 拉起就是因为 worker 管理器的扩容阈值设得太高。Grafana 的告警通知要和 Alertmanager 打通。我们配置了多级路由route: group_by: [alertname, task_type] group_wait: 30s group_interval: 5m repeat_interval: 4h routes: - match: severity: critical receiver: phone-call continue: true - match: severity: warning receiver: dingtalk-group receivers: - name: phone-call webhook_configs: - url: http://alert-bridge:8080/phone-call - name: dingtalk-group webhook_configs: - url: http://alert-bridge:8080/dingtalk这里的group_wait: 30s是为了把同一时间段的同类告警聚合成一条避免告警轰炸。repeat_interval: 4h意味着同一个告警 4 小时内不重复发送疲劳度大幅下降。我见过不少团队告警配完第一晚收到上千条消息第二天就把告警全关了——这比不配告警还糟糕。4.4 日志与链路追踪把一次任务从提交到完成整条串联起来指标能告诉你哪里出了问题日志和链路追踪才能告诉你为什么出问题。在任务编排层我们给每个任务生成了一个trace_id贯穿平台内部所有模块——调度器拉取任务、节点执行、工具调用、模型推理、人工审批——所有日志、指标、事件都打上这个 ID。查询问题时输入一个 trace_id就能拿到这条任务从提交到终态的全部时间线和日志。工具调用的请求头里也透传 trace_id下游服务如果支持也能接上。日志采用结构化格式而不是普通文本。每条日志至少包含时间戳、trace_id、task_id、node_id、事件类型、状态、耗时、关键参数摘要注意脱敏。我们统一收集到 Loki 或 ElasticsearchGrafana 里直接通过 trace_id 做日志跳转配合指标看板实现从大盘到单任务的下钻路径。这里我强烈推荐一个做法所有工具调用的请求和响应按需留痕可以开关注意隐私合规。在某次模型生成错误参数的排查中正是靠工具调用的请求留痕发现模型把quantity字段写成了负数而工具侧居然没有参数校验直接执行了。事后我们在工具网关统一加了参数合法性校验这比反复调模型 prompt 靠谱得多。5. 生产环境踩坑记录与扩展建议这五条经验是花钱买来的监控体系上线后平台还算稳定但生产环境总是会以意想不到的方式教育你。这几个坑我单独记一笔希望你不用再来一次。5.1 重试风暴 下游限流一次工具滑动雪崩复盘那次事故的起因很简单短信服务商接口不稳定报错率上升大量任务自动重试。由于我们初始重试间隔只设了 1 秒几千个任务同时重试短信接口直接被并发打挂下游限流拒绝错误率进一步升高形成恶性循环。修复方案就是在重试策略里加入指数退避 扣减式重试预算——不是说好最多重试 3 次就完事而是整个平台的全局重试预算有限超过一定总量自动暂停所有任务并告警。平台级限量是重试设计里最容易漏掉的一环。5.2 模型生成任务图时的陷阱循环依赖与幻影节点模型生成的 DAG 并不总是合法。我们遇到过模型生成一个图节点 A 依赖 B、B 依赖 C、C 又依赖 A 的循环。还遇到过节点 id 引用了一个根本不存在的节点幻影依赖。单纯靠拓扑排序在循环时直接报错定位问题只能靠报错信息去找模型重试。我们在规范器里增加了几条硬校验节点 id 存在性校验、依赖关系无环校验、所有参数引用都有前序输出可匹配校验。不合法就返回给模型一段结构化错误信息让它重新生成成功率从 70% 提到 95% 以上。这个实践比你去调模型参数划算得多。5.3 Grafana 看板性能下降指标基数失控的真实案例之前提到高基数列的问题我们踩得实实在在。某次监控面板从点击到渲染要 20 秒Prometheus 查询频繁超时排查半天发现是一个开发同学在埋点时给维度加了用户 ID 标签导致基数爆炸。解决方法是把这些高基数数据挪出 Prometheus只在关键维度保留 30 天聚合并加粗粒度。Grafana 的慢查询模板也建议设置超过多少毫秒的查询要能被发现。5.4 告警规则要定期演练不要配完就忘很多团队的告警规则配完就吃灰真正出事时没人记得规则是怎么设计的。我们的做法是每个月做一次告警演练——人为注入故障看值班团队能否在 15 分钟内定位并响应。这个演练成本不高但效果立竿见影第二次演练就发现有人把 Grafana 告警静默了整个周末因为周末不想被吵——后来我们把静默操作加了审批流只有负责人才能申请。5.5 多租户隔离与配额管理生产级还缺的最后一块拼图如果平台要给多个业务线使用多租户隔离会成为硬需求。我们的设计是每个租户有自己的命名空间任务、工具、密钥全部隔离每个租户有独立的并发配额和资源上限工具注册表按租户隔离不同租户的模型看不到对方的工具。这套机制建立在前面讲的注册中心和任务编排之上改造量不算大但却是平台从内部工具走向对外提供服务的分水岭。6. 最后聊两句扩展方向从能用到好用的下一步棋写到这平台的三个核心模块讲得差不多了最后补两个我们已经在规划的扩展方向给正在做同样事情的你一点参考。第一个是任务编排的插件化。随着业务方接入越来越多不同团队希望用不同的任务模板——有的要先查后发有的要先审后发有的要定时执行有的要事件触发。目前我们通过配置化实现了一部分但下一步想把任务模板做成可插件化的包每个包自带关联工具、槽位变量和审批策略在管理后台像装应用一样启停。这个方向走通之后业务方基本不需要开发介入就能编排自己的智能体流程。第二个是监控数据反哺编排策略。现在我们监控是被动观测下一步目标是做主动决策——根据工具错误率、模型推理耗时、任务成功率等历史指标动态调整重试策略、并发上限、甚至工具选择路由。比如某个工具当前错误率高平台自动把路由切到备用工具某个模型推理延迟高平台自动切换到一个更快但不是最强的模型。这套反馈闭环做成之后平台才真正算得上自愈型。我个人的体会是生产级智能体平台不是一个冲刺型项目而是一个日拱一卒的工程。你把任务编排的状态机设计到位、工具管理的隔离和版本控制做到位、监控告警的闭环跑通剩下的就是不断在真实流量中修修补补。每修一个坑平台就硬一分每加一个观测点你就离在出事前发现更近一步。以上这些内容希望对正在搭平台的你有用。