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>',
                ],
                'custom' => [
                    'data' => '<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',
            '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

Registry identifier that accepts either ARN or ID format

Result Syntax

[
    'nextToken' => '<string>',
    'registryRecords' => [
        [
            'createdAt' => <DateTime>,
            'description' => '<string>',
            'displayName' => '<string>',
            'name' => '<string>',
            'recordArn' => '<string>',
            'recordId' => '<string>',
            'recordType' => 'MCP|AGENT|CUSTOM|SKILL',
            '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>',
                ],
                'custom' => [
                    'data' => '<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',
            '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

Base mixin for A2A agent card descriptor content

Members
data
Type: string

Descriptor payload data

dataSchemaVersion
Type: string

Version of the descriptor type schema

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

AgentSkillsAdditionalData

Description

Additional data for an agent skills definition descriptor.

Members
skillMd
Type: AgentSkillsMdDescriptor structure

Base mixin for agent skills markdown descriptor content

AgentSkillsDefinitionDescriptor

Description

Base mixin for agent skills definition descriptor content

Members
additionalData
Type: AgentSkillsAdditionalData structure

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

data
Type: string

Descriptor payload data

dataSchemaVersion
Type: string

Version of the descriptor type schema

AgentSkillsMdDescriptor

Description

Base mixin for agent skills markdown descriptor content

Members
data
Type: string

Descriptor payload data

dataSchemaVersion
Type: string

Version of the descriptor type schema

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

Record identifier that accepts either ARN or ID format

registryId
Required: Yes
Type: string

Registry identifier that accepts either ARN or ID format

CustomDescriptor

Description

Custom descriptor for user-defined content

Members
data
Type: string

Descriptor payload data

DescriptorSource

Description

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

Members
fromUrl
Type: DescriptorSourceFromUrl structure

Base mixin for descriptor source from URL

DescriptorSourceFromUrl

Description

Base mixin for descriptor source from URL

Members
url
Required: Yes
Type: string

URL source for descriptor content

Descriptors

Description

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

Members
a2aAgentCard
Type: A2aAgentCardDescriptor structure

Base mixin for A2A agent card descriptor content

agentSkillsDefinition
Type: AgentSkillsDefinitionDescriptor structure

Base mixin for agent skills definition descriptor content

custom
Type: CustomDescriptor structure

Custom descriptor for user-defined content

mcpServer
Type: McpServerDescriptor structure

Base mixin for MCP server descriptor content

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)

Timestamp in ISO 8601 date-time format

description
Type: string

Description of the Resource

displayName
Type: string

Display name for a registry record

name
Required: Yes
Type: string

Registry Record name

recordArn
Required: Yes
Type: string

Registry Record Amazon Resource Name

recordId
Required: Yes
Type: string

Registry Record unique identifier - 12-character alphanumeric string

recordType
Required: Yes
Type: string

Record type enum for registry record classification

recordVersion
Required: Yes
Type: string

Version of the registry record

registryArn
Required: Yes
Type: string

Registry Amazon Resource Name

status
Required: Yes
Type: string

Registry record status

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

Timestamp in ISO 8601 date-time format

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

MCP tools descriptor containing tool definitions

McpServerDescriptor

Description

Base mixin for MCP server descriptor content

Members
additionalData
Type: McpServerAdditionalData structure

Additional data for an MCP server descriptor

data
Type: string

Descriptor payload data

dataSchemaVersion
Type: string

Version of the descriptor type schema

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

Descriptor payload data

dataSchemaVersion
Type: string

Version of the descriptor type schema

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)

Timestamp in ISO 8601 date-time format

description
Type: string

Description of the Resource

descriptors
Required: Yes
Type: Descriptors structure

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

displayName
Type: string

Display name for a registry record

name
Required: Yes
Type: string

Registry Record name

recordArn
Required: Yes
Type: string

Registry Record Amazon Resource Name

recordId
Required: Yes
Type: string

Registry Record unique identifier - 12-character alphanumeric string

recordType
Required: Yes
Type: string

Record type enum for registry record classification

recordVersion
Required: Yes
Type: string

Version of the registry record

registryArn
Required: Yes
Type: string

Registry Amazon Resource Name

status
Required: Yes
Type: string

Registry record status

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

Timestamp in ISO 8601 date-time format

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

Registry identifier that accepts either ARN or ID format

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.