/aws-agentic-ai

Agent Registry Service

Status: Preview (launched April 9, 2026)

Overview

AWS Agent Registry is a fully managed discovery service within Amazon Bedrock AgentCore. It provides a private, governed catalog for organizing, curating, and discovering AI agents, MCP servers, tools, agent skills, and custom resources across an organization.

Problem it solves: As organizations scale AI agents and tools, resources become siloed across teams. Teams build MCP servers, deploy agents, and create specialized tools, but without a central catalog, duplication of effort occurs because builders cannot discover what already exists.

Regional Availability

Core Concepts

Registries

Top-level catalogs in your AWS account. Each registry has its own:

• Name and description
• Authorization configuration (IAM or JWT) — cannot be changed after creation
• Approval settings (auto-approve or manual review)
• Set of registry records

Naming: Must start alphanumeric. Valid characters: a-z, A-Z, 0-9, _, -, ., /. Max 64 characters.

Organize registries by resource type, environment stage (prod/QA/dev), team, or use a single org-wide registry.

Registry Records

Metadata entries describing individual resources. Each record has:

• Name (max 255 chars) and description (max 4,096 chars)
• Version (semantic versioning recommended)
• Descriptor type (MCP, A2A, SKILL, CUSTOM)
• Type-specific metadata (protocol definitions, tool schemas, etc.)

Resource Types

Record Lifecycle

Create → DRAFT → Submit → PENDING_APPROVAL → Approve → APPROVED
                                │                         │
                                │ Reject                  │ Edit (new DRAFT revision;
                                ▼                         │ approved stays in search)
                           REJECTED ── Approve (direct) ──┘
                                │
                                └── Edit → DRAFT

Any status → DEPRECATED (terminal, irreversible)

• Draft: Initial state. Not visible in search.
• Pending Approval: Submitted for review. Not visible in search.
• Approved: Visible in search results. Editing creates a new DRAFT revision while the approved revision stays active.
• Rejected: Curator can directly approve, or publisher can edit (creates new DRAFT) and resubmit.
• Deprecated: Terminal state — cannot be undone or edited. Removed from search but visible via GetRegistryRecord and ListRegistryRecords for auditing.

Key Personas

Key Capabilities

Hybrid Search

Combines semantic (vector-based, natural language) search with keyword matching. Both run simultaneously on every query with results ranked by weighted combination.

Ranking: Name has strongest keyword influence, followed by description and descriptor content (equal weight).

Metadata filters constrain results using operators:

• $eq, $ne — Equals / not equals
• $in — In list
• $and, $or — Logical combinators

Filterable fields: name, descriptorType, version.

MCP-Native Access

Each registry exposes an MCP-compatible endpoint (MCP spec 2025-11-25):

https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp

The endpoint provides one tool: search_registry_records with parameters:

• searchQuery (required) — Natural language or keyword query (1-256 chars)
• maxResults (1-20, default 10) — Number of results to return
• filter (optional) — Metadata filter object

Any MCP-compatible client (Claude Code, Kiro, etc.) can connect directly.

See MCP Endpoint Guide for detailed configuration.

Governance and Curation

Configurable approval workflow with auto-approval or manual curator review.

See Governance Workflows for details.

Record Synchronization

Pull metadata from live external MCP servers or A2A agent endpoints via URL-based discovery. Supports OAuth and IAM credential providers for outbound authorization. Creates new revisions automatically when upstream changes.

See Sync Configuration for details.

EventBridge Notifications

Events sent to default EventBridge bus (source: aws.bedrock-agentcore) when:

• Records are submitted for approval (detail-type: "Registry Record State changed to Pending Approval")
• Registries finish provisioning (detail-type: "Registry State transitions from Creating to Ready")

Enables automated review pipelines via Lambda, SNS, SQS, or Step Functions.

CloudTrail Audit

All control plane API calls are logged as management events in CloudTrail.

API Reference

Control Plane CLI (bedrock-agentcore-control)

Registry Operations

Record Operations

Approval Operations

Data Plane CLI (bedrock-agentcore)

IAM Actions

Important: ALL IAM actions use the bedrock-agentcore: prefix — both control and data plane operations.

Control Plane:

Data Plane:

Note: MCP tool invocation requires BOTH InvokeRegistryMcp AND SearchRegistryRecords.

Resource ARN Formats:

• Registry: arn:aws:bedrock-agentcore:{region}:{account}:registry/{registryId}
• Record: arn:aws:bedrock-agentcore:{region}:{account}:registry/{registryId}/record/{recordId}

Common Operations

Create a Registry

aws bedrock-agentcore-control create-registry \
  --name "MyOrgRegistry" \
  --description "Central catalog for all AI agents and tools" \
  --region us-east-1

Register an MCP Server

aws bedrock-agentcore-control create-registry-record \
  --registry-id <REGISTRY_ID> \
  --name "WeatherServer" \
  --descriptor-type MCP \
  --descriptors '{
    "mcp": {
      "server": {"schemaVersion": "2025-12-11", "inlineContent": "{\"name\": \"weather-server\", \"description\": \"Weather data service\", \"version\": \"1.0.0\"}"},
      "tools": {"protocolVersion": "2024-11-05", "inlineContent": "{\"tools\": [{\"name\": \"get_forecast\", \"description\": \"Get weather forecast\", \"inputSchema\": {\"type\": \"object\", \"properties\": {\"city\": {\"type\": \"string\"}}}}]}"}
    }
  }' \
  --record-version "1.0" \
  --region us-east-1

Register an Agent (A2A)

aws bedrock-agentcore-control create-registry-record \
  --registry-id <REGISTRY_ID> \
  --name "CustomerSupportAgent" \
  --descriptor-type A2A \
  --descriptors '{
    "a2a": {
      "agentCard": {"schemaVersion": "0.3", "inlineContent": "{\"name\": \"customer-support\", \"description\": \"Handles customer inquiries\", \"version\": \"1.0.0\", \"protocolVersion\": \"0.3.0\", \"url\": \"https://api.example.com/a2a\", \"capabilities\": {}, \"defaultInputModes\": [\"text/plain\"], \"defaultOutputModes\": [\"text/plain\"], \"skills\": [{\"id\": \"order-lookup\", \"name\": \"Order Lookup\", \"description\": \"Look up order status\", \"tags\": [\"orders\"]}]}"}
    }
  }' \
  --record-version "1.0" \
  --region us-east-1

Search Records

aws bedrock-agentcore search-registry-records \
  --search-query "weather forecast" \
  --registry-ids "<REGISTRY_ARN>" \
  --region us-east-1

Search with Filters

aws bedrock-agentcore search-registry-records \
  --search-query "customer" \
  --registry-ids "<REGISTRY_ARN>" \
  --filter '{"$and": [{"descriptorType": {"$eq": "A2A"}}, {"version": {"$eq": "1.0"}}]}' \
  --region us-east-1

Delete a Record

aws bedrock-agentcore-control delete-registry-record \
  --registry-id <REGISTRY_ID> \
  --record-id <RECORD_ID> \
  --region us-east-1

Note: Delete all records before deleting a registry.

Authorization

IAM (SigV4)

Default authentication method. Works automatically with AWS CLI and SDKs.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:SearchRegistryRecords",
        "bedrock-agentcore:InvokeRegistryMcp"
      ],
      "Resource": "arn:aws:bedrock-agentcore:<region>:<account>:registry/<registryId>"
    }
  ]
}

JWT (OAuth 2.0)

Supports Amazon Cognito, Okta, Azure AD, or any OIDC-compatible provider. Configure during registry creation. Authorization type cannot be changed after creation.

aws bedrock-agentcore-control create-registry \
  --name "external-registry" \
  --authorizer-type CUSTOM_JWT \
  --authorizer-configuration '{
    "customJWTAuthorizer": {
      "discoveryUrl": "https://cognito-idp.us-east-1.amazonaws.com/<poolId>/.well-known/openid-configuration",
      "allowedClients": ["<appClientId>"]
    }
  }' \
  --region us-east-1

Constraint: At least one JWT field required: allowedAudiences, allowedClients, allowedScopes, or customClaims. If multiple configured, ALL are verified.

Best Practices

Registry Organization

• Single org-wide registry for small organizations with few teams
• Per-team registries for larger organizations with clear ownership boundaries
• Per-environment registries (dev/staging/prod) for strict deployment governance

Naming Conventions

• Use descriptive, unique names (e.g., payments-mcp-server-v2 not server1)
• Include team/domain prefix when using shared registries (e.g., platform/auth-agent)
• Use semantic versioning for record versions

Search Optimization

• Write detailed descriptions to improve semantic search relevance
• Use consistent descriptor types to enable effective filtering
• Include relevant keywords in record metadata

Security

• Use IAM for internal (AWS-to-AWS) access patterns
• Use JWT for external or cross-organization access
• Enable manual approval for production registries
• Audit all registry operations via CloudTrail

Troubleshooting

Documentation

Related Services

• Gateway Service: Deploy discovered MCP servers as Gateway targets
• Runtime Service: Execute discovered agents in serverless runtime
• Identity Service: Manage credentials for registry authorization
• Observability Service: Monitor registry usage and search patterns

References

• AWS Agent Registry Documentation
• Registry Concepts
• Supported Record Types
• Registry Search
• Registry MCP Endpoint
• IAM Permissions
• Record Lifecycle
• Record Synchronization