智能体「没报错却少了工具」：怎样接非致命降级通道？

现有软件接入智能体 SDK 后，最容易被忽略的一类事故不是 401、429 或余额不足，而是：会话创建成功了」，界面也没弹红字，但工具突然变少、裁决人悄悄缺席、能力位解析失败却回落到「零能力档」——用户和值班同学都以为「还能聊」。 若宿主只接硬失败、不接非致命通报，运维会把「静默降级」当成正常成功。

2025 年末到 2026 年，智能体安全与可观测材料把「看不见的降级」推到开发者面前。OWASP Gen AI《OWASP Top 10 for Agentic Applications》发布说明（页面现行，本机 2026-11-09 再核 HTTP 200；配套 Version 2026 PDF 同站可下载）强调：缺少对智能体在做什么、为何做、调用了哪些工具的清晰可见性时，过度自治会悄悄扩大攻击面，并把小问题放大成系统级故障——强可观测性成为不可妥协项。OWASP Agent Observability Standard 提案 #73（HTTP 200）进一步指出：仅靠单次追踪无法发现随时间发生的静默劣化；点检通过不代表行为轨迹稳定。AWS Well-Architected Agentic AI Lens · AGENTOPS05-BP02（HTTP 200）要求为智能体建立行为基线，监测工具选择漂移、完成率与异常模式，避免只靠静态阈值漏掉「慢慢变差」。同一时期，诊断面也在补齐：Hermes Agent PR #89217（HTTP 200）为 hermes doctor 增加只读的配置组合诊断与稳定 JSON；deepagents dcode doctor（HTTP 200）把安装健康、SDK／平台版本与配置路径打成可粘贴报告；agentdx（HTTP 200）把 Silent Degradation 列为可检测的运维病理之一。上述材料共同回答的行业问题是：硬错误通道不够；装配期／运行期的非致命降级必须有结构化出口，并进入界面与值班链路。

对接入 SDK／会话宿主的开发者，完整行业答案可以收成六句话：

1. 「请求成功」≠「能力完整」：会话能聊、轮次结束，仍可能发生工具裁剪、裁决人降级或装配告警。
2. 静默降级是一等运维对象：行业安全／可观测材料已要求看见工具调用与行为漂移，而不是只盯 HTTP／异常栈。
3. 非致命通报不要丢进 console：应进入宿主回调或会话事件流，再投影到 UI／日志／告警；缺席回调不等于「没事」。
4. 回落策略必须可解释：例如能力段解析失败时回落「零能力」而不是「缺省放开」，这是安全取向，但必须让人知道发生了回落。
5. 硬失败与 notice 分通道处理：401／429／capability_disabled 走错误排障；sdk.notice／warning 走降级可见性，不要混成同一种「失败 toast」。
6. 装配前预检与运行期通报互补：CI／本地 doctor 类命令抓阻断配置；运行期 warning 抓会话装配中的非致命事实。

本文把上述行业问题映射到已核实的 Tansr 机制：createSession({ onPlatformWarning })／onWarning 接收 bundle 解析与装配期的非致命事实；缺席时回落会话事件流 turn.error { scope: 'sdk.notice', recoverable: true }——文档原文写明恒不写入 console、恒不改装配结果；常见码含 app_platform_mismatch、tools_platform_deprecated、capabilities_unparsed（SDK 0.13.0 起回落零能力档 tools 全 false，不再回落缺省档）以及多项 adjudicator_*。依据见 平台装配与 bundle、PlatformWarning、会话与事件流（本机 2026-11-09 再核均为 HTTP 200）。命令行侧可用 设置与 doctor 的 tansr doctor／--json 做零网络装配预检（退出码只看 problems 四类阻断码）。它不是 S06 的 401／429／余额／能力关闭硬失败分码排障全文，也不是 S07 能力位治理决策稿、P01 权限审计链、S10 统一面完成判定，或 S08／S09／S01／R01；这里只回答：宿主怎样把「没报错的降级」接出来，并与硬失败分流。

直接答案

1. 接 onPlatformWarning（或全量 onWarning）：在 createSession 时传入；把 code／message（及全量通道的 detail）写入应用日志与可选 UI 条，不要只 console.warn 后丢掉。
2. 同时监听 turn.error 且识别 scope: 'sdk.notice'、recoverable: true：这是回调缺席时的回落通道；不要把它当成与硬失败同一套「重试／中断」策略。
3. 按码分流用户可见性：capabilities_unparsed → 明确提示「能力配置解析失败，已按零能力装配」并引导修 bundle／控制台；adjudicator_* → 提示裁决降级／熔断，权限体验可能变严；app_platform_mismatch → 核对应用类型与接入形态；tools_platform_deprecated → 安排去掉旧别名。
4. 记住 0.13.0 回落语义：capabilities_unparsed 回落零能力档，不再回落缺省档；界面若仍显示「全部工具可用」就是宿主撒谎。
5. 硬失败仍走错误面：capability_disabled／401／429／余额等按错误信封与排障稿处理；本文不替代那条链路。
6. 本地／CI 用 tansr doctor 抓阻断：退出码 0／1；--json 的 problems 仅四码（no_provider／unresolved_model／missing_credential／session_store_unwritable）；大量呈现项不改退出码——不要把「报告里有黄字」当成 CI 红灯，也不要把「退出 0」当成运行期不会出现 warning。
7. 本批未做线上基线与联调实测：标题收窄为机制与宿主接线说明，不承诺「接上回调即消灭静默事故」。

行业问题：为什么「没红字」不够

OWASP 对可观测性的强调、AOS 对静默劣化的警告、AWS 对行为基线的要求，以及各家 doctor／病理检测项目，共同指向同一产品缺口：嵌入现有软件的智能体宿主，必须把非致命装配／运行通报做成一等公民。

你原来要自己做的事 → Tansr 接手什么 → 应用仍要负责什么

原来常要自行完成的：

• 猜测「工具变少」是模型问题、网络问题还是配置问题。
• 把所有异常塞进同一 toast，或全部忽略非 4xx／5xx。
• 在 CI 里用人工 checklist 核对 provider／凭据／会话存储可写性。
• 无法区分「能力位被管理员关闭」（硬拒绝）与「能力段解析失败回落零能力」（非致命但后果更隐蔽）。

Tansr 公开机制可接手的部分（以 2026-11-09 抓取的 docs.tansr.com 为准；0.20.0 候发内容不得写成已上线）：

• Bundle 装配期非致命事实 → onPlatformWarning／onWarning；缺席 → turn.error sdk.notice。
• 常见 warning 码与 0.13.0 起 capabilities_unparsed → 零能力档的安全回落。
• 裁决人相关 adjudicator_* 与显式 permission.mode 触发的 adjudicator_skipped_by_mode。
• tansr doctor／--json：零模型、零网络、零子进程的装配预检；CI 以退出码／problems 为准。
• 版本核对基线：资料站平台装配页写明 @tansr/sdk 0.19.0／@tansr/serve 0.15.1（均 2026-10-10 发布）；CLI doctor 页按命令行 0.10.3（2026-10-10）核对。

应用仍要负责：

• 实现回调并把码映射到文案／告警级别；决定哪些码打断用户、哪些只记审计。
• 区分 notice 与硬错误的产品策略；勿把 recoverable notice 当成自动重试信号。
• 控制台／bundle 修复流程；解析失败时先修配置，而不是提高重试频率。
• 本批未在真实应用触发全套 warning 码留截图；不承诺「逐步复现手册」。

宿主接线要点（机制说明，非「一键完成」）

1. createSession({ onPlatformWarning(w) { /* 记 code/message；必要时 UI */ } })；需要 detail 时用文档所述全量 onWarning 通道。
2. 事件循环里：若 turn.error 且 detail.scope === 'sdk.notice'（或以文档字段为准的 notice 形），走降级提示，不走「失败重试」默认路径。
3. 对 capabilities_unparsed：展示「已按零能力装配」；排查 detail.issues（zod）；修到可解析后再开新会话／重新装配。
4. 对 adjudicator_budget_exhausted／adjudicator_breaker_tripped 等：提示人工确认可能变多；不要假装仍有裁决软化。
5. 发布流水线加 tansr doctor --json：仅当 problems 非空失败构建；报告中的呈现项另开信息级日志。
6. 与 S06 硬失败表交叉引用：同一界面可同时有「错误」与「降级」两种状态条，文案勿混用。

常见码速查（以公开页为准）

什么时候采用，什么时候不采用

值得按此推进：已在现有软件嵌入 @tansr/sdk／会话宿主；安全或 SRE 要求看见「能力变少」；曾出现「能聊但工具没了」却无日志；需要把 notice 与 401／429 分流。

先不要：把所有 turn.error 一律当失败弹窗；在未接 warning 时宣称「已消除静默降级」；把 tansr doctor 退出 0 解释成「运行期不会 warning」；或把 0.11.x 的缺省档回落行为写成现行默认。纯演示、且明确接受零可观测的原型可以另议——一旦对真实用户交付工具能力，就应按非致命通道接线。

与已有稿的差异

• 相对 S06：S06 讲 401／429／余额／capability_disabled 等硬失败分码排障；本文讲 非致命降级通道（onPlatformWarning／sdk.notice）与零能力回落可见性。
• 相对 S07：S07 讲按应用治理工具与联网能力位策略；本文讲能力／裁决在装配期出问题或降级时如何被看见。
• 相对 P01：P01 讲权限决定与业务回执审计链；本文不展开权限事件字段。
• 相对 S10：S10 讲统一调用面完成判定与 retryAction；本文不讨论 202／SSE 终态。
• 相对 doctor 专题假设：本文以运行期 warning 为主线，tansr doctor 仅作互补预检，不写成 CLI 专文。

限制（紧邻结论）

• 产品事实以 2026-11-09 抓取的 docs.tansr.com 公开页为准；未做全码触发联调实测。
• OWASP／AWS／GitHub／PyPI 材料用作行业可观测与静默降级旁证，不表示实现兼容或商业关系。
• 不写具体价格；不写「免费试用」；无 AI／身份／适用版本页脚。
• AI 效果基线本批缺测，按指导单独记录，不阻塞内容交付。
• 子代理本轮不线上发布；微信仅准备已渲染 HTML 供父代理／公众号代理交接草稿。