SDK for PHP V3

Agent Registry 2025-12-01

Client: Aws\AgentRegistry\AgentRegistryClient
Service ID: agent-registry
Version: 2025-12-01

This page describes the parameters and results for the operations of the Agent Registry (2025-12-01), and shows how to use the Aws\AgentRegistry\AgentRegistryClient object to call the described operations. This documentation is specific to the 2025-12-01 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 */).

BatchGetDiscoverableRegistryRecord ( array $params = [] )
Retrieves multiple discoverable registry records by ID from a single registry.
ListDiscoverableRegistryRecords ( array $params = [] )
Lists the discoverable registry records in a registry.
SearchDiscoverableRegistryRecords ( array $params = [] )
Searches the discoverable registry records in a registry using a natural language query.

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:

ListDiscoverableRegistryRecords

Operations

BatchGetDiscoverableRegistryRecord 

$result = $client->batchGetDiscoverableRegistryRecord([/* ... */]);
$promise = $client->batchGetDiscoverableRegistryRecordAsync([/* ... */]);

Retrieves multiple discoverable registry records by ID from a single registry. Records that cannot be retrieved are reported individually in the errors list rather than failing the entire request.

Parameter Syntax

$result = $client->batchGetDiscoverableRegistryRecord([
    'entries' => [ // REQUIRED
        [
            'recordIds' => ['<string>', ...], // REQUIRED
            'registryId' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Members
entries
Required: Yes
Type: Array of RegistryRecordsEntry structures

The registry-scoped groups of record IDs to retrieve. Currently, you can specify exactly one entry.

Result Syntax

[
    'errors' => [
        [
            'errorCode' => 'RESOURCE_NOT_FOUND|ACCESS_DENIED|INTERNAL_ERROR',
            'message' => '<string>',
            'recordId' => '<string>',
            'registryId' => '<string>',
        ],
        // ...
    ],
    'registryRecords' => [
        [
            'createdAt' => <DateTime>,
            'description' => '<string>',
            'descriptors' => [
                'a2aAgentCard' => [
                    'data' => '<string>',
                    'dataSchemaVersion' => '<string>',
                    'source' => [
                        'fromUrl' => [
                            'url' => '<string>',
                        ],
                    ],
                ],
                'agentSkillsDefinition' => [
                    'additionalData' => [
                        'skillMd' => [
                            'data' => '<string>',
                            'dataSchemaVersion' => '<string>',
                            'source' => [
                                'fromUrl' => [
                                    'url' => '<string>',
                                ],
                            ],
                        ],
                    ],
                    'data' => '<string>',
                    'dataSchemaVersion' => '<string>',
                ],
                'agui' => [
                    'source' => [
                        'fromUrl' => [
                            'url' => '<string>',
                        ],
                    ],
                ],
                'custom' => [
                    'data' => '<string>',
                ],
                'http' => [
                    'source' => [
                        'fromUrl' => [
                            'url' => '<string>',
                        ],
                    ],
                ],
                'mcpServer' => [
                    'additionalData' => [
                        'tools' => [
                            'data' => '<string>',
                            'dataSchemaVersion' => '<string>',
                        ],
                    ],
                    'data' => '<string>',
                    'dataSchemaVersion' => '<string>',
                    'source' => [
                        'fromUrl' => [
                            'url' => '<string>',
                        ],
                    ],
                ],
            ],
            'displayName' => '<string>',
            'name' => '<string>',
            'recordArn' => '<string>',
            'recordId' => '<string>',
            'recordType' => 'MCP|AGENT|CUSTOM|SKILL|GATEWAY',
            'recordVersion' => '<string>',
            'registryArn' => '<string>',
            'status' => 'DRAFT|PENDING_APPROVAL|APPROVED|REJECTED|DEPRECATED|CREATING|UPDATING|CREATE_FAILED|UPDATE_FAILED',
            'updatedAt' => <DateTime>,
        ],
        // ...
    ],
]

Result Details

Members
errors
Required: Yes
Type: Array of BatchGetDiscoverableRegistryRecordError structures

The per-record errors for records that could not be retrieved. This list is empty when all requested records were returned.

registryRecords
Required: Yes
Type: Array of RegistryRecordSummary structures

The records that were successfully retrieved. Each record correlates to the request by its recordId.

Errors

InternalServerException:

The request failed due to an unexpected internal error; the caller may retry.

AccessDeniedException:

The caller is not authorized to perform the requested action.

ResourceNotFoundException:

The requested resource was not found.

ThrottlingException:

The request was denied due to request throttling; the caller may retry after a delay.

UnauthorizedException:

The request could not be authenticated.

ValidationException:

The request failed validation of one or more input fields.

ListDiscoverableRegistryRecords 

$result = $client->listDiscoverableRegistryRecords([/* ... */]);
$promise = $client->listDiscoverableRegistryRecordsAsync([/* ... */]);

Lists the discoverable registry records in a registry. You can optionally filter and paginate the results.

Parameter Syntax

$result = $client->listDiscoverableRegistryRecords([
    'filters' => [
        [
            'name' => 'recordType|descriptorType', // REQUIRED
            'values' => ['<string>', ...], // REQUIRED
        ],
        // ...
    ],
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'registryId' => '<string>', // REQUIRED
]);

Parameter Details

Members
filters
Type: Array of RegistryRecordFilter structures

The filters to apply to the discoverable registry record list.

maxResults
Type: int

The maximum number of records to return in a single page. Valid values are 1 through 100.

nextToken
Type: string

The pagination token returned by a previous request. Use this value to retrieve the next page of results.

registryId
Required: Yes
Type: string

The identifier of the registry whose discoverable records are listed. You can provide either the full Amazon Resource Name (ARN) or the registry ID.

Result Syntax

[
    'nextToken' => '<string>',
    'registryRecords' => [
        [
            'createdAt' => <DateTime>,
            'description' => '<string>',
            'descriptorTypes' => ['<string>', ...],
            'displayName' => '<string>',
            'name' => '<string>',
            'recordArn' => '<string>',
            'recordId' => '<string>',
            'recordType' => 'MCP|AGENT|CUSTOM|SKILL|GATEWAY',
            'recordVersion' => '<string>',
            'registryArn' => '<string>',
            'status' => 'DRAFT|PENDING_APPROVAL|APPROVED|REJECTED|DEPRECATED|CREATING|UPDATING|CREATE_FAILED|UPDATE_FAILED',
            'updatedAt' => <DateTime>,
        ],
        // ...
    ],
]

Result Details

Members
nextToken
Type: string

The pagination token to pass to a subsequent request to retrieve the next page of results. This field is absent when there are no more results.

registryRecords
Required: Yes
Type: Array of DiscoverableRegistryRecordSummary structures

The page of discoverable registry record summaries.

Errors

InternalServerException:

The request failed due to an unexpected internal error; the caller may retry.

AccessDeniedException:

The caller is not authorized to perform the requested action.

ResourceNotFoundException:

The requested resource was not found.

ThrottlingException:

The request was denied due to request throttling; the caller may retry after a delay.

UnauthorizedException:

The request could not be authenticated.

ValidationException:

The request failed validation of one or more input fields.

SearchDiscoverableRegistryRecords 

$result = $client->searchDiscoverableRegistryRecords([/* ... */]);
$promise = $client->searchDiscoverableRegistryRecordsAsync([/* ... */]);

Searches the discoverable registry records in a registry using a natural language query. Returns metadata for the matching records ordered by relevance.

Parameter Syntax

$result = $client->searchDiscoverableRegistryRecords([
    'filters' => [
    ],
    'maxResults' => <integer>,
    'registryIds' => ['<string>', ...], // REQUIRED
    'searchQuery' => '<string>', // REQUIRED
]);

Parameter Details

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

An optional structured JSON metadata filter that narrows the search results. Supports the field-level operators $eq, $ne, and $in, and the logical operators $and and $or on filterable fields.

maxResults
Type: int

The maximum number of results to return. Valid values are 1 through 20. The default value is 10.

registryIds
Required: Yes
Type: Array of strings

The registry identifiers to search within. Currently, you must specify exactly one registry identifier. You can provide either the full Amazon Web Services Resource Name (ARN) or the registry ID.

searchQuery
Required: Yes
Type: string

The natural language query to search for matching registry records.

Result Syntax

[
    'registryRecords' => [
        [
            'createdAt' => <DateTime>,
            'description' => '<string>',
            'descriptors' => [
                'a2aAgentCard' => [
                    'data' => '<string>',
                    'dataSchemaVersion' => '<string>',
                    'source' => [
                        'fromUrl' => [
                            'url' => '<string>',
                        ],
                    ],
                ],
                'agentSkillsDefinition' => [
                    'additionalData' => [
                        'skillMd' => [
                            'data' => '<string>',
                            'dataSchemaVersion' => '<string>',
                            'source' => [
                                'fromUrl' => [
                                    'url' => '<string>',
                                ],
                            ],
                        ],
                    ],
                    'data' => '<string>',
                    'dataSchemaVersion' => '<string>',
                ],
                'agui' => [
                    'source' => [
                        'fromUrl' => [
                            'url' => '<string>',
                        ],
                    ],
                ],
                'custom' => [
                    'data' => '<string>',
                ],
                'http' => [
                    'source' => [
                        'fromUrl' => [
                            'url' => '<string>',
                        ],
                    ],
                ],
                'mcpServer' => [
                    'additionalData' => [
                        'tools' => [
                            'data' => '<string>',
                            'dataSchemaVersion' => '<string>',
                        ],
                    ],
                    'data' => '<string>',
                    'dataSchemaVersion' => '<string>',
                    'source' => [
                        'fromUrl' => [
                            'url' => '<string>',
                        ],
                    ],
                ],
            ],
            'displayName' => '<string>',
            'name' => '<string>',
            'recordArn' => '<string>',
            'recordId' => '<string>',
            'recordType' => 'MCP|AGENT|CUSTOM|SKILL|GATEWAY',
            'recordVersion' => '<string>',
            'registryArn' => '<string>',
            'status' => 'DRAFT|PENDING_APPROVAL|APPROVED|REJECTED|DEPRECATED|CREATING|UPDATING|CREATE_FAILED|UPDATE_FAILED',
            'updatedAt' => <DateTime>,
        ],
        // ...
    ],
]

Result Details

Members
registryRecords
Required: Yes
Type: Array of RegistryRecordSummary structures

The registry records that match the search query, ordered by relevance.

Errors

InternalServerException:

The request failed due to an unexpected internal error; the caller may retry.

AccessDeniedException:

The caller is not authorized to perform the requested action.

ResourceNotFoundException:

The requested resource was not found.

ThrottlingException:

The request was denied due to request throttling; the caller may retry after a delay.

UnauthorizedException:

The request could not be authenticated.

ValidationException:

The request failed validation of one or more input fields.

Shapes

A2aAgentCardDescriptor

Description

Descriptor that defines the content of an A2A (Agent-to-Agent) agent card registry record. The content is validated against the A2A protocol schema.

Members
data
Type: string

The A2A agent card content, serialized as descriptor payload data.

dataSchemaVersion
Type: string

The schema version of the descriptor payload.

source
Type: DescriptorSource structure

The source location from which the A2A (Agent-to-Agent) agent card descriptor content was retrieved.

AccessDeniedException

Description

The caller is not authorized to perform the requested action.

Members
message
Type: string

AgUiDescriptor

Description

A descriptor for a registry record that exposes an AG-UI protocol endpoint. This descriptor is source-only: it identifies where the endpoint is located and carries no descriptor payload data or schema version.

Members
source
Type: DescriptorSource structure

The source location of the AG-UI protocol endpoint.

AgentSkillsAdditionalData

Description

Additional data for an agent skills definition descriptor.

Members
skillMd
Type: AgentSkillsMdDescriptor structure

The agent skills markdown descriptor associated with the agent skills definition.

AgentSkillsDefinitionDescriptor

Description

Descriptor that defines an agent skills registry record and its associated content.

Members
additionalData
Type: AgentSkillsAdditionalData structure

Additional data for the agent skills definition, such as the skills markdown descriptor.

data
Type: string

The agent skills definition content, serialized as descriptor payload data.

dataSchemaVersion
Type: string

The schema version of the descriptor payload.

AgentSkillsMdDescriptor

Description

Markdown-format descriptor containing an agent skills document.

Members
data
Type: string

The agent skills markdown content, serialized as descriptor payload data.

dataSchemaVersion
Type: string

The schema version of the descriptor payload.

source
Type: DescriptorSource structure

The source location from which the agent skills markdown content was retrieved.

BatchGetDiscoverableRegistryRecordError

Description

Describes why a requested record could not be retrieved.

Members
errorCode
Required: Yes
Type: string

The machine-readable reason that the record could not be retrieved.

message
Type: string

An optional human-readable detail about the error. Do not parse this value programmatically.

recordId
Required: Yes
Type: string

The identifier of the record that could not be retrieved, echoed from the request in the same format that you supplied (ARN or record ID).

registryId
Required: Yes
Type: string

The identifier of the registry the record was requested from, echoed from the request.

CustomDescriptor

Description

Custom descriptor for user-defined content

Members
data
Type: string

The custom descriptor content, serialized as descriptor payload data.

DescriptorSource

Description

The source location from which a descriptor's content was retrieved.

Members
fromUrl
Type: DescriptorSourceFromUrl structure

The URL-based descriptor source, populated when descriptor content is synchronized from a URL.

DescriptorSourceFromUrl

Description

A URL-based descriptor source that identifies where descriptor content is retrieved from.

Members
url
Required: Yes
Type: string

The URL from which the descriptor content is retrieved.

Descriptors

Description

The protocol-specific descriptors that describe how to connect to and use the registry record.

Members
a2aAgentCard
Type: A2aAgentCardDescriptor structure

The A2A agent card descriptor, populated when the record type is AGENT.

agentSkillsDefinition
Type: AgentSkillsDefinitionDescriptor structure

The agent skills definition descriptor, populated when the record type is SKILL.

agui
Type: AgUiDescriptor structure

The AG-UI descriptor, populated when the record exposes an AG-UI protocol endpoint.

custom
Type: CustomDescriptor structure

The custom descriptor, populated when the record type is CUSTOM.

http
Type: HttpDescriptor structure

The HTTP descriptor, populated when the record exposes an HTTP endpoint.

mcpServer
Type: McpServerDescriptor structure

The MCP server descriptor, populated when the record type is MCP.

DiscoverableRegistryRecordSummary

Description

Summary information about a discoverable registry record returned by ListDiscoverableRegistryRecords. This summary does not include descriptors.

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

The timestamp when the registry record was created.

description
Type: string

A human-readable description of the registry record. Use this field to explain the record's purpose or content to consumers discovering it in the registry.

descriptorTypes
Type: Array of strings

The descriptor types that are present on this registry record. Each value corresponds to a descriptor entry key on the approved record.

displayName
Type: string

The human-readable display name of the registry record.

name
Required: Yes
Type: string

The name of the registry record. Names are unique within a registry.

recordArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the registry record.

recordId
Required: Yes
Type: string

The unique identifier of the registry record.

recordType
Required: Yes
Type: string

The type of the registry record. MCP is a Model Context Protocol server record, AGENT is an Agent-to-Agent (A2A) agent card record, SKILL is an agent skills definition record, and CUSTOM is a record with a custom descriptor.

recordVersion
Required: Yes
Type: string

The version identifier of the registry record.

registryArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the parent registry that owns the record.

status
Required: Yes
Type: string

The lifecycle status of the registry record. A record is DRAFT before it is submitted, PENDING_APPROVAL while awaiting curator review, and APPROVED once it is approved and discoverable. REJECTED and DEPRECATED records are not discoverable. The CREATING, UPDATING, CREATE_FAILED, and UPDATE_FAILED values reflect the state of an in-progress or failed asynchronous change.

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

The timestamp when the registry record was last updated.

HttpDescriptor

Description

A descriptor for a registry record that exposes an HTTP endpoint. This descriptor is source-only: it identifies where the endpoint is located and carries no descriptor payload data or schema version.

Members
source
Type: DescriptorSource structure

The source location of the HTTP endpoint.

InternalServerException

Description

The request failed due to an unexpected internal error; the caller may retry.

Members
message
Type: string

McpServerAdditionalData

Description

Additional data for an MCP server descriptor

Members
tools
Type: McpToolsDescriptor structure

The MCP tools descriptor that defines the tools exposed by the MCP server.

McpServerDescriptor

Description

Descriptor that defines the content of an MCP (Model Context Protocol) server registry record, including the server definition and its tool definitions. The content is validated against the MCP protocol schema.

Members
additionalData
Type: McpServerAdditionalData structure

Additional data associated with the MCP server descriptor, such as tool definitions.

data
Type: string

The MCP server descriptor content, serialized as descriptor payload data.

dataSchemaVersion
Type: string

The schema version of the descriptor payload.

source
Type: DescriptorSource structure

The source location from which the MCP (Model Context Protocol) server descriptor content was retrieved.

McpToolsDescriptor

Description

MCP tools descriptor containing tool definitions

Members
data
Type: string

The MCP tools descriptor content, serialized as descriptor payload data.

dataSchemaVersion
Type: string

The schema version of the descriptor payload.

MetadataFilterExpression

Members

RegistryRecordFilter

Description

A single filter applied to a ListDiscoverableRegistryRecords request.

Members
name
Required: Yes
Type: string

The attribute to filter on.

values
Required: Yes
Type: Array of strings

The values to match for the attribute.

RegistryRecordSummary

Description

Summary information about a registry record, including its descriptors.

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

The timestamp when the registry record was created.

description
Type: string

A human-readable description of the registry record. Use this field to explain the record's purpose or content to consumers discovering it in the registry.

descriptors
Required: Yes
Type: Descriptors structure

The protocol-specific descriptors that describe how to connect to and use the record.

displayName
Type: string

The human-readable display name of the registry record.

name
Required: Yes
Type: string

The name of the registry record. Names are unique within a registry.

recordArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the registry record.

recordId
Required: Yes
Type: string

The unique identifier of the registry record.

recordType
Required: Yes
Type: string

The type of the registry record. MCP is a Model Context Protocol server record, AGENT is an Agent-to-Agent (A2A) agent card record, SKILL is an agent skills definition record, and CUSTOM is a record with a custom descriptor.

recordVersion
Required: Yes
Type: string

The version identifier of the registry record.

registryArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the parent registry that owns the record.

status
Required: Yes
Type: string

The lifecycle status of the registry record. A record is DRAFT before it is submitted, PENDING_APPROVAL while awaiting curator review, and APPROVED once it is approved and discoverable. REJECTED and DEPRECATED records are not discoverable. The CREATING, UPDATING, CREATE_FAILED, and UPDATE_FAILED values reflect the state of an in-progress or failed asynchronous change.

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

The timestamp when the registry record was last updated.

RegistryRecordsEntry

Description

Binds one registry to the record IDs requested from it.

Members
recordIds
Required: Yes
Type: Array of strings

The record IDs to retrieve from the registry. You can specify 1 through 100 record IDs.

registryId
Required: Yes
Type: string

The identifier of the registry to retrieve the records from. You can provide either the full Amazon Resource Name (ARN) or the registry ID.

ResourceNotFoundException

Description

The requested resource was not found.

Members
message
Type: string

ThrottlingException

Description

The request was denied due to request throttling; the caller may retry after a delay.

Members
message
Type: string

UnauthorizedException

Description

The request could not be authenticated.

Members
message
Type: string

ValidationException

Description

The request failed validation of one or more input fields.

Members
fieldList
Type: Array of ValidationExceptionField structures

The list of input fields that failed validation.

message
Required: Yes
Type: string
reason
Required: Yes
Type: string

The reason the request failed validation.

ValidationExceptionField

Description

Describes a single input field that failed validation.

Members
message
Required: Yes
Type: string

A description of why the field failed validation.

name
Required: Yes
Type: string

The name of the field that failed validation.