# Contratto di protocollo A2A
Il contratto di protocollo A2A definisce i requisiti per l'implementazione della comunicazione tra agenti in Amazon Bedrock Runtime. AgentCore Questo contratto specifica i requisiti tecnici, gli endpoint e i modelli di comunicazione che il server A2A deve implementare.
Per un esempio di codice, consulta [Distribuire i server A2A in Runtime](runtime-a2a.md). AgentCore
**Topics**
+ [Requisiti di implementazione del protocollo](#protocol-implementation-requirements)
+ [Requisiti del contenitore](#container-requirements)
+ [Requisiti del percorso](#path-requirements)
+ [Requisiti di autenticazione](#authentication-requirements)
+ [Gestione degli errori](#error-handling)
+ [Risposte di autenticazione OAuth](#a2a-oauth-authentication-responses)
## Requisiti di implementazione del protocollo
Il server A2A deve implementare questi requisiti di protocollo specifici:
+ **Trasporto**: [JSON-RPC 2.0](https://www.jsonrpc.org/specification) su HTTP: consente la comunicazione standardizzata da agente a agente
+ **Gestione della sessione: la** piattaforma aggiunge `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` automaticamente l'intestazione per l'isolamento della sessione
+ **Agent Discovery**: è necessario fornire Agent Card all'endpoint `/.well-known/agent-card.json`
## Requisiti del contenitore
Il server A2A deve essere distribuito come applicazione containerizzata che soddisfi queste specifiche:
+ **Ospite:** `0.0.0.0`
+ **Porta**: `9000` - Porta standard per la comunicazione con il server A2A (diversa dai protocolli HTTP e MCP)
+ **Piattaforma**: contenitore ARM64 - Necessario per la compatibilità con l'ambiente di AWS runtime Amazon Bedrock AgentCore
## Requisiti del percorso
### /- POSTA
#### Scopo
Riceve messaggi JSON-RPC 2.0 e li elabora tramite le funzionalità del vostro agente, trasmissione completa del payload [InvokeAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html)API con messaggi del protocollo A2A
#### Casi d’uso
L'endpoint root serve a diversi scopi chiave:
+ Agent-to-agent comunicazione e collaborazione
+ Multi-step flussi di lavoro degli agenti e delega delle attività
+ Real-time esperienze di conversazione tra agenti
+ invocazione degli strumenti e condivisione delle funzionalità
#### Formato della richiesta
I server A2A prevedono richieste in formato 2.0 JSON-RPC :
```
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 della risposta
I server A2A rispondono con risposte in formato JSON-RPC 2.0 contenenti attività e artefatti:
```
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"
}
]
}
]
}
}
```
### known/agent/.well- -card.json - OTTIENI
#### Scopo
Fornisce i metadati della Agent Card per l'individuazione e la pubblicità delle capacità degli agenti
#### Casi d’uso
L'endpoint Agent Card ha diversi scopi chiave:
+ Individuazione degli agenti in sistemi multiagente
+ Pubblicità di capacità e competenze
+ Specificazione dei requisiti di autenticazione
+ Configurazione degli endpoint del servizio
#### Formato della risposta
Restituisce i metadati JSON che descrivono l'identità e le funzionalità dell'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 - OTTIENI
#### Scopo
Verifica che il server A2A sia operativo e pronto a gestire le richieste
#### Formato della risposta
Restituisce un codice di stato che indica lo stato di salute dell'agente:
+ **Content-Type** : `application/json`
+ **Codice di stato HTTP**: `200` per codici di errore corretti e appropriati per stati non integri
```
{
"status": "Healthy"
}
```
`status`è obbligatorio ed è uno dei `Healthy` o`HealthyBusy`. Mentre lo stato è`HealthyBusy`, la sessione di runtime viene mantenuta attiva.
È possibile includere un `time_of_last_update` campo opzionale (un timestamp Unix in secondi) per segnalare quando è stata apportata l'`status`ultima modifica.
**avvertimento**
Non impostate l'ora corrente `time_of_last_update` a ogni ping. Un timestamp che avanza a ogni ping segnala un cambiamento continuo dello stato, che impedisce che il timeout della sessione inattiva si verifichi. Le sessioni quindi persistono fino a `MaxLifetime` esaurimento della quota di sessione. Se ometti il campo, la piattaforma tiene traccia delle modifiche allo stato da sola. Se utilizzi Bedrock AgentCore SDK, la risposta al ping viene gestita automaticamente.
## Requisiti di autenticazione
I server A2A supportano diversi meccanismi di autenticazione:
### Token OAuth 2.0 Bearer
Per l'autenticazione del client A2A, includi il token Bearer nelle intestazioni della richiesta:
```
Authorization: Bearer
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id:
```
### Autenticazione SigV4
L'autenticazione AWS SigV4 standard è supportata anche per l'accesso programmatico.
## Gestione degli errori
I server A2A restituiscono gli errori come risposte di errore standard JSON-RPC 2.0 con codici di stato HTTP 200 per mantenere la conformità del protocollo:
| JSON-RPC Codice di errore | Eccezione di runtime | Codice di errore HTTP | JSON-RPC Messaggio di errore |
| --- | --- | --- | --- |
| -32501 | ResourceNotFoundException | 404 | Risorsa non trovata - La risorsa richiesta non esiste |
| -32052 | ValidationException | 400 | Errore di convalida: dati di richiesta non validi |
| -32053 | ThrottlingException | 429 | Limite di velocità superato: troppe richieste |
| -32054 | ResourceConflictException | 409 | Conflitto di risorse: la risorsa esiste già |
| -32055 | RuntimeClientError | 424 | Errore del client di runtime: controlla i CloudWatch log per ulteriori informazioni |
Esempio di risposta all'errore:
```
{
"jsonrpc": "2.0",
"id": "req-001",
"error": {
"code": -32052,
"message": "Validation error - Invalid request data"
}
}
```
## Risposte di autenticazione OAuth
OAuth-configured gli agenti seguono gli standard di autenticazione [RFC 6749 (OAuth 2.0)](https://datatracker.ietf.org/doc/html/rfc6749). Quando manca l'autenticazione, il servizio restituisce una risposta 401 Unauthorized con un' WWW-Authenticate intestazione (secondo [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235)), che consente ai client di scoprire gli endpoint del server di autorizzazione tramite l'API. GetRuntimeProtectedResourceMetadata
### 401 Non autorizzato: autenticazione mancante
```
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}"
```
**Nota**
SigV4-configured gli agenti restituiscono HTTP 403 con un `ACCESS_DENIED` errore e non includono `WWW-Authenticate` le intestazioni.