多智能体协作的“身份证”：Agent ID 体系设计与落地

先说个背景。前阵子我参与的内部项目做了个小规模的智能体重构，十几个不同用途的 Agent 同时在线跑，各种会话互相跳转，数据互相引用。一开始还挺顺利，等数量上了两位数，麻烦就来了：某个会话里调用了另一个 Agent 的能力，日志里只显示一串模型返回的文本，根本分不清是“谁”在什么时候替“谁”做了什么。当时我就意识到，智能体不能只有能力，还得有身份。

这也就是今天这篇文章想聊透的事——Agent 365里的“身份证”环节。我给这套方案起了个内部代号叫 Agent 365，含义很简单：让智能体 365 天都能被明确识别、可靠追溯。这篇是实操上篇，重点讲从蓝图到 Agent ID 的完整落地路径，不聊虚的，全程按能直接抄走的思路写。适合正在搭多智能体系统、被“会话串台”“权限说不清”“日志对不上账”折磨过的同学参考。

1. 为什么智能体非要一张“身份证”：三个让我决定动手的现场

先别急着看方案，我先把动机讲清楚。Agent ID 不是锦上添花，是系统复杂到一定程度后的生存刚需。下面这三个场景来自我自己的实操现场，任何一个都足以让你夜不能寐。

1.1 多个智能体协作时，日志里全是“无名氏”

智能体一多，第一块多米诺骨牌倒下的地方就是日志。早期我跑两个 Agent，一个负责检索，一个负责总结，出问题还能靠进程 PID 猜个大概。当数量扩展到十几个，情况完全失控——主 Agent 调度子 Agent，子 Agent 又嵌套调用另一个子 Agent，最终日志里全是模型输出，压根没有“这段输出是谁生成的”这个维度。

有一次线上会话突然返回了错误格式，我翻日志翻了两个小时，最后发现是某个子 Agent 在升级后改了返回结构，而主 Agent 依然按旧结构去解析。如果每个 Agent 在生成内容时都附带自己的 ID，那定位这个锅只是几秒钟的事。所谓“给智能体造身份证”，本质上是让系统的每一个参与者都能在日志里留下可追踪的指纹。

1.2 权限边界模糊，数据越权只能靠猜

第二个现场更刺痛。我有两个 Agent，一个负责处理公开资料，一个负责处理内部业务数据。理论上后者应该有更高的权限，前者不能访问内部库。结果因为我在调用链路上只用了模型名称作为区分，某次路由配置错误，公开资料 Agent 竟然带着内部库的查询凭证跑了一圈，而且整个过程没有任何拦截。

这类问题靠人眼审查代码很难发现，因为问题不出在单条逻辑上，而出在动态调用链的组合上。有了 Agent ID 之后，每个请求都能追溯到“哪个 Agent 发起的、它声明了什么权限、实际拿到了什么数据”，权限边界才真正变得可描述、可校验、可审计。

1.3 审计需求出现后，才发现“不知道谁干了什么”

第三个现场来自合规需求。某次项目评审问了我一个问题：你们系统里总共有多少个智能体？每个智能体最近一个月分别被调用了多少次？每次调用的结果有没有留痕？

我当时愣住了。命名倒是有一堆，比如“检索助手”“总结助手”“改写助手”，但要精确回答“哪个版本、在哪个时间段、被哪个上游调用”，完全无从查起。没有统一身份体系，这类审计基本做不了。于是我从零开始设计了一套 Agent ID 体系，并在一个内部项目里完整落地。下面这节，就是我落地的全过程复盘。

2. 蓝图先行：Agent ID 不是随机字符串，而是一整套身份体系

很多人听到 Agent ID，第一反应是“搞个 UUID 不就行了”。大错特错。UUID 能保证唯一性，但保证不了可读性、可路由性和可校验性。“给智能体造身份证”的关键不是造一个号，而是设计一套能承载业务规则的身份体系。

2.1 先画清楚四件事：我是谁、我属于谁、我能干什么、我怎么被信任

动手写代码之前，我花了一天半时间梳理需求。我给 Agent ID 体系定义了四个维度，对应身份证上的不同信息项：

第一维身份标识，解决“我是谁”。每个智能体要有唯一编码，这个编码要能让人一眼看出它是什么角色。比如agent-cn-retrieval-v1-0423，一眼就能看出是中文检索智能体第一版。

第二维归属关系，解决“我属于谁”。一个智能体可能被多个上层应用引用，但它的“所有者”只有一个。归属关系决定了升级、下线、故障时由谁决策。

第三维能力声明，解决“我能干什么”。这决定了智能体能访问哪些工具、哪些数据源。它不是静态标签，而是运行时会被校验的权限声明。

第四维信任凭证，解决“我怎么被信任”。别人调用我的时候，怎么确认我是我？怎么确保消息没有被篡改？这需要基于密钥或签名的机制。

这四个维度缺一不可。早期版本我只做了第一维，结果就是上面说的权限越界和审计空白。后来把四维补齐，系统才真正像一个“有身份的人”在协作。

2.2 Agent ID 结构设计：给 ID 加上“人话”逻辑

Blueprint 阶段我定了 ID 的组成规则。我的设计参考了编程语言包名和身份证号的经验，兼顾唯一性和可读性，结构分五段：

第一段是主体类型，固定用agent。将来如果系统里还要管“人”或“外部服务”，可以扩展出user、service前缀。

第二段是业务域，类似命名空间。比如cn表示中文场景，intl表示国际场景。这一层用于逻辑隔离，避免不同业务域的智能体互相误调。

第三段是职能角色，比如retrieval（检索）、summary（总结）、rewrite（改写）、planner（规划）。角色决定了这个智能体在协作链路里扮演什么位置。

第四段是版本号，用v1、v2这种格式。版本不允许省略，原因很简单——同一个角色的智能体，不同版本的返回格式和能力边界可能完全不同。没有版本号，线上跑的和日志里记录的可能是两颗不同的“灵魂”。

第五段是注册序号，用四位数字，从0001开始递增。它是全局唯一的区分符，防止前四段相同的智能体冲突。

最终的 ID 长这样：agent:cn:retrieval:v1:0001。你可能注意到我用了冒号做分隔而不是下划线或点。因为冒号在日志系统和 URI 解析里的转义成本最低，搜索拆分也方便。

2.3 元数据模型：Agent ID 只是索引，完整档案才是本体

光有 ID 还不够。ID 是一个索引，真正起作用的是 ID 背后挂载的智能体档案。我用一张表来描述每个 Agent 的完整元数据，核心字段如下：

这套元数据模型看起来朴素，但实测下来最有用。不管是做路由、做权限校验，还是做审计报表，都在这个模型上做文章，ID 本身只是引路牌。

3. 从设计到底层代码，手把手落一套能跑的 Agent ID 服务

蓝图做完，接下来是硬核环节：把 Agent ID 从文档变成能跑的代码。

3.1 编写 ID 的校验与解析逻辑，拒绝“垃圾进，垃圾出”

Agent ID 的解析和校验是整套体系的地基。我先写了一个校验函数，确保所有进入系统的 ID 都符合规范，从源头拦截格式错误的数据。

import re from typing import Dict, Optional AGENT_ID_PATTERN = re.compile( r"^(?P<type>agent):" r"(?P<domain>[a-z0-9_-]+):" r"(?P<role>[a-z0-9_-]+):" r"(?P<version>v[0-9]+):" r"(?P<seq>[0-9]{4})$" ) def parse_agent_id(agent_id: str) -> Optional[Dict[str, str]]: match = AGENT_ID_PATTERN.match(agent_id.strip()) if not match: return None return match.groupdict() # 示例 for raw in [ "agent:cn:retrieval:v1:0001", "agent:cn:retrieval:v1:0001:extra", "agent:cn:retrieval:latest:0001", ]: parsed = parse_agent_id(raw) print(f"{raw} -> {parsed}")

运行结果：

agent:cn:retrieval:v1:0001 -> {'type': 'agent', 'domain': 'cn', 'role': 'retrieval', 'version': 'v1', 'seq': '0001'} agent:cn:retrieval:v1:0001:extra -> None agent:cn:retrieval:latest:0001 -> None

注意第二个和第三个例子。第二个是段数多了，直接拒绝；第三个用了latest这种不明确的版本号，也拒绝。这里我故意禁止了latest这种标签，因为它会让“当前运行的版本”变得无法从日志中确定。所有 Agent 的版本必须是显式、不可变、可追溯的。

3.2 注册中心：Agent 上线前的第一步是“上户口”

校验逻辑写好之后，我实现了注册中心。它负责给新 Agent 分配 ID 和维护生命周期。流程并不复杂。

新 Agent 上线时，向注册中心提交申请，提交内容包括业务域、职能角色、能力声明、归属团队等。注册中心检查业务域和角色是否合法。比如domain必须是已注册的业务域，role必须在角色词典里存在。检查通过后，自动生成下一个可用序号。把完整元数据写入存储。返回正式的 Agent ID。

这样做的好处是，ID 的分配完全受控，不会出现“两个团队各自初始化，结果编码撞了”的情况。在一个多团队协作的部门里，Agent 注册中心和 CI/CD 的制品库一样，属于基础设施建设。

3.3 将 Agent ID 接入会话上下文，让每个请求都带“身份信息”

ID 不是发完就完事了，它必须被真正用起来。我在系统的会话上下文里加了一个AgentIdentity对象，随每个请求传递。

@dataclass class AgentIdentity: agent_id: str display_name: str capability_declaration: list allowed_data_sources: list @classmethod def from_registry(cls, registry, agent_id: str) -> "AgentIdentity": record = registry.fetch(agent_id) if not record: raise UnknownAgentError(f"Agent {agent_id} is not registered") return cls(**record)

主流程调用时：

def handle_request(request, registry): agent_id = request.headers.get("X-Agent-ID") identity = AgentIdentity.from_registry(registry, agent_id) if not identity: return reject("Missing or invalid Agent Identity") # 后续路由、权限、日志都基于 identity context = build_context(identity) result = planner.execute(request.payload, context) audit_logger.log(agent_id=identity.agent_id, event="request_completed") return result

这里有个容易被忽略的细节：Agent ID 必须显式地放在请求头里，而不是从消息内容里解析。放在请求头意味着它是传输层元数据，不依赖模型输出格式；从消息内容里解析则非常脆弱，模型一旦改了口径，身份就会识别不准。

4. 接入路由与权限校验，Agent ID 才开始真正发挥价值

ID 体系只有接入业务链路，才算真正落地。我把它接到了两处最关键的环节：路由和权限拦截。

4.1 基于 Agent ID 的动态路由，不再硬编码“谁调用谁”

路由层是智能体调度的枢纽。以前路由靠硬编码或模型根据模糊指令判断，不靠谱。我改成了一张动态路由表，字段包括source_agent_id、target_agent_id、action、priority。每一次调用的源智能体都会被检查，是否被允许调用目标智能体。

路由配置的粒度可以很细。比如检索 Agent 可以调用网页搜索工具，但不能调用内部数据访问模块；总结 Agent 不允许直接调用任何数据源，只能接收上游传入的文本。这些规则全部用source_agent_id + target_agent_id来约束。

这样设计的好处很直接：当业务需要调整协作关系时，不用改代码，改路由表即可。运维人员也能一眼看清系统里谁和谁可以协作，避免“黑盒式”调用链。

4.2 权限校验的落地细节，怎样避免越权

路由解决“能不能调用”，权限校验解决“调用后能拿什么数据”。我把权限服务做成了独立的中间件，每个数据请求都会经过它。

权限中间件拿到了当前请求的 Agent ID，从注册中心查出allowed_data_sources，再对比本次请求实际访问的数据源 ID。不一致就拒绝。

这一步看起来简单，实际落地时有一个非常容易踩坑的地方：上游透传身份。早期版本里，子 Agent 替主 Agent 访问数据时，携带的都是自己的 Agent ID，导致权限检查经常失败。后来我引入了“调用链身份透传”机制：子 Agent 请求中同时携带自己的 ID 和上游调用方 ID。权限校验时，取两者交集。只有源和上游都被允许访问的数据源，才会被放行。

def check_data_access(identity: AgentIdentity, upstream_identity: AgentIdentity, target_source: str) -> bool: allowed_by_self = target_source in identity.allowed_data_sources allowed_by_upstream = target_source in upstream_identity.allowed_data_sources if not allowed_by_self or not allowed_by_upstream: logger.warning("Access denied: agent=%s upstream=%s source=%s", identity.agent_id, upstream_identity.agent_id, target_source) return False return True

这条逻辑补齐之后，之前那种“公开 Agent 摸到内部库”的越权场景被彻底堵死。

4.3 日志与审计：ID 带来的直接回报

接入 Agent ID 之后，日志从“混沌一团”变成了“结构化事件流”。每条关键日志都会记录agent_id、upstream_agent_id、target_agent_id、timestamp、action等核心字段。

审计报表也顺手解决了。部门里问“系统有几个智能体、分别活跃吗”，一条 SQL 就能查出来。系统里哪些 Agent 在近 30 天没有被调用，哪些调用频次异常高，哪些 Agent 的失败率明显高于同类，一目了然。这些数据对资源规划和容量管理非常有用。

5. 实操中的教训：Agent ID 这套方案哪里最容易被低估

最后这段是我最想写的。方案看着简单，实际操作却有不少坑。如果从一开始就意识到这些问题，能省下大把调试时间。

5.1 被低估的 ID 迁移成本：老 Agent 换新 ID 的阵痛

我刚推 Agent ID 时，系统里已经有一批在跑的智能体，它们的调用关系和日志记录都是基于旧的模型名称建立的。要给它们补办“身份证”，不只是加个 ID 字段那么简单，还涉及调用链上所有相关方的同步修改。

最痛的是：某个上游服务缓存了旧标识，导致切换后一段时间内持续向下游发送旧格式的调用，下游校验全部拒绝。最后我只能加一个“兼容期”配置，在路由层做新旧 ID 映射。这个过程拖了一周才完全收敛。

我的建议是尽量早做，最好在系统还没复杂起来的时候就定好规范。已经跑起来的系统，迁移时要把“兼容期”当成正式计划的一部分来做，而不是临时救火。

5.2 校验规则太松或太紧，都会出问题

校验规则也不是越严格越好。我在早期把所有字段都限制为纯小写字母和数字，结果某个海外团队的业务域必须包含大写缩写，导致他们的 Agent 注册被反复拒绝。后来放开到允许[a-z0-9_-]，问题才解决。

反过来，版本号字段早期允许v1.2.3这种带小版本的写法。后来发现，小版本更新太频繁，导致日志里的版本标识飞速变化，根本无法稳定关联“线上实际运行的是哪一套行为”。最后我定了规则：Agent ID 里的版本只记录大版本，小版本和构建号放在注册中心元数据里。这样既保留追溯能力，又不至于让 ID 频繁跳动。

5.3 别忘了身份体系的运维：密钥轮换和下线管理

最后提醒一个很多人会忽略的点：Agent ID 体系不是建完就能一直跑。它还涉及密钥管理、状态迁移等运维细节。

每个 Agent 注册时，我都会签发一对密钥，用于调用时的签名校验。密钥需要定期轮换，轮换周期建议 90 天。轮换时要用“先加新、后删旧”的方式，避免正在跑的任务因为密钥缺失直接失败。

Agent 下线也要走流程：先把状态改为 deprecated，观察一段时间，确认没有流量后再置为 retired，最终归档。快刀斩乱麻的方式会让正在引用它的人直接扑空。

我在实际项目里被迫处理过一次“已下线的 Agent 仍被调用”的事故，原因就是状态没有置成 deprecated，调用方不知道它已经不再维护。所以状态迁移这件事，务必作为流程固定下来。

这套 Agent ID 身份体系，我从设计到带我手下的开发落地，用了大约三周。效果很明显：日志可读了，权限可控了，审计可查了，协作链条清晰了。下一篇我会写实操下篇，重点讲怎么在 Agent ID 之上构建多智能体的可信协作机制，包括调用链签名、消息溯源和会话级身份绑定这几个更硬核的话题。如果你正在被多智能体的“身份混乱”折磨，今天这篇里讲的设计思路和代码骨架，可以直接拿去改改落地。