观测与治理
只要是 Agent 干的，就有案可查。
AgentGuide 站在每一次模型调用、工具执行与 agent 轮次的必经之路上， 所以可观测性不是一个指望每个团队都接入的 SDK，而是流量本身的属性。 同样的位置也让治理成为强制执行，而不是善意建议。
用量事件
四类事件，一套归因模型。
LLM、MCP、ACP 与 builtin 流量各自产生持久化的类型化用量事件。 每条事件都携带引发它的 agent —— 成本、时延与错误按 agent 汇总， 而不只是按端点。
| 时间 | 类型 | agent | 目标 | tokens 入 / 出 | 时延 |
|---|---|---|---|---|---|
| 14:02:11 | llm | support-triage | anthropic · claude-sonnet-5 | 8,412 / 1,203 | 2.1s |
| 14:02:13 | mcp | support-triage | crm-tools · lookup_account | — | 340ms |
| 14:02:19 | builtin | report-writer | turn · plan-execute | 31,908 / 4,551 | 18.7s |
| 14:02:24 | acp | codex-dev | turn · session 7f3a | 12,050 / 2,340 | timeout |
对账级的 token 明细
prompt、completion、缓存与推理 token 分别记录 —— 这才是解释账单、调优缓存真正需要的数字。
span，而不只是计数器
agent 轮次打开交互 span；内部的模型调用与工具执行嵌套其下。 你看到的是因果链条，而不是四份互不相干的日志。
故障分门别类
客户端错误、上游故障与内部异常在每条事件上区分开 —— agent 的失误与提供商的宕机永远不会混为一谈。
分析与集成
就地查询，随处聚合。
指标 Admin API
带管道健康计数的汇总、按协议的时间序列与维度分解、近期交互事件， 以及按 agent 的用量与活动视图 —— 网关一启动即可查询。
- 按 agent 汇总 每个注册 agent 的用量、活动、交互与健康。
- Prometheus 暴露 直接抓取网关；趋势与告警交给 Grafana。
- OpenTelemetry 接缝 为对接你的追踪体系而设计的 sink 适配器。
- 保留期控制 可配置的数据保留与自动清理 —— 不吃垮你存储的可观测性。
治理
在唯一绕不过去的位置执行策略。
Wiki 里的规范拦不住凌晨三点的 agent，网关上的控制可以。 AgentGuide 的治理是结构性的：流量不满足策略，就到不了模型、工具或 agent。
身份与密钥
- 按应用、团队或 agent 发放虚拟密钥 —— 集中签发、轮换、吊销
- 上游密钥永远不出网关
- 路由级鉴权要求，fail-closed
审批门禁
- 默认拒绝；安全处自动批准；关键处交互式人工审批
- 未回应的请求超时即拒绝
- 每个决定可归因、有记录
失控防护
- agent 递归深度限制，在网关处掐断 agent 套 agent 的循环
- 按 agent 的并发上限与轮次超时，拒绝而非排队
- panic 隔离：一个坏轮次永远拖不垮网关
能力有边界
- agent 只能触达绑定给它的模型路由与 MCP 工具
- 托管编码 agent 运行在池化的隔离进程中，限定在许可的文件系统根内
- 缺失的工具大声报错 —— 没有静默降级
- 一条路由只属于一个 agent：归因始终无歧义
把你的 Agent 放上雷达
在扩编队伍之前，先学会观测。
能把多 agent 系统做成的团队，都是先看清了单个 agent 的团队。 部署网关，把一个 agent 的流量接进来，画面自然会浮现。