SDK for PHP V3

Client: Aws\AgentDiscovery\AgentDiscoveryClient
Service ID: agent-discovery
Version: 2022-07-26

This page describes the parameters and results for the operations of the Agent Discovery (2022-07-26), and shows how to use the Aws\AgentDiscovery\AgentDiscoveryClient object to call the described operations. This documentation is specific to the 2022-07-26 API version of the service.

Operation Summary

Each of the following operations can be created from a client using $client->getCommand('CommandName'), where "CommandName" is the name of one of the following operations. Note: a command is a value that encapsulates an operation and the parameters used to create an HTTP request.

You can also create and send a command immediately using the magic methods available on a client object: $client->commandName(/* parameters */). You can send the command asynchronously (returning a promise) by appending the word "Async" to the operation name: $client->commandNameAsync(/* parameters */).

SearchPublicRecords ( array $params = [] )
Search public agent records across the authoritative + crawler indexes.

Paginators

Paginators handle automatically iterating over paginated API results. Paginators are associated with specific API operations, and they accept the parameters that the corresponding API operation accepts. You can get a paginator from a client class using getPaginator($paginatorName, $operationParameters). This client supports the following paginators:

SearchPublicRecords

Operations

SearchPublicRecords

$result = $client->searchPublicRecords([/* ... */]);
$promise = $client->searchPublicRecordsAsync([/* ... */]);

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).

Parameter Syntax

$result = $client->searchPublicRecords([
    'filters' => [
    ],
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'searchQuery' => '<string>',
]);

Parameter Details

Members
filters
Type: document (null|bool|string|numeric) or an (array|associative array) whose members are all valid documents

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.

maxResults
Type: int

Max records per page. Default 20, max 100.

nextToken
Type: string

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

searchQuery
Type: string

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

Result Syntax

[
    'nextToken' => '<string>',
    'records' => [
        [
            'createdAt' => <DateTime>,
            'description' => '<string>',
            'descriptors' => [
                '<descriptorSlotKey>' => [
                    'additionalData' => [...], // RECURSIVE
                    'data' => '<string>',
                    'source' => [
                        'fromUrl' => [
                            'url' => '<string>',
                        ],
                    ],
                    'version' => '<string>',
                ],
                // ...
            ],
            'displayName' => '<string>',
            'domain' => '<string>',
            'identifier' => [
                'domain' => '<string>',
                'uri' => '<string>',
            ],
            'recordType' => 'AGENT|TOOL|SKILL|CUSTOM|GATEWAY|WEB_BOT',
            'recordVersion' => '<string>',
            'trustManifests' => [
                [
                    'contributor' => '<string>',
                    'provenance' => [
                        [
                            'relation' => 'publishedFrom|discoveredFrom|federatedFrom',
                            'sourceId' => '<string>',
                        ],
                        // ...
                    ],
                ],
                // ...
            ],
            'updatedAt' => <DateTime>,
        ],
        // ...
    ],
]

Result Details

Members
nextToken
Type: string

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

records
Required: Yes
Type: Array of PublicRecord structures

The records that match the search, most relevant first.

Errors

ThrottlingException:

Thrown when the caller exceeds a rate/burst limit (D-9). ARD's code for it is RATE_LIMIT_EXCEEDED.

ValidationException:

Thrown when a request fails input validation.

`errorCode` carries ARD's Appendix B code, `INVALID_ARGUMENT`, which ARD's OpenAPI makes a required member of every error body on the ARD surface. The Amazon-shaped and internal surfaces leave it unset.

InternalServerException:

Thrown on an internal defect — a bug or malformed state, not a failed dependency.

⚠️ Deliberately a **permanent** failure. Repeating a request that failed to serialize will fail identically, so treating a 500 as retryable would spin a poison message through redelivery forever instead of letting it reach a dead-letter queue. Dependency failures that *are* worth retrying use `ServiceUnavailableException` and its 503 instead.

Examples

Example 1: To search for agents by keyword

The following example searches public records for flight booking agents and returns the first match.

$result = $client->searchPublicRecords([
    'filters' => [
    ],
    'maxResults' => 1,
    'searchQuery' => 'book a flight',
]);

Result syntax:

[
    'nextToken' => 'MQ',
    'records' => [
        [
            'createdAt' => ,
            'description' => 'Searches and books flights for a traveler.',
            'descriptors' => [
                'a2aAgentCard' => [
                    'version' => '0.3.0',
                    'source' => [
                        'fromUrl' => [
                            'url' => 'https://example.com/.well-known/agent-card.json',
                        ],
                    ],
                ],
            ],
            'displayName' => 'Flight Booking Agent',
            'domain' => 'example.com',
            'identifier' => [
                'uri' => 'urn:air:example.com:flight-booking:agent',
            ],
            'recordType' => 'AGENT',
            'recordVersion' => '1.0.0',
            'trustManifests' => [
                [
                    'contributor' => 'did:web:agent-registry.global.api.aws',
                    'provenance' => [
                        [
                            'relation' => 'publishedFrom',
                            'sourceId' => 'urn:air:example.com:flight-booking:agent',
                        ],
                    ],
                ],
            ],
            'updatedAt' => ,
        ],
    ],
]

Shapes

DescriptorEntry

Description

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).

Members
additionalData
Type: Associative array of custom strings keys (descriptorSlotKey) to DescriptorEntry structures

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

data
Type: string

Inline descriptor content (JSON string).

source
Type: DescriptorSource structure

Reference to externally-hosted descriptor content.

version
Type: string

Descriptor type version.

DescriptorSource

Description

Reference to descriptor content hosted at a URL.

Members
fromUrl
Type: DescriptorSourceUrl structure

The URL that hosts the descriptor content.

DescriptorSourceUrl

Description

A URL that hosts descriptor content.

Members
url
Required: Yes
Type: string

The URL of the externally hosted descriptor content.

Identifier

Description

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

Members
domain
Type: string

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

uri
Type: string

Arbitrary resolvable URI (urn / url / did).

InternalServerException

Description

Thrown on an internal defect — a bug or malformed state, not a failed dependency.

⚠️ Deliberately a **permanent** failure. Repeating a request that failed to serialize will fail identically, so treating a 500 as retryable would spin a poison message through redelivery forever instead of letting it reach a dead-letter queue. Dependency failures that *are* worth retrying use `ServiceUnavailableException` and its 503 instead.

Members
errorCode
Type: string

ARD's Appendix B code on the ARD surface, INTERNAL_ERROR.

message
Type: string
Description

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

Members
relation
Required: Yes
Type: string

How the contributor got the record.

sourceId
Required: Yes
Type: 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.

PublicRecord

Description

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

Members
createdAt
Type: timestamp (string|DateTime or anything parsable by strtotime)

When the record was created.

description
Type: string

A description of the record.

descriptors
Type: Associative array of custom strings keys (descriptorSlotKey) to DescriptorEntry structures

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.

displayName
Required: Yes
Type: string

The record's display name.

domain
Type: string

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

identifier
Required: Yes
Type: Identifier structure

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

recordType
Required: Yes
Type: string

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

recordVersion
Type: 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.

trustManifests
Type: Array of TrustManifest structures

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.

updatedAt
Type: timestamp (string|DateTime or anything parsable by strtotime)

When the record was last updated.

SearchFilterExpression

Description

SearchPublicRecords' filters: an object of field → {operator: value}, or one $and/$or key holding an array of such objects. A document because a value is a string or an array depending on the operator.

Members

ThrottlingException

Description

Thrown when the caller exceeds a rate/burst limit (D-9). ARD's code for it is RATE_LIMIT_EXCEEDED.

Members
errorCode
Type: string

ARD's error classification (Appendix B). Values are ARD's, uppercase on the wire.

message
Type: string

TrustManifest

Description

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.

Members
contributor
Required: Yes
Type: string

Absolute URI of the contributor these claims are attributed to.

provenance
Type: Array of ProvenanceLink structures

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

ValidationException

Description

Thrown when a request fails input validation.

`errorCode` carries ARD's Appendix B code, `INVALID_ARGUMENT`, which ARD's OpenAPI makes a required member of every error body on the ARD surface. The Amazon-shaped and internal surfaces leave it unset.

Members
errorCode
Type: string

ARD's error classification (Appendix B). Values are ARD's, uppercase on the wire.

message
Type: string