AWS Agent Registry: A Practical Guide to Governing Agents at Scale
Once a business has more than one team building agents, a predictable set of problems shows up. Nobody has a clear picture of who has built what, so the same MCP server gets rebuilt three times instead of reused once. Tools get wired into agents without any validation, which is how a security blind spot ends up in production without anyone noticing. And once a handful of agents exist, there’s no shared way to tell whether any of them are actually performing, or to catch it early when one isn’t.
AWS Agent Registry, part of Bedrock AgentCore and currently in preview, is built to be the fix: a unified, searchable catalogue for every agent, MCP server, skill, and tool an organisation has built, sitting next to the identity and observability layers that already track who did what.
What’s actually in it
The registry indexes four record types. MCP servers register against the official MCP registry server schema. A2A agents register against the official A2A Agent Card schema. Agent skills register against the Skills.md schema. Anything that doesn’t fit one of those gets a custom schema, as long as it’s valid JSON with a descriptorType. Search runs as a hybrid of semantic, lexical, and filter-based matching, so a query can be a natural-language description of what you need or an exact name and version filter, depending on whether you’re exploring or already know what you’re looking for.
Three roles sit around the registry. Publishers build and register agents, tools, and skills. Admins own the registry infrastructure, set the approval guardrails, and control what’s visible to whom. Consumers, human developers or other agents, discover and integrate what’s already there instead of building it again.
The approval workflow
A publisher creates a record in draft. Submitting it for approval triggers metadata and schema validation, and from there EventBridge either kicks off an automated CI pipeline check or routes it to a human curator, depending on how the admin has configured it. The admin approves or rejects. Only approved records become discoverable, whether that’s a developer searching the console, an agent calling the search API, or an IDE connecting through an MCP endpoint.
That approval gate is the whole point. It’s the single checkpoint where an admin can catch a security issue, kill a duplicate build, or control exactly what the rest of the organisation can see, rather than every team pushing whatever they’ve built straight into a shared namespace. One thing worth planning for operationally: search results go eventually consistent after a change, typically within a few seconds, so if you’re triggering a search right after an approval event, build in a short delay.
Choosing a discovery pattern
The harder engineering decision is how an agent actually finds and uses the registry at runtime. AWS’s own guidance for the Strands SDK lays out five patterns, and they trade off along three axes: who controls discovery (your code, the LLM, or the framework), when it happens (upfront, on demand, or reactively), and how much the LLM knows the registry exists at all.
Programmatic pre-fetch is the simplest: your code calls the registry before the agent even starts and hands it a fixed tool list. Fast to build, but the discovery logic is hardcoded and you pay a registry call on every invocation. Registry-as-tool gives the LLM a search_registry tool it can call when it decides it needs a capability, at the cost of an extra round-trip. Hook interception lets an agent call tools by name as it always has, while a hook resolves the real implementation from the registry behind the scenes, which is the easiest way to retrofit registry support into an agent that already has tool names baked into its prompts. Planner-executor splits the work into a planning agent that searches the registry and an executor agent that only ever sees the tools the planner selected, which keeps context tight for complex multi-step tasks.
AWS calls the fourth pattern, ToolProvider, or registry-as-plugin, the recommended default. It plugs into Strands’ ToolProvider interface, resolving tools lazily on first access and caching them after that:
class RegistryToolProvider(ToolProvider):
async def load_tools(self, **kwargs) -> Sequence[AgentTool]:
"""Called by Strands when the agent needs its tool list."""
return dp_client.search_registry_records(...)
agent = Agent(
model="us.anthropic.claude-sonnet-4-6",
tools=[
RegistryToolProvider(
registry_id=REGISTRY_ID,
domain_query="order management CRM inventory",
auth_context={"headers": {"Authorization": f"Bearer {user_token}"}}
)
]
)
The agent just asks for tools the normal way, and the provider resolves them from the registry behind the scenes. Only the matched tools’ schemas load into context, and after the first call they’re cached.
Auth, and a heads-up on where it’s heading
Registry access runs through OAuth or IAM, same as the rest of AgentCore. For IDE-initiated MCP flows specifically, Dynamic Client Registration is the currently supported approach, but it’s worth knowing the MCP protocol spec is moving toward Client ID Metadata Documents as the long-term recommendation, with DCR set to become obsolete. If you’re building against DCR now, put a tenant access-control list and rate limiting in front of it and monitor the logs for unusual registration activity, since DCR endpoints are a known target for abuse. For machine-to-machine flows in production, static client registration is the recommended path either way.
Lessons from teams already running this in production
A few patterns are worth carrying over before you hit them the hard way. On security: automate the scanning step rather than relying on manual review, use act-on-behalf identity propagation so an agent’s actions trace back to a real user, and enforce fine-grained access through Gateway interceptors rather than registry permissions alone. On multi-tenancy: validate tenant isolation explicitly and treat any data leakage across tenants as non-negotiable, not a bug to fix later. On search performance: lean on semantic search over exact-match lookups, write tool descriptions that explain the problem the tool solves rather than just its name, and keep queries either short and specific or natural-language exploratory, not a mix of both in the same call.
Pricing and where to go next
The registry has a genuinely usable free tier:
• 5,000 records a month free, then $0.40 per 1,000
• 1,000,000 search API calls a month free, then $0.02 per 1,000
• 2,000,000 list and get calls a month free, then $0.004 per 1,000
For most teams starting out, that free tier covers early development entirely.
For the full API reference and code samples, AWS’s documentation and the agentcore-samples GitHub repository are the best starting points, alongside AWS’s own launch post on the registry.
What this means for ANZ platform teams
If your organisation already runs change-management or security review for anything going into production, the registry’s approval workflow should map onto that process rather than exist alongside it as a separate one. And because it’s still in preview, expect the auth model, particularly the DCR to CIMD transition, to keep shifting. Make sure registry audit events land in whatever logging or SIEM setup already covers the rest of your AWS estate, especially if you’re in a regulated sector where a security or compliance team will eventually ask who approved a given agent and why.
We help ANZ engineering teams design the registry structure, approval workflow, and discovery pattern before the first agent goes into production, rather than retrofitting governance after the third one ships. If you’re past the point of one agent and want a second set of eyes on the architecture, we’re happy to talk it through.
