Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Contrat de protocole 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 spécifie les exigences techniques, les points de terminaison et les modèles de communication que votre serveur A2A doit implémenter.

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 conteneurs

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

Exigences relatives au chemin

/- POSTE

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 par 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 - OBTENIR known/agent

Objectif

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

Cas d’utilisation

Le terminal de la carte d'agent répond à plusieurs objectifs principaux :

Format de la réponse

Renvoie des métadonnées JSON décrivant l'identité et les fonctionnalité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 d'état indiquant l'état de santé de votre agent :

{
  "status": "Healthy"
}

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

Un time_of_last_update champ facultatif (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 au porteur 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 par programmation.

Gestion des erreurs

Les serveurs A2A renvoient des erreurs sous forme de réponses d'erreur standard JSON-RPC 2.0. Le tableau suivant associe chaque exception d'exécution à son code JSON-RPC d'erreur, à son code d'état HTTP et à son message. Certaines exceptions partagent un code JSON-RPC d'erreur mais renvoient des messages différents. Elles sont donc répertoriées sur des lignes distinctes.

ConflictExceptionet RetryableConflictException les deux utilisent un code JSON-RPC d'erreur -32054 (HTTP 409). Leurs messages les distinguent. Le service renvoie RetryableConflictException (Session operation in progress, please retry) lorsqu'une deuxième opération cible une session que le service est en train de provisionner ou de supprimer. Cette condition est transitoire et peut être réessayée. L'appelant doit réessayer avec une courte période d'attente exponentielle, car les clients A2A ne réessayent pas automatiquement.

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 suivent les normes d'authentification RFC 6749 (OAuth 2.0). Lorsque l'authentification est manquante, 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}"