AWS has added custom metadata schemas to AWS Agent Registry, enabling organizations to define and enforce standardized key-value attributes across all records, including agents, Model Context Protocol (MCP) servers, and skills. The feature, announced on November 17, 2026, addresses the need for a unified vocabulary to govern, discover, and filter agentic resources within a registry.
Custom metadata schemas allow administrators to create a shared set of facts that every record in the registry must carry. This capability ensures that teams use consistent field names and values, which is critical for scaling governance, compliance, and discovery across an agentic fleet.
Enforcing Consistent Governance with Custom Schemas
Administrators define custom metadata schemas by specifying field names, data types, allowed values, and whether each field is required or optional. The registry supports four data types: Text, Enum, URL, and Boolean. Schemas can define attributes that apply to every record type, as well as dedicated fields specific to certain record types, such as networkEgress for MCP servers.
The schema acts as a centralized definition for an organization's resources. For example, a schema might standardize fields such as environment (with allowed values like prod, staging, dev), businessUnit, ownerTeam, supportContact, costCenter, and cmdbId. Security and compliance fields can include dataClassification, complianceScope (such as PCI or HIPAA), riskTier, scanStatus, and scanReportUrl.
By enforcing a common definition, the registry ensures that a field such as environment has the same name and allowed values regardless of which team publishes the record. This consistency allows consumers, agents, and governance tools to rely on a predictable structure when searching or evaluating resources.
Illustrative image: tookapic / Pixabay
Validation, Compliance, and Approval Workflows
When a record is created or updated, AWS Agent Registry validates the custom metadata against the active schema. The validation logic enforces strict compliance:
- Records created without any custom metadata are saved with a NON_COMPLIANT status. This allows teams to save work in progress, but the record cannot be submitted for approval until it includes all required fields and values.
- If a record includes custom metadata with an unknown field, a missing required field, or an invalid value, the registry rejects it with a
ValidationException. - The
GetRegistryRecordAPI returns the record's custom metadata values and its compliance status. A COMPLIANT status indicates that the values match the administrator's schema; it does not signify approval. Approval remains a separate decision made by approvers or automation.
The registry supports automated approval workflows triggered by record submissions. When a record moves to Pending approval, AWS Agent Registry emits an event to Amazon EventBridge. An EventBridge rule can invoke a custom AWS Lambda function to evaluate the record. The function reads the record's custom metadata and compliance status to perform checks. For example, an approval function might verify that the record is COMPLIANT, the scanStatus is PASSED, a cmdbId is present, and the dataClassification is within an allowed range. Records failing these checks are rejected with the reason for failure. Functions can also route records requiring human review, such as those with restricted data classifications.
Structured Discovery and Filtering
Custom metadata values are indexed to support precise discovery. The discovery APIs allow consumers to filter records based on custom attributes. A query can combine natural language with specific metadata filters, such as environment=prod AND businessUnit=payments AND securityScanStatus=PASSED. The registry returns only approved records that match the filters, excluding non-compliant or unapproved drafts.
Agents can access the registry via the MCP endpoint at https://agentregistry.<region>.api.aws/registry/<registryId>/mcp, which exposes search, list, and get tools. Agents can translate natural language requests into filtered searches using the defined metadata fields. For instance, an agent can query for "a production MCP server for payments ledger lookups that passed its security scan" and receive results based on the structured metadata.
Illustrative image: geralt / Pixabay
Schema Design Constraints and Evolution
Schema changes are strictly additive. Administrators can add new fields, add allowed values to existing enums, or change optional fields to required. However, schemas cannot be modified to rename fields, remove fields, or retype fields.
When a schema is updated, existing records are not rewritten. Records that no longer match the updated schema are reported as NON_COMPLIANT but retain their approval status. If a curator updates an approved record, the revision must meet the new schema requirements; otherwise, the submit fails until all required fields are populated. Until a curator approves the new revision, consumers continue to see the approved version.
The announcement advises treating the schema as a shared vocabulary. Organizations should settle field names and allowed values with the teams that publish and approve records before creating the schema. For fields populated by automation after registration, such as security scan results, the schema should allow interim values like PENDING. Sensitive details, including secrets and internal endpoints, should be excluded from broadly readable metadata.
Implementation Details and Availability
The feature is available in supported AWS Regions. Implementation requires an AWS account, AWS credentials, and IAM permissions for AWS Agent Registry. The sample implementation uses Python 3.11 or later and boto3 1.43.113 or later. The code utilizes the agent-registry-control and agent-registry boto3 clients. A sample repository demonstrating the workflow is available on GitHub.
"Treat the schema as your organization's shared vocabulary," the announcement advises, emphasizing the need to align field definitions with publishing and approving teams to ensure long-term usability.
Sources
PNEUMETRON EDITORIAL
Pneumetron's pipeline pairs AI-assisted drafting with human editorial review before publishing — our goal is to make staying informed easier, not to replace real reporting.




