Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Strumenti del protocollo A2A

Il protocollo Agent2Agent (A2A) è uno standard di messaggistica aperto che consente agli agenti AI autonomi di comunicare e coordinare le attività in sistemi diversi.

In CX Agent Studio, gli strumenti del protocollo A2A consentono all'applicazione dell'agente di delegare attività ad agenti remoti esterni o consentono ad applicazioni e orchestratori esterni di richiamare gli agenti CX Agent Studio utilizzando messaggi standardizzati.

Come funziona A2A

Il protocollo A2A in CX Agent Studio funziona utilizzando un modello di delega.

Modello di delega

Nel modello di delega, l'agente CX Agent Studio che avvia la sessione funge da orchestratore principale e mantiene il controllo generale della sessione:

Proprietà della sessione:l'agente principale mantiene la sessione di conversazione dell'utente. Quando è necessaria una sottoattività specializzata, l'agente principale richiama l'agente remoto come strumento.
Flusso di controllo:l'agente remoto elabora la richiesta e restituisce dati di risposta strutturati. Il controllo torna immediatamente all'agente principale, che riassume o incorpora i risultati per l'utente finale.
Trasferimento del contesto:l'agente principale trasmette solo i parametri e il contesto conversazionale necessari per l'attività delegata.

Diagramma di sequenza della delega A2A

Comunicazione basata su testo

Tutta la comunicazione tra agenti nel protocollo A2A è basata su testo:

Se un utente finale interagisce con un agente principale tramite un canale vocale (ad esempio telefonia o WebRTC), la voce viene prima convertita in testo.
L'agente principale invia la trascrizione del testo e i parametri all'agente secondario remoto in un payload della richiesta HTTP.
I flussi audio grezzi e gli incorporamenti non vengono trasmessi tramite l'interfaccia di rete A2A.

Supporto della modalità

Il supporto della modalità (testo o voce) per il protocollo A2A dipende dalla direzione della comunicazione:

Agente remoto a CX Agent Studio:supporta solo la modalità di testo.
CX Agent Studio all'agente remoto:indipendente dalla modalità per CX Agent Studio, il che significa che la sessione di CX Agent Studio può utilizzare qualsiasi modalità supportata, ad esempio voce o testo, ma l'agente remoto riceve solo testo.

Fatturazione

Se sia la sessione principale che quella remota si trovano in CX Agent Studio e nello stesso progetto, ti verrà addebitata una sessione.

In caso contrario, per le sessioni principali e remote in più progetti o sistemi di terze parti, ti verranno addebitate 2 sessioni.

Autenticazione e controllo degli accessi

I requisiti di autenticazione dipendono dalla direzione della comunicazione e dal servizio di destinazione.

Direzione	Destinazione target	Meccanismo di autenticazione	Ruolo IAM richiesto	Descrizione
Inbound (esterno a CX Agent Studio)	Applicazione agente CX Agent Studio	Token di accesso OAuth 2.0	`roles/ces.client`	Obbligatorio per i chiamanti esterni per richiamare l'endpoint in entrata di CX Agent Studio.
In uscita (da CX Agent Studio a CX Agent Studio)	Agente CX Agent Studio in un altro progetto	Service agent	`roles/ces.client`	Concesso al service agent del progetto chiamante nel progetto di destinazione.
In uscita (da CX Agent Studio a Cloud Run)	Servizio Cloud Run	Token ID service agent	`roles/run.invoker`	Concesso al service agent del progetto chiamante sul servizio Cloud Run.
In uscita (da CX Agent Studio a Vertex AI)	Vertex AI Agent Engine	OAuth del service agent	`roles/aiplatform.user`	Concesso al service agent del progetto chiamante nel progetto di destinazione.
In uscita (da CX Agent Studio a terze parti)	Endpoint esterno (ad esempio ServiceNow o Salesforce)	Chiave API o OAuth	Gestito tramite Secret Manager	Credenziali memorizzate inserite durante l'esecuzione dello strumento.

Identità del service agent

Le richieste in uscita da CX Agent Studio utilizzano l'agente di servizio CX Agent Studio:

service-PROJECT_NUMBER@gcp-sa-ces.iam.gserviceaccount.com

Sostituisci PROJECT_NUMBER con il numero del tuo progetto Google Cloud .

Autenticazione in entrata

Quando un'applicazione esterna, un agente personalizzato o un orchestratore chiama CX Agent Studio, deve passare un token di accesso OAuth 2.0 valido emesso da Google nell'intestazione Authorization:

Test:genera un token di accesso temporaneo per il tuo account attivo:
```
gcloud auth print-access-token
```
Client programmatici:utilizza le Credenziali predefinite dell'applicazione (ADC):
```
gcloud auth application-default print-access-token
```
Produzione:utilizza un account di servizio Google dedicato con il ruolo roles/ces.client (Customer Engagement Suite Client).

Prerequisiti

Prima di configurare gli strumenti del protocollo A2A:

Abilita l'API Gemini Enterprise for Customer Experience (ces.googleapis.com) sul tuo progetto:
```
gcloud services enable ces.googleapis.com --project=PROJECT_ID
```
Assicurati che al principal chiamante o account di servizio sia stato concesso il ruolo Customer Engagement Suite Client (roles/ces.client).

Configurare uno strumento del protocollo A2A

Per connettere l'agente principale a un agente remoto esterno:

Apri la console CX Agent Studio.
Seleziona il progetto e apri l'applicazione dell'agente.
Nel generatore di agenti, fai clic sull'icona Strumenti.
Fai clic sul pulsante + (Aggiungi) per creare un nuovo strumento.
Seleziona la scheda dello strumento Protocollo A2A.
Configura la scheda dell'agente utilizzando il modulo UI o l'editor JSON.
Nel campo URL, inserisci l'URL dell'endpoint di base dell'agente remoto (ad esempio, https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID o l'URL del servizio Cloud Run). Non aggiungere /message:send all'URL; CX Agent Studio aggiunge automaticamente /message:send in fase di runtime.
Seleziona il tipo di autenticazione appropriato per l'endpoint.
Fai clic su Crea.

Esempio di scheda dell'agente

Il seguente JSON di esempio definisce una scheda agente per un agente meteo remoto:

{
  "name": "weather_agent",
  "description": "Agent capable of querying weather conditions and local time for given locations.",
  "version": "0.1.0",
  "supportedInterfaces": [
    {
      "url": "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0"
    }
  ],
  "skills": [
    {
      "id": "get_weather",
      "name": "get_weather",
      "description": "Retrieves weather conditions for a specified location.",
      "tags": [
        "weather",
        "forecast"
      ],
      "examples": [],
      "inputModes": [],
      "outputModes": []
    },
    {
      "id": "get_current_time",
      "name": "get_current_time",
      "description": "Retrieves current local time for a specified city or timezone.",
      "tags": [
        "time",
        "clock"
      ],
      "examples": [],
      "inputModes": [],
      "outputModes": []
    }
  ]
}

Aggiungere le indicazioni stradali

Indica all'agente principale quando delegare all'A2A. Ad esempio:

If the user asks for weather information or local time, use {@TOOL: weather_agent}.
Pass the city or location specified by the user.
If the tool returns an error, inform the user that weather details are temporarily unavailable.

Messaggistica in entrata

I sistemi esterni possono inviare messaggi direttamente a un'applicazione agente CX Agent Studio utilizzando l'endpoint di messaggistica A2A in entrata.

URL endpoint in entrata

Invia richieste POST HTTP al seguente endpoint:

https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID/message:send

Sostituisci quanto segue:

PROJECT_ID: l'ID progetto Google Cloud .
LOCATION: la regione che ospita l'applicazione agente (ad esempio us-central1).
APP_ID: l'identificatore univoco dell'applicazione agente CX Agent Studio.

Schema del payload della richiesta

La struttura del payload JSON per l'invio di un messaggio in entrata:

{
  "message": {
    "messageId": "msg-MY_UNIQUE_MESSAGE_UUID",
    "role": "ROLE_USER",
    "content": [
      {
        "text": "Hello! I would like help checking my account balance."
      }
    ],
    "metadata": {
      "gecx_a2a_agent_context": "MY_SERIALIZED_AGENT_CONTEXT_STRING"
    }
  }
}

Nota: in CX Agent Studio, il payload del messaggio utilizza il campo content per contenere le parti di testo del messaggio.

Esempio di richiesta con curl

Puoi testare la messaggistica in entrata utilizzando curl:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "messageId": "msg-'"$(uuidgen)"'",
      "role": "ROLE_USER",
      "content": [
        {
          "text": "Hello!"
        }
      ]
    }
  }' \
  "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID/message:send"

Gestione del contesto e dello stato

Il protocollo A2A utilizza il messaggio AgentContext per gestire le variabili e gli stati della sessione tra gli agenti. Il contesto viene passato nei metadati di SendMessageRequest utilizzando la chiave gecx_a2a_agent_context.

Mappatura delle variabili

Quando deleghi un'attività, puoi mappare le variabili tra l'agente principale e quello remoto:

Mappatura in uscita: RemoteAgentTool.input_variable_mapping calcola AgentContext.variables inviato all'agente remoto.
Mapping in entrata: RemoteAgentTool.output_variable_mapping aggiorna le variabili dell'agente principale quando l'agente remoto risponde.

Per le richieste in entrata (client esterno a CX Agent Studio), l'applicazione deserializza i metadati gecx_a2a_agent_context e scrive AgentContext.variables direttamente nella sessione corrente. Le variabili aggiornate vengono riscritte in AgentContext.variables quando si risponde al client.

Chiusura della sessione

L'agente principale monitora AgentContext.session_metadata.closed per determinare quando termina una sessione remota:

Le richieste in uscita impostano sempre closed su false. Se la risposta dell'agente remoto imposta closed su true, la connessione A2A viene terminata.
Per le risposte in entrata al client, l'app CX Agent Studio imposta closed su true se la sessione è terminata.

Modalità stateful

Le sessioni remote con le app CXAS sono sempre stateful. Le sessioni CXAS principali e remote condivideranno lo stesso ID sessione e le sessioni remote manterranno la cronologia della conversazione tra gli agenti principali e quelli remoti.

Per le sessioni remote con sistemi di terze parti, le sessioni remote saranno senza stato per impostazione predefinita e l'agente remoto riceverà ogni messaggio dall'agente principale come una nuova sessione (ovvero un nuovo ID contesto).

Puoi attivare il campo RemoteAgentTool.stateful_agent per memorizzare automaticamente nella cache e riutilizzare il primo ID contesto restituito dall'agente remoto.

Questo ID contesto memorizzato nella cache viene utilizzato per il resto della sessione a meno che l'agente remoto non risponda con AgentContext.session_metadata.closed == true. Se la sessione viene chiusa, la cache viene reimpostata e un nuovo ID contesto verrà memorizzato nella cache alla successiva chiamata allo strumento.

Esegui il deployment di un sub-agente remoto

Puoi eseguire il deployment di agenti remoti personalizzati sui servizi Google Cloud per fungere da subagenti per CX Agent Studio.

Esegui il deployment in Cloud Run

Per ospitare un agente creato con Agent Development Kit (ADK) su Cloud Run:

Crea un file Dockerfile nella directory del progetto dell'agente:

FROM python:3.11-slim

WORKDIR /app

COPY pyproject.toml requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
RUN pip install --no-cache-dir "google-adk[a2a]==1.32.0" "a2a-sdk[all]==0.3.26"

COPY . .

ENV PORT=8080
ENV PYTHONUNBUFFERED=1

EXPOSE 8080

CMD ["python", "-m", "app.a2a_rest_server"]

Esegui il deployment del container in Cloud Run:

gcloud run deploy my-adk-agent \
  --project=PROJECT_ID \
  --region=us-central1 \
  --source=. \
  --memory=4Gi \
  --no-cpu-throttling

Concedi il ruolo roles/run.invoker sul servizio Cloud Run all'agente di servizio CX Agent Studio del progetto chiamante.
Segui i passaggi descritti in Configurare uno strumento di protocollo A2A per collegare l'URL del servizio Cloud Run a CX Agent Studio.

Esegui il deployment su Vertex AI Agent Engine

Per eseguire il deployment di un agente ADK su Vertex AI Agent Engine:

Definisci le dipendenze in requirements.txt:

a2a-sdk==0.3.26
google-adk[a2a]>=1.15.0,<2.0.0

Esegui il deployment del motore utilizzando l'SDK Vertex AI:

import os
import sys
from google.protobuf import json_format
import vertexai
from vertexai.agent_engines import _agent_engines

sys.path.append("./")
from app.agent_runtime_app import agent_runtime

client = vertexai.Client(project="PROJECT_ID", location="us-central1")

ops = agent_runtime.register_operations()
class_methods_proto = _agent_engines._generate_class_methods_spec_or_raise(
    agent_engine=agent_runtime,
    operations=ops
)
class_methods_list = [
    json_format.MessageToDict(cm, preserving_proto_field_name=True)
    for cm in class_methods_proto
]

agent_config = {
    "entrypoint_module": "app.agent_runtime_app",
    "entrypoint_object": "agent_runtime",
    "source_packages": ["app", "requirements.txt"],
    "requirements_file": "requirements.txt",
    "class_methods": class_methods_list,
    "agent_framework": "google-adk",
    "env_vars": {
        "GOOGLE_CLOUD_LOCATION": "us-central1",
    },
    "min_instances": 1,
    "max_instances": 10,
    "resource_limits": {"cpu": "4", "memory": "8Gi"},
}

engine = client.agent_engines.create(config=agent_config)
print(f"Deployed Engine Resource Name: {engine.api_resource.name}")

Concedi il ruolo roles/aiplatform.user nel progetto di destinazione al service agent CX Agent Studio del progetto chiamante.
Segui i passaggi descritti in Configurare uno strumento del protocollo A2A per collegare l'endpoint di Agent Engine a CX Agent Studio.

Connettiti a endpoint di terze parti

CX Agent Studio può delegare attività a endpoint esterni di terze parti, come ServiceNow o Salesforce.

Quando configuri lo strumento nella console:

Segui i passaggi descritti in Configurare uno strumento del protocollo A2A.
Seleziona il metodo di autenticazione richiesto dall'endpoint di terze parti (ad esempio chiave API o OAuth).
Archivia le credenziali in modo sicuro utilizzando Secret Manager.