# 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](runtime-a2a.md). AgentCore
**Topics**
+ [Anforderungen an die Implementierung von Protokollen](#protocol-implementation-requirements)
+ [Anforderungen an den Container](#container-requirements)
+ [Pfadanforderungen](#path-requirements)
+ [Anforderungen an die Authentifizierung](#authentication-requirements)
+ [Fehlerbehandlung](#error-handling)
+ [Antworten auf die OAuth-Authentifizierung](#a2a-oauth-authentication-responses)
## Anforderungen an die Implementierung von Protokollen
Ihr A2A-Server muss diese spezifischen Protokollanforderungen erfüllen:
+ **Transport**: [JSON-RPC 2.0](https://www.jsonrpc.org/specification) über HTTP — Ermöglicht eine standardisierte Agent-zu-Agent-Kommunikation
+ **Sitzungsverwaltung**: Die Plattform fügt automatisch einen `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` Header für die Sitzungsisolierung hinzu
+ **Agent Discovery**: Am `/.well-known/agent-card.json` Endpunkt muss die Agentenkarte bereitgestellt werden
## Anforderungen an den Container
Ihr A2A-Server muss als containerisierte Anwendung bereitgestellt werden, die die folgenden Spezifikationen erfüllt:
+ **Host:** `0.0.0.0`
+ **Port**: `9000` - Standardport für die A2A-Serverkommunikation (unterscheidet sich von den HTTP- und MCP-Protokollen)
+ **Plattform**: ARM64-Container — Für die Kompatibilität mit der AWS Amazon AgentCore Bedrock-Laufzeitumgebung erforderlich
## Pfadanforderungen
### /- BEITRAG
#### Zweck
Empfängt JSON-RPC 2.0-Nachrichten und verarbeitet sie mithilfe der Funktionen Ihres Agenten, vollständige Weiterleitung der [InvokeAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html)API-Payload mit A2A-Protokollnachrichten
#### Anwendungsfälle
Der Root-Endpunkt dient mehreren wichtigen Zwecken:
+ Agent-to-agent Kommunikation und Zusammenarbeit
+ Multi-step Arbeitsabläufe für Agenten und Delegierung von Aufgaben
+ Real-time Gesprächserfahrungen zwischen Agenten
+ Aufruf von Tools und gemeinsame Nutzung von Fähigkeiten
#### 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:
+ Agentenerkennung in Systemen mit mehreren Agenten
+ Werbung für Fähigkeiten und Fähigkeiten
+ Spezifikation der Authentifizierungsanforderungen
+ Konfiguration des Dienstendpunkts
#### 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:
+ **Content-Type** : `application/json`
+ **HTTP-Statuscode**: `200` für fehlerfreie Zustände, entsprechende Fehlercodes für fehlerhafte Zustände
```
{
"status": "Healthy"
}
```
`status`ist erforderlich und ist einer von `Healthy` oder`HealthyBusy`. Solange der Status lautet`HealthyBusy`, 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.
**Warnung**
Stellen Sie nicht `time_of_last_update` bei jedem Ping die aktuelle Uhrzeit ein. Ein Zeitstempel, der bei jedem Ping weitergeht, signalisiert eine kontinuierliche Statusänderung, wodurch verhindert wird, dass das Timeout für inaktive Sitzungen jemals ausgelöst wird. Die Sitzungen dauern dann an, bis Ihr Sitzungskontingent ausgeschöpft ist `MaxLifetime` und diese möglicherweise aufgebraucht sind. Wenn Sie das Feld weglassen, verfolgt die Plattform die Statusänderungen selbstständig. Wenn Sie das Bedrock AgentCore SDK verwenden, wird die Ping-Antwort für Sie abgewickelt.
## 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
X-Amzn-Bedrock-AgentCore-Runtime-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:
| JSON-RPC Fehlercode | Laufzeit-Ausnahme | HTTP-Fehlercode | JSON-RPC Fehlermeldung |
| --- | --- | --- | --- |
| -32501 | ResourceNotFoundException | 404 | Ressource nicht gefunden - Die angeforderte Ressource existiert nicht |
| -32052 | ValidationException | 400 | Validierungsfehler — Ungültige Anforderungsdaten |
| -32053 | ThrottlingException | 429 | Ratenlimit überschritten - Zu viele Anfragen |
| -32054 | ResourceConflictException | 409 | Ressourcenkonflikt — Die Ressource ist bereits vorhanden |
| -32055 | RuntimeClientError | 424 | Runtime-Client-Fehler — Weitere Informationen finden Sie in Ihren CloudWatch Protokollen |
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)](https://datatracker.ietf.org/doc/html/rfc6749). Fehlt die Authentifizierung, gibt der Dienst eine Antwort 401 Unauthorized mit einem WWW-Authenticate Header (gemäß [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235)) 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}"
```
**Anmerkung**
SigV4-configured Agenten geben HTTP 403 mit einem `ACCESS_DENIED` Fehler zurück und schließen keine `WWW-Authenticate` Header ein.