Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Alat A2A Protocol

Protokol Agent-to-Agent (A2A) adalah standar pesan terbuka yang memungkinkan agen AI otonom berkomunikasi dan mengoordinasikan tugas di berbagai sistem yang berbeda.

Di CX Agent Studio, alat A2A Protocol memungkinkan aplikasi agen Anda mendelegasikan tugas ke agen jarak jauh eksternal, atau memungkinkan aplikasi dan pengelola eksternal memanggil agen CX Agent Studio Anda menggunakan pesan standar.

Cara kerja A2A

Protokol A2A di CX Agent Studio beroperasi menggunakan model delegasi.

Model delegasi

Dalam model delegasi, agen CX Agent Studio yang memulai bertindak sebagai pengorkestrasi utama dan mempertahankan kontrol sesi secara keseluruhan:

Kepemilikan sesi: Agen utama mempertahankan sesi percakapan pengguna. Jika subtugas khusus diperlukan, agen utama akan memanggil agen jarak jauh sebagai alat.
Alur kontrol: Agen jarak jauh memproses permintaan dan menampilkan data respons terstruktur. Kontrol segera kembali ke agen utama, yang merangkum atau menggabungkan hasil untuk pengguna akhir.
Transfer konteks: Agen utama hanya mengirimkan parameter dan konteks percakapan yang diperlukan untuk tugas yang didelegasikan.

Diagram urutan delegasi A2A

Komunikasi berbasis teks

Semua komunikasi antar-agen dalam protokol A2A berbasis teks:

Jika pengguna akhir berinteraksi dengan agen utama melalui saluran suara (seperti telepon atau WebRTC), ucapan akan dikonversi terlebih dahulu menjadi teks.
Agen utama mengirimkan transkrip teks dan parameter ke sub-agen jarak jauh dalam payload permintaan HTTP.
Streaming dan penyematan audio mentah tidak ditransmisikan melalui antarmuka jaringan A2A.

Dukungan modalitas

Dukungan modalitas (teks versus suara) untuk protokol A2A bergantung pada arah komunikasi:

Agen jarak jauh ke CX Agent Studio: Hanya mendukung modalitas teks.
CX Agent Studio ke agen jarak jauh: Tidak bergantung pada modalitas untuk CX Agent Studio, artinya sesi CX Agent Studio dapat menggunakan modalitas yang didukung seperti suara atau teks, tetapi agen jarak jauh hanya menerima teks.

Penagihan

Jika sesi utama dan jarak jauh berada di CX Agent Studio dan berada dalam project yang sama, Anda akan ditagih untuk 1 sesi.

Jika tidak, untuk sesi utama dan jarak jauh di beberapa project atau sistem pihak ketiga, Anda akan ditagih untuk 2 sesi.

Autentikasi dan kontrol akses

Persyaratan autentikasi bergantung pada arah komunikasi dan layanan target.

Arah	Tujuan target	Mekanisme autentikasi	Peran IAM yang diperlukan	Deskripsi
Masuk (Eksternal ke CX Agent Studio)	Aplikasi agen CX Agent Studio	Token akses OAuth 2.0	`roles/ces.client`	Diperlukan agar penelepon eksternal dapat memanggil endpoint masuk CX Agent Studio.
Keluar (CX Agent Studio ke CX Agent Studio)	Agen CX Agent Studio di project lain	Agen layanan	`roles/ces.client`	Diberikan kepada agen layanan project panggilan di project target.
Keluar (CX Agent Studio ke Cloud Run)	Layanan Cloud Run	Token ID agen layanan	`roles/run.invoker`	Diberikan kepada agen layanan project yang memanggil di layanan Cloud Run.
Keluar (CX Agent Studio ke Vertex AI)	Vertex AI Agent Engine	OAuth agen layanan	`roles/aiplatform.user`	Diberikan kepada agen layanan project panggilan di project target.
Keluar (CX Agent Studio ke pihak ketiga)	Endpoint eksternal (seperti ServiceNow atau Salesforce)	Kunci API atau OAuth	Dikelola menggunakan Secret Manager	Kredensial tersimpan disuntikkan selama eksekusi alat.

Identitas agen layanan

Permintaan keluar dari CX Agent Studio menggunakan agen layanan CX Agent Studio:

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

Ganti PROJECT_NUMBER dengan nomor project Google Cloud Anda.

Autentikasi masuk

Saat aplikasi eksternal, agen kustom, atau pengelola alur kerja memanggil CX Agent Studio, aplikasi tersebut harus meneruskan token akses OAuth 2.0 yang valid yang dikeluarkan Google di header Authorization:

Pengujian: Buat token akses sementara untuk akun aktif Anda:
```
gcloud auth print-access-token
```
Klien terprogram: Menggunakan Kredensial Default Aplikasi (ADC):
```
gcloud auth application-default print-access-token
```
Produksi: Gunakan akun layanan Google khusus dengan peran roles/ces.client (Customer Engagement Suite Client).

Prasyarat

Sebelum mengonfigurasi alat A2A Protocol:

Aktifkan Gemini Enterprise for Customer Experience API (ces.googleapis.com) di project Anda:
```
gcloud services enable ces.googleapis.com --project=PROJECT_ID
```
Pastikan akun utama atau akun layanan pemanggil telah diberi peran Customer Engagement Suite Client (roles/ces.client).

Mengonfigurasi alat A2A Protocol

Untuk menghubungkan agen utama Anda ke agen jarak jauh eksternal:

Buka konsol CX Agent Studio.
Pilih project Anda dan buka aplikasi agen Anda.
Di pembuat agen, klik ikon Alat.
Klik tombol + (Tambahkan) untuk membuat alat baru.
Pilih kartu alat A2A Protocol.
Konfigurasi kartu agen Anda menggunakan Formulir UI atau editor JSON.
Di kolom URL, masukkan URL endpoint dasar agen jarak jauh (misalnya, https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID atau URL layanan Cloud Run Anda). Jangan menambahkan /message:send ke URL; CX Agent Studio akan otomatis menambahkan /message:send saat runtime.
Pilih jenis autentikasi yang sesuai untuk endpoint.
Klik Create.

Contoh kartu agen

JSON contoh berikut menentukan kartu agen untuk agen cuaca jarak jauh:

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

Menambahkan petunjuk perutean

Memberi tahu agen utama Anda kapan harus mendelegasikan ke alat A2A. Contoh:

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.

Pesan masuk

Sistem eksternal dapat mengirim pesan langsung ke aplikasi agen CX Agent Studio menggunakan endpoint pesan A2A masuk.

URL endpoint masuk

Kirim permintaan POST HTTP ke endpoint berikut:

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

Ganti kode berikut:

PROJECT_ID: Project ID Google Cloud Anda.
LOCATION: Region yang menghosting aplikasi agen Anda (seperti us-central1).
APP_ID: ID unik aplikasi agen CX Agent Studio Anda.

Skema payload permintaan

Struktur payload JSON untuk mengirim pesan masuk:

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

Catatan: Di CX Agent Studio, payload pesan menggunakan kolom content untuk berisi bagian teks pesan.

Contoh permintaan menggunakan curl

Anda dapat menguji pesan masuk menggunakan 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"

Pengelolaan konteks dan status

Protokol A2A menggunakan pesan AgentContext untuk mengelola variabel dan status sesi antar-agen. Konteks diteruskan dalam metadata SendMessageRequest menggunakan kunci gecx_a2a_agent_context.

Pemetaan variabel

Saat mendelegasikan tugas, Anda dapat memetakan variabel antara agen utama dan jarak jauh:

Pemetaan keluar: RemoteAgentTool.input_variable_mapping menghitung AgentContext.variables yang dikirim ke agen jarak jauh.
Pemetaan masuk: RemoteAgentTool.output_variable_mapping memperbarui variabel agen utama saat agen jarak jauh merespons.

Untuk permintaan masuk (klien eksternal ke CX Agent Studio), aplikasi akan mendeserialisasi metadata gecx_a2a_agent_context dan menulis AgentContext.variables langsung ke sesi saat ini. Variabel yang diperbarui ditulis kembali ke AgentContext.variables saat merespons klien.

Penutupan sesi

Agen utama memantau AgentContext.session_metadata.closed untuk menentukan kapan sesi jarak jauh berakhir:

Permintaan keluar selalu menetapkan closed ke false. Jika respons agen jarak jauh menetapkan closed ke true, koneksi A2A akan dihentikan.
Untuk respons masuk kembali ke klien, aplikasi CX Agent Studio menetapkan closed ke true jika sesi telah berakhir.

Mode stateful

Sesi jarak jauh dengan aplikasi CXAS selalu stateful. Sesi CXAS utama dan jarak jauh akan memiliki ID sesi yang sama dan sesi jarak jauh akan menyimpan histori percakapan antara agen utama dan jarak jauh.

Untuk sesi jarak jauh dengan sistem pihak ketiga, sesi jarak jauh akan bersifat stateless secara default dan agen jarak jauh akan menerima setiap pesan dari agen utama sebagai sesi baru (alias ID konteks baru).

Anda dapat mengaktifkan kolom RemoteAgentTool.stateful_agent untuk otomatis menyimpan dalam cache dan menggunakan kembali ID konteks pertama yang ditampilkan oleh agen jarak jauh.

ID konteks yang di-cache ini digunakan untuk sesi berikutnya kecuali jika agen jarak jauh merespons dengan AgentContext.session_metadata.closed == true. Jika sesi ditutup, cache akan direset dan ID konteks baru akan di-cache pada panggilan alat berikutnya.

Men-deploy sub-agen jarak jauh

Anda dapat men-deploy agen jarak jauh kustom di layanan Google Cloud untuk bertindak sebagai sub-agen untuk CX Agent Studio.

Men-deploy ke Cloud Run

Untuk menghosting agen yang dibangun dengan Agent Development Kit (ADK) di Cloud Run:

Buat Dockerfile di direktori project agen Anda:

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

Deploy container ke Cloud Run:

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

Berikan peran roles/run.invoker pada layanan Cloud Run kepada agen layanan CX Agent Studio project panggilan Anda.
Ikuti langkah-langkah di Mengonfigurasi alat Protokol A2A untuk melampirkan URL layanan Cloud Run ke CX Agent Studio.

Men-deploy ke Vertex AI Agent Engine

Untuk men-deploy agen ADK ke Vertex AI Agent Engine:

Tentukan dependensi Anda di requirements.txt:

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

Deploy mesin menggunakan Vertex AI SDK:

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

Berikan peran roles/aiplatform.user di project target kepada agen layanan CX Agent Studio project panggilan Anda.
Ikuti langkah-langkah di Mengonfigurasi alat A2A Protocol untuk melampirkan endpoint Agent Engine ke CX Agent Studio.

Menghubungkan ke endpoint pihak ketiga

CX Agent Studio dapat mendelegasikan tugas ke endpoint pihak ketiga eksternal, seperti ServiceNow atau Salesforce.

Saat mengonfigurasi alat di konsol:

Ikuti langkah-langkah di Mengonfigurasi alat Protokol A2A.
Pilih metode autentikasi yang diperlukan oleh endpoint pihak ketiga (seperti kunci API atau OAuth).
Simpan kredensial dengan aman menggunakan Secret Manager.

Alat Protokol A2A dibandingkan dengan Agen sebagai alat

CX Agent Studio menyediakan beberapa metode untuk mengoordinasikan alur kerja multi-agen.

Fitur	Agen sebagai alat	Alat A2A Protocol
Cakupan	Dalam aplikasi (agen dalam aplikasi CX Agent Studio yang sama).	Antar-aplikasi (agen eksternal, layanan jarak jauh, atau platform pihak ketiga).
Komunikasi	Eksekusi langsung dalam memori / internal.	Permintaan HTTP jaringan menggunakan standar pesan A2A.
Use cases	Menggunakan kembali sub-agen internal tanpa mengalihkan sesi.	Memanggil agen ADK kustom di Cloud Run, Vertex AI, atau API eksternal.
Protokol	Eksekusi alat internal platform.	Payload JSON A2A standar melalui REST.

Eksekusi alat LLM

Di balik layar, panggilan protokol A2A beroperasi melalui panggilan alat LLM standar:

Saat alat A2A ditetapkan ke agen, deskripsi alat dan definisi keterampilan diberikan ke model sebagai deklarasi fungsi.
Saat model memutuskan untuk mendelegasikan sub-tugas, model akan menghasilkan peristiwa panggilan fungsi.
Runtime CX Agent Studio mencegat panggilan fungsi, menerjemahkan parameter menjadi permintaan HTTP A2A, dan mengirimkannya ke endpoint jarak jauh yang dikonfigurasi.
Respons yang ditampilkan oleh agen jarak jauh diteruskan kembali ke model untuk melanjutkan pembuatan respons percakapan.

Untuk mempelajari lebih lanjut cara agen dienkapsulasi sebagai alat yang dapat dipanggil, lihat implementasi AgentTool ADK di GitHub.

Alat A2A Protocol Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Cara kerja A2A

Model delegasi

Komunikasi berbasis teks

Dukungan modalitas

Penagihan

Autentikasi dan kontrol akses

Identitas agen layanan

Autentikasi masuk

Prasyarat

Mengonfigurasi alat A2A Protocol

Contoh kartu agen

Menambahkan petunjuk perutean

Pesan masuk

URL endpoint masuk

Skema payload permintaan

Contoh permintaan menggunakan curl

Pengelolaan konteks dan status

Pemetaan variabel

Penutupan sesi

Mode stateful

Men-deploy sub-agen jarak jauh

Men-deploy ke Cloud Run

Men-deploy ke Vertex AI Agent Engine

Menghubungkan ke endpoint pihak ketiga

Alat Protokol A2A dibandingkan dengan Agen sebagai alat

Eksekusi alat LLM

Alat A2A Protocol