# Contrato de protocolo A2A
El contrato de protocolo A2A define los requisitos para implementar la comunicación entre agentes en Amazon Bedrock Runtime. AgentCore Este contrato especifica los requisitos técnicos, los puntos finales y los patrones de comunicación que debe implementar su servidor A2A.
Para ver un código de ejemplo, consulte [Implementación de servidores A2A en tiempo](runtime-a2a.md) de ejecución. AgentCore
**Topics**
+ [Requisitos de implementación del protocolo](#protocol-implementation-requirements)
+ [Requisitos del contenedor](#container-requirements)
+ [Requisitos de ruta](#path-requirements)
+ [Requisitos de autenticación](#authentication-requirements)
+ [Gestión de errores](#error-handling)
+ [Respuestas de autenticación de OAuth](#a2a-oauth-authentication-responses)
## Requisitos de implementación del protocolo
Su servidor A2A debe implementar estos requisitos de protocolo específicos:
+ **Transporte**: [JSON-RPC 2.0](https://www.jsonrpc.org/specification) a través de HTTP: permite una comunicación estandarizada de agente a agente
+ **Administración de sesiones: la** plataforma agrega automáticamente un `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` encabezado para aislar la sesión
+ **Detección de agentes**: se debe proporcionar la tarjeta de agente en el `/.well-known/agent-card.json` punto final
## Requisitos del contenedor
El servidor A2A debe implementarse como una aplicación contenerizada que cumpla estas especificaciones:
+ **Host**: `0.0.0.0`
+ **Puerto**: `9000` - Puerto estándar para la comunicación con el servidor A2A (diferente de los protocolos HTTP y MCP)
+ **Plataforma**: contenedor ARM64: necesario para la compatibilidad con el entorno de ejecución de AWS Amazon Bedrock AgentCore
## Requisitos de ruta
### /- PUBLICAR
#### Finalidad
Recibe mensajes JSON-RPC 2.0 y los procesa a través de las capacidades de su agente y completa la transferencia de la carga útil de la [InvokeAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html)API con mensajes del protocolo A2A
#### Casos de uso
El punto final raíz cumple varios propósitos clave:
+ Agent-to-agent comunicación y colaboración
+ Multi-step flujos de trabajo de agentes y delegación de tareas
+ Real-time experiencias conversacionales entre agentes
+ Invocación de herramientas e intercambio de capacidades
#### Formato de las solicitudes
Los servidores A2A esperan solicitudes con formato JSON-RPC 2.0:
```
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": "req-001",
"method": "message/send",
"params": {
"message": {
"role": "user",
"parts": [
{
"kind": "text",
"text": "Your message content here"
}
],
"messageId": "unique-message-id"
}
}
}
```
#### Formato de las respuestas
Los servidores A2A responden con respuestas con formato JSON-RPC 2.0 que contienen tareas y artefactos:
```
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": "req-001",
"result": {
"artifacts": [
{
"artifactId": "unique-artifact-id",
"name": "agent_response",
"parts": [
{
"kind": "text",
"text": "Agent response content"
}
]
}
]
}
}
```
### /.well- -card.json - GET known/agent
#### Finalidad
Proporciona metadatos de la tarjeta de agente para descubrir agentes y anunciar sus capacidades
#### Casos de uso
El punto final de la tarjeta de agente cumple varios propósitos clave:
+ Descubrimiento de agentes en sistemas con varios agentes
+ Anuncio de capacidades y habilidades
+ Especificación del requisito de autenticación
+ Configuración del punto final del servicio
#### Formato de las respuestas
Devuelve los metadatos de JSON que describen la identidad y las capacidades del agente:
```
Content-Type: application/json
{
"name": "Agent Name",
"description": "Agent description and purpose",
"version": "1.0.0",
"url": "https://bedrock-agentcore.region.amazonaws.com/runtimes/agent-arn/invocations/",
"protocolVersion": "0.3.0",
"preferredTransport": "JSONRPC",
"capabilities": {
"streaming": true
},
"defaultInputModes": ["text"],
"defaultOutputModes": ["text"],
"skills": [
{
"id": "skill-id",
"name": "Skill Name",
"description": "Skill description and capabilities",
"tags": []
}
]
}
```
### /ping - OBTENER
#### Finalidad
Verifica que el servidor A2A esté operativo y preparado para gestionar las solicitudes
#### Formato de las respuestas
Devuelve un código de estado que indica el estado de salud de su agente:
+ **Content-Type** : `application/json`
+ **Código de estado HTTP**: `200` para estados en buen estado, códigos de error apropiados para estados en mal estado
```
{
"status": "Healthy"
}
```
`status`es obligatorio y es uno de los `Healthy` siguientes`HealthyBusy`: Mientras el estado sea`HealthyBusy`, la sesión en tiempo de ejecución se mantiene activa.
Se puede incluir un `time_of_last_update` campo opcional (una marca de tiempo de Unix en segundos) para indicar cuándo se modificó por última vez. `status`
**aviso**
No establezca `time_of_last_update` la hora actual en cada ping. Una marca de tiempo que avanza en cada ping indica un cambio de estado continuo, lo que impide que se agote el tiempo de espera de la sesión inactiva. De este modo, las sesiones persisten hasta `MaxLifetime` agotar la cuota de sesión. Si omites este campo, la plataforma registra los cambios de estado por sí misma. Si utilizas el AgentCore SDK de Bedrock, la respuesta al ping se gestiona automáticamente.
## Requisitos de autenticación
Los servidores A2A admiten varios mecanismos de autenticación:
### Tokens portadores de OAuth 2.0
Para la autenticación de clientes A2A, incluye el token Bearer en los encabezados de las solicitudes:
```
Authorization: Bearer
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id:
```
### Autenticación SigV4
También se admite la autenticación AWS SigV4 estándar para el acceso programático.
## Gestión de errores
Los servidores A2A devuelven los errores como respuestas de error JSON-RPC 2.0 estándar con códigos de estado HTTP 200 para mantener el cumplimiento del protocolo:
| JSON-RPC Código de error | Excepción de ejecución | Código de error HTTP | JSON-RPC Mensaje de error |
| --- | --- | --- | --- |
| -32501 | ResourceNotFoundException | 404 | Recurso no encontrado: el recurso solicitado no existe |
| -32052 | ValidationException | 400 | Error de validación: datos de solicitud no válidos |
| -32053 | ThrottlingException | 429 | Se ha superado el límite de frecuencia: demasiadas solicitudes |
| -32054 | ResourceConflictException | 409 | Conflicto de recursos: el recurso ya existe |
| -32055 | RuntimeClientError | 424 | Error en el cliente en tiempo de ejecución: compruebe sus CloudWatch registros para obtener más información |
Ejemplo de respuesta de error:
```
{
"jsonrpc": "2.0",
"id": "req-001",
"error": {
"code": -32052,
"message": "Validation error - Invalid request data"
}
}
```
## Respuestas de autenticación de OAuth
OAuth-configured los agentes siguen los estándares de autenticación [RFC 6749 (OAuth 2.0)](https://datatracker.ietf.org/doc/html/rfc6749). Cuando falta la autenticación, el servicio devuelve una respuesta 401 no autorizada con un WWW-Authenticate encabezado (según la [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235)), lo que permite a los clientes descubrir los puntos finales del servidor de autorización a través de la API. GetRuntimeProtectedResourceMetadata
### 401 No autorizado: falta la autenticación
```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
```
**nota**
SigV4-configured los agentes devuelven el HTTP 403 con un `ACCESS_DENIED` error y no incluyen `WWW-Authenticate` encabezados.