智能体注册表与清单运维手册¶

当一个组织里已经有多个智能体系统时，只靠一章清单已经不够了。团队还需要一套简明的运行模型：谁维护注册表，如何识别漂移，什么时候一个智能体算无人负责，已弃用条目又该如何处理。

这份手册把这套最小工作面放在一页里。

1. 哪些层应该始终存在¶

即使是规模不大的智能体计划，也最好始终保留两层：

inventory，用于记录全部类似智能体的实体；
registry，用于记录那些已经被识别、分类并允许进入生产轮廓的实体。

如果只有注册表，团队通常会低估影子智能体与本地实验。如果只有清单，没有注册表，就没人能明确说明哪些东西真正算已批准。

2. 谁应该拥有这一层¶

当负责人边界模糊时，注册表往往很快失效。

最小可用的分工通常是：

平台团队负责注册表结构与验证规则；
产品负责人负责业务目的与生命周期状态；
安全或治理负责人负责策略与审批链接；
运维负责人负责事故联系人与退役卫生。

这些角色可以由同一支团队兼任，但角色本身必须明确。

3. 一条智能体记录应该包含什么¶

最小记录最适合按一个固定模板检查：

agent_id
负责团队；
业务目的；
生命周期状态；
风险等级；
运行时身份；
允许的能力；
策略包；
审批模式；
可观测性覆盖；
工件包链接；
退役链接。

没有这些内容，注册表很快就会退化成一个只有名字的列表，缺少运行意义。

4. 什么时候智能体必须进入清单¶

一个比较强的默认规则通常是：

只要这个实体可以调用工具；
只要它会读取组织上下文；
只要它会代表员工或服务行动；
只要它参与生产工作流；

它至少应该进入清单。

例外情况最好被明确记录，而不是作为默许存在。

5. 什么时候智能体必须进入注册表¶

通常需要进入注册表的实体包括：

运行在生产轮廓中；
访问敏感工具或外部系统；
能产生副作用；
参与分阶段发布；
需要随时可审计的负责人。

这也是注册表对治理、审批与可靠事故响应很重要的原因。

6. 注册表应该多久检查一次¶

注册表之所以失真，通常不是因为设计不好，而是因为运行节奏太弱。

最小节奏通常包括：

每次发布更新；
每次高风险变更评审；
定期清单评审；
每次退役或替换事件；
每次事故评审之后，如果发现了隐藏智能体或陈旧记录。

如果这些时点都不更新注册表，漂移几乎不可避免。

7. 最值得优先捕捉的漂移信号¶

并不是所有漂移都同样危险。最好先盯住：

活跃智能体没有负责人；
production 智能体在追踪或注册表关联遥测里根本看不到；
已弃用智能体仍然保留活跃主体；
运行时里出现了不在允许清单中的能力；
注册表中的审批模式与策略包不一致；
已退役的工件包仍然出现在活跃运行中。

这已经足够构成一个最小连续验证闭环。

8. 什么时候该把记录改成 restricted、deprecated 或 retired¶

最好尽早调整生命周期状态：

restricted：当能力集合或审批模式被临时收窄时；
deprecated：当替换方案已经确定，新发布波次不应再走旧路径时；
retired：当主体已被撤销、发布已停止、历史状态已进入保留模式时。

这里最常见的错误很简单：智能体实际上已经退出使用，但注册表里仍然显示它已准备好用于生产。

9. 事故响应时应该看什么¶

在事故评审中，注册表的价值不在于“有目录”，而在于它应该能快速回答几件事：

哪个智能体参与了这个事件；
它的负责人是谁；
当时它处于什么生命周期状态；
哪个策略包与审批模式本应生效；
这条记录关联了哪个工件包链接与退役状态。

如果注册表不能快速回答这些问题，它对运维的帮助就很有限。

10. 最小每周评审¶

一轮简短评审可以围绕这些问题展开：

清单外是否出现了新的类似智能体实体？
是否存在无人负责的记录？
是否存在没有遥测覆盖的 production 智能体？
是否有保留活跃主体的已弃用条目？
注册表、策略包与发布状态之间是否一致？

这种评审最好保持简短，但持续进行。

11. 现在就该做什么¶

先过一遍这份短清单，把所有回答为“否”的地方单独记下来：

每个活跃智能体都有负责人吗？
清单和注册表分开了吗？
发布与退役时生命周期状态会更新吗？
注册表是否与策略包和审批模式相连？
注册表是否会对照活跃遥测进行验证？
已弃用智能体会失去主体与工具访问权吗？
事故会推动注册表卫生改进吗？