Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Outils du protocole A2A

Le protocole Agent-to-Agent (A2A) est une norme de messagerie ouverte qui permet aux agents d'IA autonomes de communiquer et de coordonner des tâches dans des systèmes disparates.

Dans CX Agent Studio, les outils du protocole A2A permettent à votre application d'agent de déléguer des tâches à des agents distants externes, ou permettent à des applications et orchestrateurs externes d'appeler vos agents CX Agent Studio à l'aide de messages standardisés.

Fonctionnement d'A2A

Le protocole A2A dans CX Agent Studio fonctionne à l'aide d'un modèle de délégation.

Modèle de délégation

Dans le modèle de délégation, l'agent CX Agent Studio initiateur agit en tant qu'orchestrateur principal et conserve le contrôle global de la session :

Propriété de la session : l'agent principal conserve la session de conversation avec l'utilisateur. Lorsqu'une sous-tâche spécialisée est requise, l'agent principal appelle l'agent distant en tant qu'outil.
Flux de contrôle : l'agent distant traite la requête et renvoie des données de réponse structurées. Le contrôle est immédiatement renvoyé à l'agent principal, qui résume ou intègre les résultats pour l'utilisateur final.
Transfert de contexte : l'agent principal ne transmet que les paramètres et le contexte conversationnel nécessaires à la tâche déléguée.

Diagramme de séquence de délégation A2A

Communication textuelle

Toutes les communications entre agents dans le protocole A2A sont basées sur du texte :

Si un utilisateur final interagit avec un agent principal sur un canal vocal (comme la téléphonie ou WebRTC), la parole est d'abord convertie en texte.
L'agent principal envoie la transcription textuelle et les paramètres au sous-agent distant dans une charge utile de requête HTTP.
Les flux audio bruts et les embeddings ne sont pas transmis via l'interface réseau A2A.

Prise en charge des modalités

La prise en charge de la modalité (texte ou voix) pour le protocole A2A dépend du sens de la communication :

Agent à distance vers CX Agent Studio : ne prend en charge que la modalité texte.
CX Agent Studio vers agent à distance : CX Agent Studio est agnostique en termes de modalités, ce qui signifie que la session CX Agent Studio peut utiliser n'importe quelle modalité compatible, comme la voix ou le texte, mais l'agent à distance ne reçoit que du texte.

Facturation

Si les sessions principale et à distance se trouvent dans CX Agent Studio et dans le même projet, vous serez facturé pour une seule session.

Sinon, pour les sessions principales et à distance sur plusieurs projets ou systèmes tiers, deux sessions vous seront facturées.

Authentification et contrôle des accès

Les exigences d'authentification dépendent du sens de la communication et du service cible.

Direction	Destination cible	Mécanisme d'authentification	Rôle IAM requis	Description
Entrant (externe à CX Agent Studio)	Application d'agent CX Agent Studio	Jeton d'accès OAuth 2.0	`roles/ces.client`	Obligatoire pour que les appelants externes puissent appeler le point de terminaison entrant de CX Agent Studio.
Sortant (de CX Agent Studio à CX Agent Studio)	Agent CX Agent Studio dans un autre projet	Agent de service	`roles/ces.client`	Accordé à l'agent de service du projet appelant sur le projet cible.
Sortant (de CX Agent Studio vers Cloud Run)	Service Cloud Run	Jeton d'ID d'agent de service	`roles/run.invoker`	Accordée à l'agent de service du projet appelant sur le service Cloud Run.
Sortant (de CX Agent Studio vers Vertex AI)	Vertex AI Agent Engine	OAuth de l'agent de service	`roles/aiplatform.user`	Accordé à l'agent de service du projet appelant sur le projet cible.
Sortant (de CX Agent Studio vers un tiers)	Point de terminaison externe (tel que ServiceNow ou Salesforce)	Clé API ou OAuth	Géré à l'aide de Secret Manager	Identifiants stockés injectés lors de l'exécution de l'outil.

Identité de l'agent de service

Les requêtes sortantes de CX Agent Studio utilisent l'agent de service CX Agent Studio :

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

Remplacez PROJECT_NUMBER par le numéro de votre projet Google Cloud .

Authentification entrante

Lorsqu'une application externe, un agent personnalisé ou un orchestrateur appelle CX Agent Studio, il doit transmettre un jeton d'accès OAuth 2.0 valide émis par Google dans l'en-tête Authorization :

Test : générez un jeton d'accès temporaire pour votre compte actif :
```
gcloud auth print-access-token
```
Clients programmatiques : utilisez les identifiants par défaut de l'application (ADC) :
```
gcloud auth application-default print-access-token
```
Production : utilisez un compte de service Google dédié avec le rôle roles/ces.client (Customer Engagement Suite Client).

Prérequis

Avant de configurer les outils du protocole A2A :

Activez l'API Gemini Enterprise for Customer Experience (ces.googleapis.com) dans votre projet :
```
gcloud services enable ces.googleapis.com --project=PROJECT_ID
```
Assurez-vous que le compte principal ou le compte de service appelant dispose du rôle Customer Engagement Suite Client (roles/ces.client).

Configurer un outil de protocole A2A

Pour associer votre agent principal à un agent distant externe :

Ouvrez la console CX Agent Studio.
Sélectionnez votre projet et ouvrez l'application de votre agent.
Dans l'outil de création d'agents, cliquez sur l'icône Outils.
Cliquez sur le bouton + (Ajouter) pour créer un outil.
Sélectionnez la fiche outil Protocole A2A.
Configurez votre fiche d'agent à l'aide du formulaire d'UI ou de l'éditeur JSON.
Dans le champ URL, saisissez l'URL du point de terminaison de base de l'agent distant (par exemple, https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID ou l'URL de votre service Cloud Run). N'ajoutez pas /message:send à l'URL. CX Agent Studio ajoute automatiquement /message:send au moment de l'exécution.
Sélectionnez le type d'authentification approprié pour le point de terminaison.
Cliquez sur Créer.

Exemple de carte d'agent

L'exemple JSON suivant définit une carte d'agent pour un agent météo à distance :

{
  "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": []
    }
  ]
}

Ajouter des instructions de routage

Indiquez à votre agent principal quand déléguer une tâche à l'outil A2A. Exemple :

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.

Messagerie entrante

Les systèmes externes peuvent envoyer des messages directement à une application d'agent CX Agent Studio à l'aide du point de terminaison de messagerie A2A entrante.

URL du point de terminaison entrant

Envoyez des requêtes HTTP POST au point de terminaison suivant :

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

Remplacez les éléments suivants :

PROJECT_ID : ID de votre projet Google Cloud .
LOCATION : région hébergeant votre application d'agent (par exemple, us-central1).
APP_ID : identifiant unique de votre application d'agent CX Agent Studio.

Schéma de la charge utile de la requête

Structure de la charge utile JSON pour l'envoi d'un message entrant :

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

Remarque : Dans CX Agent Studio, la charge utile du message utilise le champ content pour contenir les parties du texte du message.

Exemple de requête utilisant curl

Vous pouvez tester la messagerie entrante à l'aide de 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"

Gestion du contexte et de l'état

Le protocole A2A utilise le message AgentContext pour gérer les variables et les états de session entre les agents. Le contexte est transmis dans les métadonnées de SendMessageRequest à l'aide de la clé gecx_a2a_agent_context.

Mappage de variables

Lorsque vous déléguez une tâche, vous pouvez mapper des variables entre les agents principal et distant :

Mappage sortant : RemoteAgentTool.input_variable_mapping calcule le AgentContext.variables envoyé à l'agent distant.
Mappage entrant : RemoteAgentTool.output_variable_mapping met à jour les variables de l'agent principal lorsque l'agent distant répond.

Pour les requêtes entrantes (client externe vers CX Agent Studio), l'application désérialise les métadonnées gecx_a2a_agent_context et écrit les AgentContext.variables directement dans la session en cours. Les variables mises à jour sont réécrites dans AgentContext.variables lors de la réponse au client.

Fermeture de la session

L'agent principal surveille AgentContext.session_metadata.closed pour déterminer quand une session à distance se termine :

Les requêtes sortantes définissent toujours closed sur false. Si la réponse de l'agent distant définit closed sur true, la connexion A2A est interrompue.
Pour les réponses entrantes renvoyées au client, l'application CX Agent Studio définit closed sur true si la session est terminée.

Mode avec état

Les sessions à distance avec les applications CXAS sont toujours avec état. Les sessions CXAS principales et à distance partageront le même ID de session, et les sessions à distance conserveront l'historique des conversations entre les agents principaux et à distance.

Pour les sessions à distance avec des systèmes tiers, les sessions à distance seront sans état par défaut et l'agent à distance recevra chaque message de l'agent principal en tant que nouvelle session (c'est-à-dire un nouvel ID de contexte).

Vous pouvez activer le champ RemoteAgentTool.stateful_agent pour mettre automatiquement en cache et réutiliser le premier ID de contexte renvoyé par l'agent distant.

Cet ID de contexte mis en cache est utilisé pour le reste de la session, sauf si l'agent distant répond avec AgentContext.session_metadata.closed == true. Si la session est fermée, le cache est réinitialisé et un nouvel ID de contexte sera mis en cache lors du prochain appel d'outil.

Déployer un sous-agent distant

Vous pouvez déployer des agents distants personnalisés sur les services Google Cloud pour qu'ils agissent en tant que sous-agents pour CX Agent Studio.

Déployer dans Cloud Run

Pour héberger un agent créé avec l'Agent Development Kit (ADK) sur Cloud Run :

Créez un fichier Dockerfile dans le répertoire de votre projet d'agent :

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

Déployez le conteneur dans Cloud Run :

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

Attribuez le rôle roles/run.invoker sur le service Cloud Run à l'agent de service CX Agent Studio de votre projet appelant.
Suivez les étapes de la section Configurer un outil de protocole A2A pour associer l'URL du service Cloud Run à CX Agent Studio.

Déployer un agent sur Vertex AI Agent Engine

Pour déployer un agent ADK sur Vertex AI Agent Engine :

Définissez vos dépendances dans requirements.txt :
```
a2a-sdk==0.3.26
google-adk[a2a]>=1.15.0,<2.0.0
```

Déployez le moteur à l'aide du 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}")

Attribuez le rôle roles/aiplatform.user dans le projet cible à l'agent de service CX Agent Studio de votre projet appelant.
Suivez les étapes décrites dans Configurer un outil de protocole A2A pour associer le point de terminaison Agent Engine à CX Agent Studio.

Se connecter à des points de terminaison tiers

CX Agent Studio peut déléguer des tâches à des points de terminaison tiers externes, tels que ServiceNow ou Salesforce.

Lorsque vous configurez l'outil dans la console :

Suivez les étapes décrites dans Configurer un outil de protocole A2A.
Sélectionnez la méthode d'authentification requise par le point de terminaison tiers (clé API ou OAuth, par exemple).
Stocker les identifiants de manière sécurisée à l'aide de Secret Manager

Comparaison des outils du protocole A2A et de l'agent en tant qu'outil

CX Agent Studio propose plusieurs méthodes pour coordonner les workflows multi-agents.

Fonctionnalité	Agent en tant qu'outil	Outil de protocole A2A
Scope (Portée)	Intra-application (agents au sein de la même application CX Agent Studio).	Entre applications (agents externes, services à distance ou plates-formes tierces).
Communication	Exécution directe en mémoire / interne.	Mise en réseau des requêtes HTTP à l'aide de la norme de messagerie A2A.
Cas d'utilisation	Réutilisation de sous-agents internes sans transfert de la session.	Appeler des agents ADK personnalisés sur Cloud Run, Vertex AI ou des API externes.
Protocole	Exécution d'outils internes à la plate-forme.	Charge utile JSON A2A standardisée sur REST.

Exécution d'outils LLM

En coulisses, les appels de protocole A2A fonctionnent via l'appel d'outil LLM standard :

Lorsqu'un outil A2A est attribué à un agent, la description de l'outil et les définitions de compétences sont fournies au modèle sous forme de déclarations de fonctions.
Lorsque le modèle décide de déléguer une sous-tâche, il génère un événement d'appel de fonction.
L'environnement d'exécution CX Agent Studio intercepte l'appel de fonction, traduit les paramètres en requête HTTP A2A et l'envoie au point de terminaison distant configuré.
La réponse renvoyée par l'agent distant est retransmise au modèle pour qu'il continue de générer la réponse à la conversation.

Pour en savoir plus sur la façon dont les agents sont encapsulés en tant qu'outils appelables, consultez l'implémentation ADK AgentTool sur GitHub.

Outils du protocole A2A Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Fonctionnement d'A2A

Modèle de délégation

Communication textuelle

Prise en charge des modalités

Facturation

Authentification et contrôle des accès

Identité de l'agent de service

Authentification entrante

Prérequis

Configurer un outil de protocole A2A

Exemple de carte d'agent

Ajouter des instructions de routage

Messagerie entrante

URL du point de terminaison entrant

Schéma de la charge utile de la requête

Exemple de requête utilisant curl

Gestion du contexte et de l'état

Mappage de variables

Fermeture de la session

Mode avec état

Déployer un sous-agent distant

Déployer dans Cloud Run

Déployer un agent sur Vertex AI Agent Engine

Se connecter à des points de terminaison tiers

Comparaison des outils du protocole A2A et de l'agent en tant qu'outil

Exécution d'outils LLM

Outils du protocole A2A