Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

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 ejemplo de código, 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 de contenedores

Su servidor A2A debe implementarse como una aplicación en contenedores que cumpla con estas especificaciones:

Requisitos de ruta

/- PUBLICAR

Finalidad

Recibe los mensajes de la JSON-RPC versión 2.0 y los procesa a través de las capacidades de su agente. Transfiere completamente la carga útil de la InvokeAgentRuntime API con mensajes de 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 - OBTENER known/agent

Finalidad

Proporciona los metadatos de la tarjeta de agente para la detección de agentes y la publicidad de 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 su servidor A2A esté operativo y listo para atender las solicitudes

Formato de las respuestas

Devuelve un código de estado que indica el estado de su agente:

{
  "status": "Healthy"
}

statuses obligatorio y es uno de Healthy oHealthyBusy. Mientras el estado seaHealthyBusy, la sesión 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 del portador en los encabezados de las solicitudes:

Authorization: Bearer <oauth-token>
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <session-id>

Autenticación Sigv4

La autenticación AWS Sigv4 estándar también es compatible con el acceso programático.

Gestión de errores

Los servidores A2A devuelven los errores como respuestas de error estándar JSON-RPC 2.0. La siguiente tabla asigna cada excepción de tiempo de ejecución a su código de JSON-RPC error, código de estado HTTP y mensaje. Algunas excepciones comparten un código de JSON-RPC error pero devuelven mensajes diferentes, por lo que aparecen en filas independientes.

ConflictExceptiony RetryableConflictException ambos usan JSON-RPC un código de error -32054 (HTTP 409). Sus mensajes los distinguen. El servicio devuelve RetryableConflictException (Session operation in progress, please retry) cuando una segunda operación se dirige a una sesión que el servicio está aprovisionando o desactivando. Esta condición es transitoria y se puede volver a intentar. La persona que llama debe volver a intentarlo con un breve retraso exponencial, ya que los clientes A2A no lo reintentan automáticamente.

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 no autorizada 401 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}"