Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Contratto di protocollo A2A

Il contratto di protocollo A2A definisce i requisiti per l'implementazione della comunicazione da agente a agente 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 esempio di codice, vedi Distribuire i server A2A in Runtime. AgentCore

Requisiti di implementazione del protocollo

Il tuo server A2A deve implementare questi requisiti di protocollo specifici:

Requisiti del contenitore

Il server A2A deve essere distribuito come applicazione containerizzata che soddisfi queste specifiche:

Requisiti del percorso

/- POSTA

Scopo

Riceve messaggi JSON-RPC 2.0 e li elabora tramite le funzionalità del vostro agente, trasmissione completa del payload dell'InvokeAgentRuntimeAPI con i messaggi del protocollo A2A

Casi d’uso

L'endpoint root serve a diversi scopi chiave:

Formato della richiesta

I server A2A JSON-RPC prevedono richieste in formato 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"
    }
  }
}

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

Scopo

Fornisce i metadati della scheda agente per la scoperta degli agenti e la pubblicità delle capacità

Casi d’uso

L'endpoint Agent Card serve a diversi scopi chiave:

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

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 del tuo agente:

{
  "status": "Healthy"
}

statusè obbligatorio ed è uno dei seguentiHealthy. 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 l'statusultima modifica.

Requisiti di autenticazione

I server A2A supportano diversi meccanismi di autenticazione:

Token al portatore OAuth 2.0

Per l'autenticazione del client A2A, includi il token Bearer nelle intestazioni delle richieste:

Authorization: Bearer <oauth-token>
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <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 2.0. JSON-RPC La tabella seguente associa ogni eccezione di runtime al relativo codice JSON-RPC di errore, codice di stato HTTP e messaggio. Alcune eccezioni condividono un codice JSON-RPC di errore ma restituiscono messaggi diversi, quindi sono elencate come righe separate.

ConflictExceptioned RetryableConflictException entrambi utilizzano JSON-RPC un codice di errore -32054 (HTTP 409). I loro messaggi li contraddistinguono. Il servizio restituisce RetryableConflictException (Session operation in progress, please retry) quando una seconda operazione è indirizzata a una sessione di cui il servizio sta eseguendo il provisioning o la disattivazione. Questa condizione è transitoria e riprovabile. Il chiamante deve riprovare con un breve backoff esponenziale, perché i client A2A non lo riprovano automaticamente.

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). Quando manca l'autenticazione, il servizio restituisce una risposta 401 Unauthorized con un' WWW-Authenticate intestazione (per RFC 7235), 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}"