Discover tools at runtime with AWS Agent Registry

Runtime discovery with AWS Agent Registry can help address a problem that agent demos might hide. Hardcoded tools work fine for a handful, start to degrade at a few dozen, and become unmanageable beyond that. Enterprise systems expose hundreds of internal APIs for pricing, support, orders, inventory, and customer data. In these systems, the model can spend more tokens disambiguating tool names than reasoning about the user’s request. Each new capability requires a code change in the orchestrator, a redeploy, and a coordinated release across teams that would much rather ship on their own cadence. This pattern can arise across enterprise software as a service (SaaS) engagements where teams expose large internal API surfaces to agentic consumers. Build-time wiring can become a bottleneck as the catalog expands. One approach is to change how the orchestrator accesses its tools: instead of compiling every tool into the agent, the agent can discover relevant tools at runtime. AWS Agent Registry is a managed service for cataloging and discovering Model Context Protocol (MCP) servers, agents, and agent skills. Publishers register protocol-specific descriptors and searchable descriptions. At runtime, an orchestrator can search approved, discoverable records and use the returned endpoint and descriptor content to construct a client. Registry search results do not return the capability’s invocation credentials or authentication scheme. This post walks through the Discover → Instantiate → Execute loop demonstrated by the refactored Python sample. The code deploys an order-management MCP server through Amazon Bedrock AgentCore Gateway , a capability of Amazon Bedrock AgentCore, two agent-to-agent (A2A) agents on AgentCore runtime , a Registry, and an orchestrator. The sample directory contains the deployment script, orchestrator, helper modules, and cleanup script. Solution overview: discover, instantiate, execute The orchestrator agent in this sample has no built-in knowledge of tools or agents. Figure 1: Without AWS Agent Registry (left), endpoints are hardcoded and adding a new agent means code changes plus redeployment. With AWS Agent Registry (right), the orchestrator discovers capabilities through semantic search and new integrations are usable after registration and approval Discover The orchestrator sends a natural-language query to the AWS Agent Registry data plane. The search response includes record identity, name, description, record type, status, version, and protocol descriptors such as MCP server metadata or an A2A agent card. It does not include invocation credentials. The application must obtain and apply the appropriate credentials through a separate, trusted configuration path. Instantiate For each returned record, the orchestrator constructs a client from the descriptor type. In this sample, the registered MCP server represents tools that were first added as targets to Amazon Bedrock AgentCore Gateway. The MCP descriptor therefore points to the Gateway endpoint. The orchestrator fetches a Cognito OAuth access token separately and uses it when creating the MCPClient . A2A records contain an agent card whose URL identifies an AgentCore runtime endpoint. The wrapper invokes that runtime through the boto3 data-plane client, which signs the request with the caller’s AWS credentials. Registry discovery supplies connection metadata, not the authentication material. Execute An ephemeral inner agent is built with only the dynamically-discovered tools. The large language model (LLM) picks the right one(s) for the request, and the result is synthesized back to the user. After the turn finishes, the inner agent and its clients are torn down. The next request gets a fresh search and a fresh tool set. Figure 2: End-to-end architecture. A single orchestrator on Amazon Bedrock AgentCore runtime queries AWS Agent Registry. Matched MCP servers are invoked through Amazon Bedrock AgentCore Gateway, and matched A2A agents are invoked on Amazon Bedrock AgentCore runtime The reference architecture used in the sample includes AWS Agent Registry , Amazon Bedrock AgentCore Gateway , Amazon Bedrock AgentCore runtime , Amazon Bedrock, Amazon Cognito, AWS Lambda, and AWS Secrets Manager. AWS Agent Registry provides the governed, searchable catalog queried by the orchestrator. Only records that complete the configured approval workflow are available through the discoverable data plane. Amazon Bedrock AgentCore Gateway exposes the order-management Lambda tools as an MCP server. The sample configures Cognito JWT authorization for inbound Gateway calls and uses the Gateway AWS Identity and Access Management (IAM) role to invoke the Lambda target. Amazon Bedrock AgentCore runtime hosts the orchestrator and the Pricing and Customer Support A2A agents. Runtime invocations use IAM-authorized Boto3 calls. Amazon Bedrock provides the foundation model (FM) used by the orchestrator and A2A agents. The sample currently configures an Anthropic Claude Sonnet model through a cross-Region model ID. See Supported models by AWS Region in Amazon Bedrock . Three demo scenarios exercise the discovery loop with different capability combinations. The first is an MCP-only call (order status). The second chains MCP + A2A (pricing and discounts). The third tests a pure semantic match against ambiguous user intent: return and refund, where those words don’t appear in the matched A2A agent’s name. Technical implementation The linked runtime-discovery sample deploys the dependencies, creates and populates the Registry, verifies discovery, deploys the orchestrator, and runs three demos. orchestrator_agent.py contains the per-request discovery loop. utils.py parses Registry descriptors and creates MCP and A2A clients. cleanup.py removes resources. 1. The registration model A Registry record contains a searchable description plus a protocol-specific descriptor. The sample uses the Agent Registry control-plane client for Registry and record lifecycle operations and the Agent Registry data-plane client for runtime discovery. Creating a Registry with manual approval and IAM authorization. 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] The recordType field is required when creating a record. In this sample, MCP servers use recordType="MCP" and A2A-backed agents use recordType="AGENT" . Protocol metadata is stored under mcpServer or a2aAgentCard in the descriptors object. An MCP descriptor contains server metadata and tool definitions. An A2A descriptor contains the agent card. The descriptors contain connection metadata but not the credentials that a consumer must present when invoking the capability. Building current public-SDK descriptor shapes for MCP and A2A records. # 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", } } Write descriptions in user-facing language that distinguishes the capability from neighboring records. Descriptor content supplies the protocol-specific server, tool, or agent-card data. Search quality should be evaluated with representative queries. This post does not assume that catalog growth automatically improves ranking. Creating a Registry record with the current control-plane shape. descriptors = ( mcp_descriptors if cfg["protocol"] == "MCP" else a2a_descriptors ) response = registry_client.create_regi