AWS Agent Registry 发布 支持运行时工具发现

使用 AWS Agent Registry 进行运行时发现，有助于解决智能体演示中可能隐藏的一个问题。硬编码工具在数量较少时运行良好，但在达到几十个时开始性能下降，超过这个数量后便难以管理。企业系统通常会暴露数百个内部 API，用于处理定价、支持、订单、库存和客户数据等事务。在这些系统中，模型可能会花费比推理用户请求更多的 token 来消除工具名称的歧义。每增加一项新功能，都需要修改编排器代码、重新部署，并在那些更希望按各自节奏发布的团队之间协调发布流程。

这种模式常见于企业软件即服务（SaaS）场景中，团队向智能体消费者暴露大规模的内部 API 接口。随着目录规模的扩大，构建时的静态接线可能成为瓶颈。一种解决方案是改变编排器访问其工具的方式：不再将所有工具编译进智能体中，而是让智能体在运行时动态发现相关工具。

AWS Agent Registry 是一项托管服务，用于对 Model Context Protocol (MCP) 服务器、智能体和智能体技能进行编目和发现。发布者注册特定协议的描述符和可搜索的描述信息。在运行时，编排器可以搜索已批准且可发现的记录，并利用返回的端点和描述符内容来构建客户端。Registry 搜索结果不会返回该能力的调用凭证或身份验证方案。

本文将逐步介绍重构后的 Python 示例所展示的“发现 → 实例化 → 执行”循环。该代码通过 Amazon Bedrock AgentCore Gateway（Amazon Bedrock AgentCore 的一项功能）部署了一个订单管理 MCP 服务器，在 AgentCore runtime 上部署了两个智能体到智能体（A2A）的智能体，以及一个 Registry 和一个编排器。示例目录包含部署脚本、编排器、辅助模块和清理脚本。

解决方案概览：发现、实例化、执行

本示例中的编排器智能体不具备任何内置的工具或智能体知识。

图 1：不使用 AWS Agent Registry（左），端点是硬编码的，添加新智能体需要修改代码并重新部署。使用 AWS Agent Registry（右），编排器通过语义搜索发现能力，新集成在注册和审批后即可使用

发现 (Discover)

编排器向 AWS Agent Registry 数据平面发送自然语言查询。搜索结果包括记录标识、名称、描述、记录类型、状态、版本以及协议描述符（如 MCP 服务器元数据或 A2A 智能体卡片）。结果中不包含调用凭证。应用程序必须通过单独的受信任配置路径获取并应用适当的凭证。

实例化 (Instantiate)

对于每个返回的记录，编排器根据描述符类型构建客户端。在此示例中，注册的 MCP 服务器代表最初作为目标添加到 Amazon Bedrock AgentCore Gateway 的工具。因此，MCP 描述符指向 Gateway 端点。编排器单独获取 Cognito OAuth 访问令牌，并在创建 MCPClient 时使用该令牌。A2A 记录包含一个智能体卡片，其 URL 标识了 AgentCore 运行时端点。包装器通过 boto3 数据平面客户端调用该运行时，该客户端使用调用者的 AWS 凭证对请求进行签名。Registry 发现提供的是连接元数据，而非认证材料。

执行 (Execute)

构建一个临时的内部智能体，仅包含动态发现的工具。大语言模型 (LLM) 为请求选择正确的工具，并将结果综合后返回给用户。回合结束后，内部智能体及其客户端会被销毁。下一个请求将执行全新的搜索并获取全新的工具集。

图 2：端到端架构。Amazon Bedrock AgentCore runtime 上的单个编排器查询 AWS Agent Registry。匹配的 MCP 服务器通过 Amazon Bedrock AgentCore Gateway 调用，匹配的 A2A 智能体在 Amazon Bedrock AgentCore runtime 上调用

示例中使用的参考架构包括 AWS Agent Registry、Amazon Bedrock AgentCore Gateway、Amazon Bedrock AgentCore runtime、Amazon Bedrock、Amazon Cognito、AWS Lambda 和 AWS Secrets Manager。

• AWS Agent Registry 提供由编排器查询的受治理且可搜索的目录。只有完成配置审批流程的记录才可通过可发现数据平面访问。
• Amazon Bedrock AgentCore Gateway 将订单管理 Lambda 工具作为 MCP 服务器暴露出来。该示例为入站 Gateway 调用配置了 Cognito JWT 授权，并使用 Gateway 的 AWS Identity and Access Management (IAM) 角色来调用 Lambda 目标。
• Amazon Bedrock AgentCore runtime 托管编排器以及定价和客户支持 A2A 智能体。Runtime 调用使用经过 IAM 授权 的 Boto3 调用。
• Amazon Bedrock 提供编排器和 A2A 智能体使用的基础模型（FM）。该示例目前通过跨 Region 模型 ID 配置了一个 Anthropic Claude Sonnet 模型。请参阅 Amazon Bedrock 中按 AWS Region 支持的模型。

三个演示场景通过不同的能力组合来验证发现循环。第一个是仅涉及 MCP 的调用（订单状态）。第二个串联了 MCP + A2A（定价与折扣）。第三个测试针对模糊用户意图的纯语义匹配：退货与退款，其中这些词汇并未出现在匹配到的 A2A 智能体的名称中。

技术实现

链接的运行时发现 示例 部署依赖项、创建并填充注册表（Registry）、验证发现功能、部署编排器（orchestrator），并运行三个演示。orchestrator_agent.py 包含每次请求的发现循环。utils.py 解析注册表描述符并创建 MCP 和 A2A 客户端。cleanup.py 用于移除资源。

1. 注册模型

注册表记录包含可搜索的描述以及特定于协议的描述符。该示例使用 Agent Registry 控制平面客户端来执行注册表和记录的生命周期操作，并使用 Agent Registry 数据平面客户端进行运行时发现。

通过手动审批和 IAM 授权创建注册表。

registry_client = session.client("agent-registry-control")
dp_client = session.client("agent-registry")
reg = registry_client.create_registry(
    name="OrderManagementRegistry",
    description=(
        "Registry for Order Management & Customer Service — "
        "agent discovers tools and agents via semantic search"
    ),
    approvalConfiguration={"autoApprovalRules": []},
)
REGISTRY_ARN = reg["registryArn"]
REGISTRY_ID = REGISTRY_ARN.split("/")[-1]

在创建记录时，recordType 字段是必需的。在此示例中，MCP 服务器使用 recordType="MCP"，而基于 A2A 的智能体使用 recordType="AGENT"。协议元数据存储在 descriptors 对象下的 mcpServer 或 a2aAgentCard 中。MCP 描述符包含服务器元数据和工具定义。A2A 描述符包含智能体卡片（agent card）。描述符包含连接元数据，但不包含消费者在调用能力时必须出示的凭证。

构建当前公共 SDK 中 MCP 和 A2A 记录的描述符格式。

# MCP descriptor
mcp_descriptors = {
    "mcpServer": {
        "data": json.dumps(server_metadata),
        "dataSchemaVersion": "2025-12-11",
        "additionalData": {
            "tools": {
                "data": json.dumps({"tools": tool_schemas}),
                "dataSchemaVersion": "2025-06-18",
            }
        },
    }
}

# A2A descriptor
a2a_descriptors = {
    "a2aAgentCard": {
        "data": json.dumps(agent_card),
        "dataSchemaVersion": "0.3",
    }
}

使用面向用户的语言编写描述，以区分该能力与相邻记录。Descriptor 内容提供协议特定的服务器、工具或 Agent Card 数据。应使用具有代表性的查询来评估搜索质量。本文不假设目录的增长会自动改善排名。

使用当前的控制平面结构创建 Registry 记录。

descriptors = (
    mcp_descriptors
    if cfg["protocol"] == "MCP"
    else a2a_descriptors
)

response = registry_client.create_registry_record(
    registryId=REGISTRY_ID,
    name=name,
    description=cfg["description"],
    recordType=cfg["protocol"],
    descriptors=descriptors,
    recordVersion="1.0",
)
record_id = response["recordId"]

2. 审批工作流

当 autoApproval 设置为 false 时，新记录必须从 DRAFT（草稿）状态移动到 PENDING_APPROVAL（待审批），然后变为 APPROVED（已批准）。提交和状态更新操作受 IAM 授权，允许将发布者和审批者的权限分离。只有已批准的记录才会由可发现的 Registry 数据平面返回。

两步审批转换。

record = registry_client.get_registry_record(
    registryId=REGISTRY_ID,
    recordId=record_id,
)
if record["status"] == "DRAFT":
    registry_client.submit_registry_record_for_approval(
        registryId=REGISTRY_ID,
        recordId=record_id,
    )
    registry_client.update_registry_record_status(
        registryId=REGISTRY_ID,
        recordId=record_id,
        status="APPROVED",
        statusReason="Approved",
    )

3. 发现层

数据平面客户端支持对可发现记录进行混合关键词与语义搜索。最新的方法名为 search_discoverable_registry_records。搜索结果会暴露规范化的记录字段和可发现描述符，但不会暴露该能力的调用凭证。

跨协议搜索已批准的可发现记录。

response = dp_client.search_discoverable_registry_records(
    registryIds=[REGISTRY_ARN],
    searchQuery=query,
    maxResults=3,
)
records = response.get("registryRecords", [])

在示例场景中，“退货退款”查询能够检索到客户支持代理（Customer Support Agent），因为其描述涵盖了该意图。请将此视为演示结果，而非“目录规模越大排名就越好”这一普遍结论的证明。

4. 编排器（Orchestrator）

编排器是一个部署在 Amazon Bedrock AgentCore 运行时上的 Strands agent。它暴露了 discover_and_execute 方法，该方法会搜索注册表（Registry），解析每个返回的描述符，创建相应的 MCP 或 A2A 客户端，并仅基于这些发现的能力构建一个请求作用域（request-scoped）的内部代理。

图 3：编排器的每请求流程。外部代理将用户请求转化为注册表搜索操作。内部代理根据搜索结果组装而成，并在对话轮次结束时被销毁。

discover_and_execute 的核心逻辑可以容纳在一个代码块中：

编排器的发现/实例化/执行循环。

​​​@tool 
 def discover_and_execute(request: str) -> str: 
     records = dp_client.search_discoverable_registry_records( 
         registryIds=[REGISTRY_ARN], 
         searchQuery=request, 
         maxResults=5, 
     ).get("registryRecords", [])

# Registry 返回的是描述符，而非调用凭证。 
     oauth_token = fetch_oauth_token_from_config() 
     mcp_clients, a2a_tools = [], [] 
     for record in records: 
         metadata = parse_server_metadata(record) 
         if metadata["protocol"] == "MCP": 
             mcp_clients.append( 
                 create_mcp_client_from_metadata(metadata, oauth_token) 
             ) 
         elif metadata["protocol"] == "A2A": 
             a2a_tools.append( 
                 create_a2a_tool_from_metadata(metadata, session, REGION) 
             ) 

    return run_request_scoped_agent(request, mcp_clients, a2a_tools)

model = BedrockModel(model_id=MODEL_ID, region_name=REGION) 
    started_clients = [] 
    try: 
        mcp_tools = [] 
        for c in mcp_clients: 
            c.start() 
            started_clients.append(c) 
            mcp_tools.extend(c.list_tools_sync())

        ##agent compiled in realtime within agent 
        sub_agent = Agent( 
            model=model, 
            tools=mcp_tools + a2a_tools, 
            system_prompt=( 
                "You are an Order Management & Customer Service assistant. " 
                "Use the RIGHT tool for each request:\\n" 
                "- Order lookups, status, cancellations, address changes: use MCP tools\\n" 
                "- Pricing, discounts, promo codes: use the pricing_agent tool\\n" 
                "- Returns, refunds, complaints, escalations: use the customer_support_agent tool\\n" 
                "Always use the most specific tool for the task." 
            ), 
        ) 
        return str(sub_agent(request)) 
    finally: 
        for c in started_clients: 
            try: 
                c.stop() 
            except Exception: 
                pass 

该示例通过扇出（fan-out）多个搜索查询来提高其订单管理领域的召回率，对记录进行去重，并在请求结束后拆除 MCP 客户端。这种扇出操作是示例特定的编排选择，并非 Registry 的要求。身份验证独立于发现过程：Gateway OAuth 令牌从 Cognito 配置和 Secrets Manager 中获取，而 A2A 运行时调用则通过 boto3 会话进行签名。

5. 运行三个演示

每个演示都针对发现循环的不同形态进行实践。

演示 1：订单状态（仅 MCP）

一个解析为单个 MCP 工具调用的请求。

result = invoke_orchestrator(
    "What is the current status and tracking info for order 123?",
    agentcore_client, orchestrator_arn,
)

Registry 返回订单管理 MCP 服务器。编排器通过 Gateway 调用 get_order_status，LLM 综合生成人类可读的响应，内部代理随即终止。本轮交互不涉及 A2A。

演示 2：定价与折扣（MCP + A2A）

一个解析为多协议链的请求。

result = invoke_orchestrator(
    "Order 123 has 2x Widget Pro at $99.98. What discount tiers or "
    "promo codes can reduce the price?",
    agentcore_client, orchestrator_arn,
)

Registry 返回订单管理 MCP 服务器和定价 A2A 代理：两种协议，对应一个自然语言查询。LLM 首先调用 get_order_status 获取行项目信息，然后在运行时调用定价代理进行折扣分析，最后综合生成单一推荐方案。

演示 3：退货与退款（语义匹配）

一个其意图并未字面出现在任何工具名称中的请求。

result = invoke_orchestrator(
    "I want to return order 789 (Premium Headphones, delivered "
    "March 10). Am I eligible for a return and what is the refund "
    "amount?",
    agentcore_client, orchestrator_arn,
)

此演示展示了语义发现的价值。“return refund”这一短语并未出现在客户支持代理的注册名称中。混合搜索之所以将其排名靠前，是因为其描述准确捕捉了用户意图。若没有 Registry，编排器将需要硬编码知识来明确哪个代理负责处理退货。

6. 可观测性

使用 Amazon Bedrock AgentCore Observability 和 Amazon CloudWatch 对发现与调用路径进行监控。有用的信号包括：Registry 搜索的成功与失败、选定的记录标识符、客户端构建错误、下游调用结果、端到端追踪关联以及应用错误。示例代码授予了 Amazon CloudWatch Logs 权限，但并未创建自定义指标或仪表盘。生产团队应根据其运营模型定义所需的追踪、日志和告警。此外，生产部署应将 Amazon Bedrock Guardrails 作为针对 Agent 响应的标准控制措施加以应用。

受治理的运行时发现为团队带来的收益

一旦建立发现循环，此前与编排器发布版本耦合的多项能力即可实现解耦。

• 解耦式发布。团队可以独立部署并注册自己的 MCP 服务器、Agent 和技能。审批策略决定已发布的记录何时可供消费者使用。
• 新增获批记录无需修改编排器代码。在此模式下，添加兼容且已获批的 Registry 记录无需在编排器中引入特定工具的导入或端点。但协议、身份验证设置或编排策略的变更仍可能需要更新代码或配置。
• 受治理的发现。通过手动审批机制，仅经过审核并获批的记录才可被发现。IAM 权限可将记录发布者与审批者分离。
• 身份验证分离。Registry 授权可使用 IAM 或自定义 JWT。能力调用的身份验证则独立处理：示例中对 Gateway 使用 Cognito OAuth，对 AgentCore 运行时使用 Boto3/IAM 签名。搜索结果不会返回这些凭证。
• 目录搜索而非提示词填充。借助混合 Registry 搜索，编排器检索的是少量候选集，而非将整个目录放入模型上下文中。搜索质量取决于描述信息、描述符质量、查询设计及评估效果。

何时不使用运行时发现

并非所有工作负载都需要运行时发现。以下两种模式仍可能更倾向于显式的构建时接线方式：

• 小型、稳定的目录。如果完整的能力集较小且很少变化，显式的构建时接线可能更简单，并避免额外的发现请求。
• 固定流水线。当相同的能力始终以固定顺序运行时，将其实现为确定性流程更为直接，并保持追踪的聚焦性。

结论

在运行时从注册中心（Registry）发现资产，使编排器不再依赖于固定的目录。针对 AWS Agent Registry，它可以利用混合语义和关键词搜索来查找已批准的能力，解析 MCP 或 A2A 描述符，并实例化请求作用域（request-scoped）的客户端。治理机制决定了哪些内容是可发现的。身份验证仍然是注册中心和每个被调用能力的明确关注点。

AWS Agent Registry 已正式可用，其功能超越了此单账户示例的范围：

• 组织范围内的发现和跨账户共享可以通过受支持的 AWS Organizations 和共享机制，在账户边界之间暴露经过治理的记录。
• 自动能力同步可以从 URL 填充受支持的描述符。该同步请求上的凭证提供者配置用于获取描述符内容。它不会作为调用身份验证返回给运行时消费者。
• 审批工作流可以使用注册中心状态 API 和 IAM 权限，将 CI 检查、安全审查或人工审批连接到 DRAFT → PENDING_APPROVAL → APPROVED 的生命周期中。
• 标签、AWS CloudFormation 支持以及基础设施即代码模式可以使注册中心的部署和治理具有可重复性。评估应针对组织自身的目录验证搜索相关性和调用行为。

运行 runtime-discovery 示例，然后注册一个你自己的兼容 MCP 服务器或 agent。确认其描述符、审批状态、认证路径和搜索行为符合你的生产环境要求。

了解更多

• AWS Agent Registry 正式发布公告
• AWS Agent Registry 文档
• Amazon Bedrock AgentCore 控制台（Registry）
• AWS Agent Registry 正式发布的官方技术博客文章