Agent Discovery

2026/11/20 - Agent Discovery - 1 new api methods

Changes  Adds the SearchPublicRecords API, which searches public registry records for AI agents, tools, and skills that their publishers have made discoverable.

SearchPublicRecords (new) Link ¶

Search public agent records across the authoritative + crawler indexes. Hybrid keyword + neural ranking, merged and fused (weighted RRF), with filters, org governance policy, and descriptor-visibility enforcement applied server-side. Public, authenticated (D-1).

See also: AWS API Documentation

Request Syntax

client.search_public_records(
    searchQuery='string',
    filters={...}|[...]|123|123.4|'string'|True|None,
    maxResults=123,
    nextToken='string'
)
type searchQuery:

string

param searchQuery:

Free-text natural-language query (ARD text). Drives semantic + lexical ranking.

type filters:

:ref:`document<document>`

param filters:

Structured filter narrowing the results, in the grammar of Agent Registry's SearchDiscoverableRegistryRecords filters: $eq, $ne and $in on a field, with $and or $or over single-condition objects, never nested. Fields are identifier, domain, recordType, descriptorType, provenance and recordVersion, and identifier also takes $prefix. For example {"recordType": {"$eq": "AGENT"}} or {"$or": [{"recordType": {"$eq": "MCP"}}, {"domain": {"$eq": "acme.com"}}]}.

Limits, the same ones Agent Registry applies: at most 10 conditions, $in takes 1-25 values, values are strings of 1-512 characters, and {} is invalid. A document can't carry @length, so the service enforces these and answers a filter past them with a ValidationException, as Agent Registry does.

type maxResults:

integer

param maxResults:

Max records per page. Default 20, max 100.

type nextToken:

string

param nextToken:

Opaque composite-cursor pagination token (O-DM12).

rtype:

dict

returns:

Response Syntax

{
    'records': [
        {
            'identifier': {
                'domain': 'string',
                'uri': 'string'
            },
            'displayName': 'string',
            'description': 'string',
            'recordType': 'AGENT'|'TOOL'|'SKILL'|'CUSTOM'|'GATEWAY'|'WEB_BOT',
            'domain': 'string',
            'descriptors': {
                'string': {
                    'data': 'string',
                    'version': 'string',
                    'source': {
                        'fromUrl': {
                            'url': 'string'
                        }
                    },
                    'additionalData': {'... recursive ...'}
                }
            },
            'trustManifests': [
                {
                    'contributor': 'string',
                    'provenance': [
                        {
                            'relation': 'publishedFrom'|'discoveredFrom'|'federatedFrom',
                            'sourceId': 'string'
                        },
                    ]
                },
            ],
            'recordVersion': 'string',
            'createdAt': datetime(2015, 1, 1),
            'updatedAt': datetime(2015, 1, 1)
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) --

    • records (list) --

      The records that match the search, most relevant first.

      • (dict) --

        A public record returned by search. Only the record's public descriptors are included.

        • identifier (dict) --

          The resolvable identifier value. Discriminated union — exactly one member is set.

          • domain (string) --

            Verified domain (e.g. example.com).

          • uri (string) --

            Arbitrary resolvable URI (urn / url / did).

        • displayName (string) --

          The record's display name.

        • description (string) --

          A description of the record.

        • recordType (string) --

          The kind of resource the record describes, such as an agent, a tool, or a skill.

        • domain (string) --

          FQDN per RFC-1035/1123, case-insensitive, at least two labels.

        • descriptors (dict) --

          Every PUBLIC descriptor slot the record was published with, as published: each slot's source, inline data, version and nested additionalData, the custom slot included. Absent on a record discovered at a partner source; ARD serves the partner's cards.

          • (string) --

            • (dict) --

              A descriptor slot value (A2A card, MCP server card, skills definition, custom). Content is either inline ( data) or a reference ( source). additionalData carries nested sub-descriptors (e.g. mcpServer.tools, agentSkillsDefinition.skillMd).

              • data (string) --

                Inline descriptor content (JSON string).

              • version (string) --

                Descriptor type version.

              • source (dict) --

                Reference to externally-hosted descriptor content.

                • fromUrl (dict) --

                  The URL that hosts the descriptor content.

                  • url (string) --

                    The URL of the externally hosted descriptor content.

              • additionalData (dict) --

                Nested sub-descriptors keyed by slot name (e.g. tools, skillMd).

        • trustManifests (list) --

          Trust Manifests (AI Catalog Trust Manifest Object), today only the registry's own, contributor did:web:agent-registry.global.api.aws. Its one provenance link says how the registry got the record: relation is publishedFrom for a record its owner published and discoveredFrom for one the registry discovered at a partner source, with sourceId as ProvenanceLink.sourceId describes. The provenance filter takes the same values (see ProvenanceRelation). It's left off when the registry can't name the source: a federatedFrom record until the index carries the peer registry, a discovered record with no source, or a missing or unknown origin. The manifest is unsigned, so it attributes the claim to the registry and doesn't authenticate it.

          • (dict) --

            One contributor's trust metadata about a record (AI Catalog Trust Manifest Object), with only the members the registry sets. AI Catalog's other members ( subject, signature, trustSchema, attestations, extensions) are optional, so each can be added when something sets it.

            • contributor (string) --

              Absolute URI of the contributor these claims are attributed to.

            • provenance (list) --

              The record's lineage as the contributor states it: how the contributor got the record, and from which source.

              • (dict) --

                Lineage of a record (AI Catalog Provenance Link Object), with only its required members.

                • relation (string) --

                  How the contributor got the record.

                • sourceId (string) --

                  The source of the record. Not always a URI. On publishedFrom it's the value of the record's identifier union member, identifier.uri or identifier.domain, unchanged. On discoveredFrom it's the name the registry gave the partner source when it was configured for crawling, not a URL.

        • recordVersion (string) --

          The record's version string, set by its publisher. Left off when the record has none, for example a discovered record whose source carries no version.

        • createdAt (datetime) --

          When the record was created.

        • updatedAt (datetime) --

          When the record was last updated.

    • nextToken (string) --

      The token to pass in a later request to get the next page of results. Absent when there are no more results.