Contrat protocolaire A2A

Le contrat de protocole A2A définit les exigences relatives à la mise en œuvre de la communication agent-agent dans Amazon Bedrock Runtime. AgentCore Ce contrat précise les exigences techniques, les points de terminaison et les modèles de communication que votre serveur A2A doit mettre en œuvre.

Pour un exemple de code, voir Déployer des serveurs A2A dans AgentCore Runtime.

Exigences de mise en œuvre du protocole

Votre serveur A2A doit implémenter ces exigences de protocole spécifiques :

Exigences relatives aux contenants

Votre serveur A2A doit être déployé en tant qu'application conteneurisée répondant aux spécifications suivantes :

Exigences relatives au chemin

/- PUBLIER

Objectif

Reçoit les messages JSON-RPC 2.0 et les traite grâce aux capacités de votre agent, transmission complète de la charge utile de l'InvokeAgentRuntimeAPI avec les messages du protocole A2A

Cas d’utilisation

Le point de terminaison racine répond à plusieurs objectifs principaux :

Format des demandes

Les serveurs A2A attendent des requêtes au format 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"
    }
  }
}

Format de la réponse

Les serveurs A2A répondent avec des réponses au format JSON-RPC 2.0 contenant des tâches et des artefacts :

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

Objectif

Fournit les métadonnées de la carte d'agent pour la découverte des agents et la publicité sur les capacités

Cas d’utilisation

Le point de terminaison Agent Card répond à plusieurs objectifs clés :

Format de la réponse

Renvoie des métadonnées JSON décrivant l'identité et les capacités de l'agent :

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 - OBTENIR

Objectif

Vérifie que votre serveur A2A est opérationnel et prêt à traiter les demandes

Format de la réponse

Renvoie un code de statut indiquant l'état de santé de votre agent :

{
  "status": "Healthy"
}

statusest obligatoire et est l'un Healthy des suivantsHealthyBusy. Tant que le statut est HealthyBusy défini, la session d'exécution est maintenue active.

Un time_of_last_update champ facultatif (un horodatage Unix en secondes) peut être inclus pour indiquer la date de la status dernière modification.

Exigences en matière d'authentification

Les serveurs A2A prennent en charge plusieurs mécanismes d'authentification :

Jetons porteurs OAuth 2.0

Pour l'authentification du client A2A, incluez le jeton Bearer dans les en-têtes de demande :

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

Authentification SigV4

L'authentification AWS SigV4 standard est également prise en charge pour l'accès programmatique.

Gestion des erreurs

Les serveurs A2A renvoient les erreurs sous forme de réponses d'erreur JSON-RPC 2.0 standard avec des codes d'état HTTP 200 pour garantir la conformité au protocole :

Exemple de réponse d'erreur :

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "error": {
    "code": -32052,
    "message": "Validation error - Invalid request data"
  }
}

Réponses d'authentification OAuth

OAuth-configured les agents respectent les normes d'authentification RFC 6749 (OAuth 2.0). Lorsque l'authentification est absente, le service renvoie une réponse 401 Unauthorized avec un WWW-Authenticate en-tête (conformément à la RFC 7235), permettant aux clients de découvrir les points de terminaison du serveur d'autorisation via l'API. GetRuntimeProtectedResourceMetadata

401 Non autorisé - Authentification manquante

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}"