AWS Agent Registry实操：用一个注册中心管好所有AI Agent-育师

1. 多 Agent 团队的真实困境：能力散落，没人说得清

团队里 Agent 一多，最先崩掉的不是模型效果，而是「资产台账」。上个月我帮一个做智能客服的团队梳理现状，他们内部跑着 7 个 Agent、11 个 MCP Server，结果问「谁负责发邮件那个工具」，三个人给了三个答案。有人说是客服组写的，有人说是数据组接的第三方，还有人翻出半年前的 wiki 说早就废弃了。最后发现那个邮件 Agent 还在被两个线上流程调用，只是没人记得它的存在。

这就是 AWS Agent Registry 想解决的问题。它是挂在 Bedrock AgentCore 下面的一个私有目录服务，你可以把 Agent、工具、Skill、MCP Server 统一登记进去，每条记录带描述、连接信息和工具 schema。团队里谁想找某个能力，搜一下就行，不用翻代码、不用问人、不用猜。它支持关键词搜索和语义搜索两种方式，语义搜索允许你用自然语言描述需求，比如「我要一个能从合同 PDF 里抽条款的工具」，它能匹配到注册过的对应记录。

适合谁用？如果你的团队已经跑了 5 个以上的 Agent 或 MCP Server，或者你正在做多 Agent 协作、需要统一收敛治理入口，这套东西值得花半天跑通。本文会交付可复制的注册配置骨架、TaoToken 统一 Key/API 通道的接入示例，以及注册、发现、调用的完整验证动作。我实测下来，注册一两条记录跑通搜索半小时够了，真正花时间的是后面制定命名规范和审批流程。

2. 前置准备：Registry 建在哪、Key 怎么统一管

Agent Registry 目前是 Preview 版，只开在 5 个 Region：us-east-1、us-west-2、ap-northeast-1（东京）、ap-southeast-2（悉尼）、eu-west-1（爱尔兰）。你的 Agent 如果跑在新加坡或者其他没覆盖的区域，只能就近连东京，跨 Region 延迟会多几十毫秒，功能不受影响但体感慢一拍。

创建 Registry 之前要先想清楚认证方式，因为建好之后不能改。IAM 认证适合内部团队，JWT 认证适合对外开放或跨组织场景。我第一次建了 IAM 的，后来想换 JWT，发现改不了，只能删了重建，白折腾一轮。生产环境建议关掉 Auto-approval，让记录走审批；Preview 阶段开着省事，提交即生效。

另一个前置是统一 Key 通道。多 Agent 场景下最烦的是每个 Agent 各配一套模型 Key，轮换时到处改。我习惯用 TaoToken 做统一入口，一个 Key 覆盖多个模型通道，Agent 侧只认一个 base_url 和 api_key，换模型不用动 Agent 代码。官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api ，注意 API 地址不带 UTM 参数。先把 Key 拿到手，后面注册 Agent 记录时把 endpoint 指向这个统一通道，治理入口和调用入口就都收敛了。

3. 可复制配置：从建 Registry 到注册 MCP Server

3.1 创建 Registry（CLI 与 Python SDK 双写法）

CLI 方式最直接，跑完返回一个 registryArn，状态从 CREATING 变 READY 大概 1 到 2 分钟：

aws bedrock-agentcore-control create-registry \ --name "my-agent-registry" \ --description "团队Agent注册中心" \ --region us-east-1

Python SDK 写法适合塞进自动化脚本：

import boto3 client = boto3.client('bedrock-agentcore-control', region_name='us-east-1') response = client.create_registry( name='my-agent-registry', description='团队Agent注册中心' ) print(f"Registry ARN: {response['registryArn']}") print(f"Status: {response['status']}")

注意：文档里部分 Python SDK 示例的参数名和实际 API 对不上，我碰到两处。跑之前先用aws bedrock-agentcore-control create-registry help确认参数，别直接抄文档。

3.2 注册一个 MCP Server 记录

以一个 PDF 解析 MCP Server 为例，CLI 注册如下：

aws bedrock-agentcore-control create-registry-record \ --registry-name "my-agent-registry" \ --record-name "data-pdf-parser-v1" \ --record-type "MCP_SERVER" \ --description "从PDF文件中提取文字和表格数据" \ --metadata '{"endpoint": "https://mcp.example.com/pdf-parser"}' \ --region us-east-1

如果 MCP Server 已经在线且公网可达，可以用 URL-based discovery，Registry 会自动去拉工具定义和 schema，省得手动填。我有个 Server 在 VPC 内网，Registry 死活拉不到 metadata，后来配了 PrivateLink 才通。内网 Server 提前准备。

记录 name 是永久的，建好不能改，想改名只能删除重建。命名建议用team-function-version格式，比如data-pdf-parser-v1，别用test1、new这种，三个月后你自己都不认识。

3.3 注册一个 Agent 记录并指向统一 Key 通道

Agent 记录的 metadata 里放模型调用信息，把 endpoint 指向 TaoToken 统一通道：

aws bedrock-agentcore-control create-registry-record \ --registry-name "my-agent-registry" \ --record-name "cs-email-agent-v1" \ --record-type "AGENT" \ --description "客服邮件发送Agent，支持模板渲染和附件" \ --metadata '{"endpoint": "https://taotoken.net/api", "model": "claude-sonnet", "owner": "cs-team"}' \ --region us-east-1

这样注册中心里既能看到 Agent 的能力描述，也能看到它走哪个通道调模型。换模型时只改 metadata 里的 model 字段，Agent 代码不动。

3.4 关闭 Auto-approval 时的审批动作

生产环境关了 Auto-approval，记录提交后是 Pending 状态，管理员批准后才可见：

aws bedrock-agentcore-control approve-registry-record \ --registry-name "my-agent-registry" \ --record-name "data-pdf-parser-v1" \ --region us-east-1

4. 验证请求：搜索、发现、调用三步跑通

4.1 关键词搜索

注册几条记录后，先跑关键词搜索确认记录生效：

aws bedrock-agentcore-control search-registry \ --registry-name "my-agent-registry" \ --query "PDF" \ --region us-east-1

返回结果里应该能看到data-pdf-parser-v1的 name、type、description 和状态。如果返回空，先检查记录是不是还在 Pending。

4.2 语义搜索

语义搜索不要求关键词精确匹配，描述需求就行：

aws bedrock-agentcore-control search-registry \ --registry-name "my-agent-registry" \ --query "我需要一个能从文档里提取结构化数据的工具" \ --search-type SEMANTIC \ --region us-east-1

实测下来，语义搜索的中文效果不如英文。同一个需求，英文 query 命中 3 条，中文只命中 1 条。如果搜中文没结果，先换英文试试，别急着怀疑记录没注册上。

4.3 把 Registry 当 MCP Server 接进 IDE

Agent Registry 本身暴露了 MCP Server 接口，你可以在 Claude Code 或 Cursor 的 MCP 配置里把它接进来，让 AI 助手在编码时直接查注册中心有什么可用：

{ "mcpServers": { "agent-registry": { "command": "aws", "args": [ "bedrock-agentcore-control", "start-mcp-server", "--registry-name", "my-agent-registry", "--region", "us-east-1" ] } } }

配好之后，你在编码时问「有没有现成的 PDF 解析工具」，AI 助手会自动搜注册中心并返回匹配记录。这比纯 Web 管理界面实用，Agent 可以在运行时自己搜自己接，不需要人工去控制台配「这个 Agent 可以调那个工具」。

4.4 调用验证

找到记录后，用返回的 endpoint 发一次真实请求。如果 Agent 走 TaoToken 通道，验证时确认 base_url 是https://taotoken.net/api，api_key 用统一 Key。调用成功返回正常响应，说明注册、发现、调用整条链路通了。

5. 本篇常见错排查

认证方式建好不能改。IAM 和 JWT 二选一，建之前想清楚。我第一次建了 IAM 想换 JWT，只能删了重建，Registry 里已有的记录也一起没了。

Region 只有 5 个。Agent 跑在 ap-southeast-1 的话只能连 ap-northeast-1，跨 Region 延迟多几十毫秒。不影响功能，但体感慢一拍，对延迟敏感的流程要提前评估。

语义搜索中文命中率低。中文 query 命中少时先换英文，这是目前 Preview 版的已知表现，不是你的配置问题。

URL-based discovery 要求公网可达。VPC 内网的 MCP Server 拉不到 metadata，需要配 PrivateLink。内网 Server 提前准备，别等到注册时才发现。

记录 name 永久不可改。命名用team-function-version格式，别用临时名。想改名只能删除重建，重建后引用它的地方都要跟着改。

Python SDK 参数名对不上。文档示例和实际 API 有出入，跑之前用 CLI help 确认参数，别直接抄文档。

Auto-approval 关了但忘了审批。记录一直是 Pending，搜索搜不到，容易误判成注册失败。先查状态再排查其他。

6. 把治理入口收敛到一处

Agent Registry 解决的问题很具体：Agent 多了之后找不到、管不住。我们团队有个客户信息查询 Agent，另一个组不知道，自己又写了一个，注册到 Registry 之后第二个组开工前搜了一下，发现已经有了，直接接入，省了两周工作量。另一个价值是审计，每条记录的访问在 CloudTrail 里有日志，谁搜了什么、谁调了哪个 Agent 都有迹可查。

如果你要把这套跑起来，下一步动作很明确：先拿统一 Key，再建 Registry，然后注册第一条 MCP Server 记录跑通搜索。Key 在 https://taotoken.net/api-keys 拿，接入文档在 https://taotoken.net/doc ，模型对话验证在 https://taotoken.net/chat ，长期编码和 Agent 场景可以看 https://taotoken.net/coding-plan 。注册中心建好后，把现有 Agent 一个个登记进去，制定命名规范、设计审批流程，这些工程实践得自己摸。工具给你了，台账得自己建。