A2A-Protokollvertrag

Der A2A-Protokollvertrag definiert die Anforderungen für die Implementierung der Agent-zu-Agent-Kommunikation in Amazon Bedrock Runtime. AgentCore Dieser Vertrag legt die technischen Anforderungen, Endpunkte und Kommunikationsmuster fest, die Ihr A2A-Server implementieren muss.

Beispielcode finden Sie unter Bereitstellen von A2A-Servern in Runtime. AgentCore

Anforderungen an die Implementierung von Protokollen

Ihr A2A-Server muss diese spezifischen Protokollanforderungen erfüllen:

Anforderungen an den Container

Ihr A2A-Server muss als containerisierte Anwendung bereitgestellt werden, die die folgenden Spezifikationen erfüllt:

Pfadanforderungen

/- BEITRAG

Zweck

Empfängt JSON-RPC 2.0-Nachrichten und verarbeitet sie mithilfe der Funktionen Ihres Agenten, vollständige Weiterleitung der InvokeAgentRuntimeAPI-Payload mit A2A-Protokollnachrichten

Anwendungsfälle

Der Root-Endpunkt dient mehreren wichtigen Zwecken:

Anforderungsformat

A2A-Server erwarten Anfragen im JSON-RPC 2.0-Format:

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

Reaktionsformat

A2A-Server antworten mit Antworten im JSON-RPC 2.0-Format, die Aufgaben und Artefakte enthalten:

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 known/agent - GET

Zweck

Stellt Agentenkarten-Metadaten für die Agentenerkennung und die Ankündigung von Funktionen bereit

Anwendungsfälle

Der Agent Card-Endpunkt dient mehreren wichtigen Zwecken:

Reaktionsformat

Gibt JSON-Metadaten zurück, die die Identität und die Fähigkeiten des Agenten beschreiben:

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 — GET

Zweck

Überprüft, ob Ihr A2A-Server betriebsbereit und bereit ist, Anfragen zu bearbeiten

Reaktionsformat

Gibt einen Statuscode zurück, der den Zustand Ihres Agenten angibt:

{
  "status": "Healthy"
}

statusist erforderlich und ist einer von Healthy oderHealthyBusy. Solange der Status lautetHealthyBusy, wird die Runtime-Sitzung aktiv gehalten.

Ein optionales time_of_last_update Feld (ein Unix-Zeitstempel in Sekunden) kann hinzugefügt werden, um zu melden, wann die status letzte Änderung vorgenommen wurde.

Anforderungen an die Authentifizierung

A2A-Server unterstützen mehrere Authentifizierungsmechanismen:

OAuth 2.0-Trägertoken

Fügen Sie für die A2A-Clientauthentifizierung das Bearer-Token in die Anforderungsheader ein:

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

SigV4-Authentifizierung

Die standardmäßige AWS SigV4-Authentifizierung wird auch für den programmatischen Zugriff unterstützt.

Fehlerbehandlung

A2A-Server geben Fehler als JSON-RPC Standard-2.0-Fehlerantworten mit HTTP 200-Statuscodes zurück, um die Einhaltung der Protokolle zu gewährleisten:

Beispiel für eine Fehlerantwort:

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

Antworten auf die OAuth-Authentifizierung

OAuth-configured Agenten folgen den Authentifizierungsstandards RFC 6749 (OAuth 2.0). Fehlt die Authentifizierung, gibt der Dienst eine Antwort 401 Unauthorized mit einem WWW-Authenticate Header (gemäß RFC 7235) zurück, sodass Clients die Endpunkte des Autorisierungsservers über die API ermitteln können. GetRuntimeProtectedResourceMetadata

401 Nicht autorisiert — Fehlende Authentifizierung

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