跳到正文
AWS Machine Learning Blog· Vibhu Pareek·· 2 小时前精选AI 评分58

AWS 发布 Agent Registry 运行时工具发现教程

Discover tools at runtime with AWS Agent Registry

AI 导读

AWS 官方博客介绍用 AWS Agent Registry 在运行时发现 MCP 服务器与 A2A 智能体，替代把工具硬编码进编排器。

推荐理由

原文给出可运行的发现、实例化、执行循环与代码，读者可据此评估运行时工具发现替代硬编码的适用边界。

正文 · AI 翻译

使用 AWS Agent Registry 进行运行时发现，可以帮助解决智能体演示可能掩盖的一个问题。硬编码工具在只有少数几个时运行良好，到几十个时开始退化，再往上就变得难以管理。企业系统会暴露数百个内部 API，用于定价、支持、订单、库存和客户数据。在这些系统中，模型花在消歧工具名称上的 token 可能比推理用户请求还多。每新增一项能力，都需要在编排器中修改代码、重新部署，并在多个团队之间协调发布，而这些团队更愿意按自己的节奏交付。

这种模式可能出现在企业软件即服务（SaaS）项目中，这些项目中的团队向智能体消费者暴露大量内部 API 接口。随着目录扩大，构建时接线可能成为瓶颈。一种方法是改变编排器访问其工具的方式：不再将每个工具编译进智能体，而是让智能体在运行时发现相关工具。

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

本文逐步介绍重构后的 Python 示例所演示的 Discover → Instantiate → Execute 循环。该代码通过 Amazon Bedrock AgentCore Gateway（Amazon Bedrock AgentCore 的一项能力）部署一个订单管理 MCP 服务器、在 AgentCore runtime 上部署两个智能体到智能体（A2A）智能体、一个 Registry 以及一个编排器。示例目录包含部署脚本、编排器、辅助模块和清理脚本。

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

此示例中的编排器智能体没有内置的工具或智能体知识。

Comparison of hardcoded tool endpoints versus runtime discovery with AWS Agent Registry

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

发现

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

实例化

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

执行

一个临时的内部代理仅使用动态发现的工具构建。大语言模型（LLM）为请求挑选合适的工具，并将结果综合后返回给用户。本轮结束后，内部代理及其客户端被拆除。下一个请求会获得全新的搜索和全新的工具集。

End-to-end architecture: the orchestrator queries AWS Agent Registry, then invokes MCP servers through AgentCore Gateway and A2A agents on AgentCore runtime

图 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。

三个演示场景以不同的能力组合演练发现循环。第一个是仅 MCP 调用（订单状态）。第二个串联 MCP + A2A（定价和折扣）。第三个针对模糊的用户意图测试纯语义匹配：退货和退款，而这两个词并未出现在所匹配 A2A 代理的名称中。

技术实现

链接的运行时发现示例部署依赖项、创建并填充 Registry、验证发现、部署编排器并运行三个演示。orchestrator_agent.py 包含按请求的发现循环。utils.py 解析 Registry 描述符并创建 MCP 和 A2A 客户端。cleanup.py 删除资源。

1. 注册模型

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

创建具有手动审批和 IAM 授权的 Registry。

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 描述符包含代理卡片。描述符包含连接元数据，但不包含使用方在调用该能力时必须提供的凭证。

为 MCP 和 A2A 记录构建当前公共 SDK 描述符结构。

# 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",
    }
}

用面向用户的语言编写描述，使其能够将该能力与相邻记录区分开来。描述符内容提供协议特定的服务器、工具或 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. 编排器

编排器是一个部署到 Amazon Bedrock AgentCore runtime 的 Strands agent。它暴露 discover_and_execute，该接口会搜索 Registry，解析每个返回的描述符，创建相应的 MCP 或 A2A 客户端，并仅根据这些发现的能力构建请求作用域内的内部 agent。

The orchestrator’s per-request flow, where an outer agent searches the Registry and assembles a request-scoped inner agent from the results

图 3：编排器的每请求流程。外部 agent 将用户请求转换为 Registry 搜索。内部 agent 由搜索结果组装而成，并在该轮结束时拆除

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 returns descriptors, not invocation credentials. 
     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​

该示例会扇出多个搜索查询，以提高其订单管理领域的召回率，对记录去重，并在请求后拆除 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 合成人类可读的响应，内部 agent 终止。此轮不涉及 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 agent：两个协议，一个自然语言查询。LLM 调用 get_order_status 获取行项目，然后在 runtime 上调用定价 agent 进行折扣分析，最后合成单一建议。

演示 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”这个短语并未出现在 Customer Support Agent 的注册名称中。混合搜索之所以将其排在前面，是因为它的描述捕捉到了这一意图。如果没有 Registry，编排器就需要硬编码知道哪个 agent 负责退货。

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 描述符，并实例化请求作用域的客户端。治理决定哪些内容可被发现。身份验证仍然是 Registry 和每个被调用能力的明确关注点。

AWS Agent Registry 已正式可用，其能力超出了这个单账户示例：

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

运行运行时发现示例，然后注册一个你自己的兼容 MCP 服务器或代理。确认其描述符、审批状态、身份验证路径和搜索行为符合你的生产要求。

了解更多

关于作者

Vibhu Pareek

Vibhu Pareek

Vibhu 是 AWS 的高级解决方案架构师。自 2016 年以来，他一直指导客户采用架构良好、可重复的模式上云。凭借在数据库、数据分析和 AI 方面的专长，他擅长将复杂挑战转化为创新解决方案。工作之余，他喜欢短途徒步以及羽毛球、足球和游泳等运动。

Shubham Gupta

Shubham Gupta

Shubham 是 AWS 驻印度班加罗尔的解决方案架构师，为独立软件供应商（ISV）提供支持。他与工程和领导团队合作，在 AWS 上设计、构建和运行其产品，从初始架构到生产环境，并深度关注生成式 AI 和大规模韧性。工作之余，Shubham 是一位热衷的徒步爱好者，他将徒步中的准备和坚持同样带入构建持久系统的过程中。

来源：AWS Machine Learning Blog · aws.amazon.com

Agent 智能体部署工程MCP 与工具调用教程实践#教程/实践#Agent#MCP/工具调用#部署/工程