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 de ejecución. AgentCore

Requisitos de implementación del protocolo

Su servidor A2A debe implementar estos requisitos de protocolo específicos:

Requisitos del contenedor

El servidor A2A debe implementarse como una aplicación contenerizada que cumpla estas especificaciones:

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 InvokeAgentRuntimeAPI con mensajes del protocolo A2A

Casos de uso

El punto final raíz cumple varios propósitos clave:

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:

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:

{
  "status": "Healthy"
}

statuses obligatorio y es uno de los Healthy siguientesHealthyBusy: Mientras el estado seaHealthyBusy, 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

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 <oauth-token>
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <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:

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). Cuando falta la autenticación, el servicio devuelve una respuesta 401 no autorizada con un WWW-Authenticate encabezado (según la RFC 7235), 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}"