Catatan: Kumpulan dokumentasi ini ditujukan untuk edisi Standard, Plus, dan Frontline Gemini Enterprise. Untuk dokumentasi edisi Business, lihat Pusat Bantuan Gemini Enterprise - Edisi Business.

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

Memanggil agen menggunakan endpoint A2A registrinya

Agen Agent2Agent (A2A) di Agent Registry mengiklankan antarmuka protokol yang berisi URL endpoint dan binding protokol (seperti HTTP_JSON). Anda dapat menemukan URL agen di registry untuk memanggil metode A2A-nya dari orkestrator atau klien kustom.

Selayang pandang

Spesifikasi	Detail
Discovery API	`agentregistry.googleapis.com` (`v1`)
Host proxy pemanggilan	`LOCATION-discoveryengine.googleapis.com`
Binding protokol	`HTTP_JSON`
ID project URL	Google Cloud nomor project (bukan project ID)
Metode A2A yang didukung	`GET /v1/card`, `POST /v1/message:send`, `POST /v1/message:stream`
Skema pesan yang diperlukan	`message.role = "ROLE_USER"`, `content[].text`, unik `messageId`
Izin IAM yang diperlukan	`roles/agentregistry.viewer` (penemuan) dan `discoveryengine.assistants.assist` (pemanggilan)

Sebelum memulai

Aktifkan Agent Registry API (agentregistry.googleapis.com) dan Discovery Engine API (discoveryengine.googleapis.com) di project Anda Google Cloud .
Jika agen tidak dibuat langsung di aplikasi Gemini Enterprise Anda, impor agen dari Agent Registry dan berikan akses kepada pengguna akhir. Untuk mengetahui petunjuknya, lihat Mengimpor agen A2A dari Agent Registry.
Berikan izin IAM yang sesuai kepada akun utama pemanggil Anda:
- Untuk membaca registry: Agent Registry Viewer (roles/agentregistry.viewer).
- Untuk memanggil agen: Discovery Engine Editor (roles/discoveryengine.editor) atau peran kustom yang menyertakan discoveryengine.assistants.assist.
Jika Anda melakukan autentikasi menggunakan Kredensial Default Aplikasi (ADC), konfigurasi klien Anda untuk mengirim header project kuota: -H "X-Goog-User-Project: PROJECT_ID".
Secara opsional, instal library Agent Development Kit (ADK) jika Anda berencana untuk menggabungkan agen jarak jauh sebagai sub-agen terprogram: pip install "google-adk[a2a]>=1.29.0".

Langkah 1: Temukan agen dan endpoint A2A-nya

Untuk memanggil agen A2A, temukan terlebih dahulu url yang diiklankan di Agent Registry. Buat daftar agen di lokasi registry Anda (seperti us atau eu, yang diteruskan sebagai parameter jalur di host agentregistry.googleapis.com global):

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/agents?pageSize=100"

Anda juga dapat menelusuri agen berdasarkan awalan nama tampilan menggunakan Google Cloud CLI:

gcloud agent-registry agents search \
  --project=PROJECT_ID \
  --location=LOCATION \
  --search-string="displayName:My_Agent_*"

Di resource agen yang ditampilkan, periksa array protocols. Temukan entri dengan type sama dengan A2A_AGENT dan interfaces[].protocolBinding sama dengan HTTP_JSON. Ekstrak url yang sesuai:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/agents/AGENT_RESOURCE_ID",
  "displayName": "My Agent",
  "protocols": [
    {
      "type": "A2A_AGENT",
      "protocolVersion": "0.3.0",
      "interfaces": [
        {
          "url": "https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/ENGINE_ID/assistants/default_assistant/agents/AGENT_ID/a2a",
          "protocolBinding": "HTTP_JSON"
        }
      ]
    }
  ]
}

Lihat referensi REST API projects.locations.agents untuk skema resource agen lengkap.

Langkah 2: Ambil kartu agen

Kartu agen menyediakan metadata yang menjelaskan identitas, deskripsi, dan kemampuan input/output agen. Untuk mengambil kartu, kirim permintaan GET HTTP ke jalur /v1/card yang ditambahkan ke URL endpoint A2A agen:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"A2A_ENDPOINT_URL/v1/card"

Payload respons contoh:

{
  "name": "My Agent",
  "description": "What the agent does.",
  "url": "A2A_ENDPOINT_URL",
  "capabilities": {},
  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text"],
  "preferredTransport": "HTTP+JSON"
}

Langkah 3: Kirim pesan

Untuk mengirim kueri pengguna ke agen, buat permintaan POST ke /v1/message:send. Isi permintaan harus sesuai dengan skema pesan A2A, yang memerlukan role yang ditetapkan ke ROLE_USER, array content yang berisi bagian teks, dan messageId yang dibuat secara unik:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"A2A_ENDPOINT_URL/v1/message:send" \
  -d '{
    "message": {
      "role": "ROLE_USER",
      "content": [
        {
          "text": "What can you help me with?"
        }
      ],
      "messageId": "UNIQUE_UUID_STRING"
    }
  }'

Dalam payload respons, balasan agen ditampilkan dalam objek message:

{
  "message": {
    "contextId": "projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/ENGINE_ID/sessions/SESSION_ID",
    "role": "ROLE_AGENT",
    "content": [
      {
        "text": "I am an AI assistant..."
      }
    ]
  }
}

Gabungkan string teks di dalam content[].text untuk menampilkan respons lengkap. Untuk melanjutkan percakapan dalam sesi yang sama, simpan string contextId yang ditampilkan dan berikan sebagai message.contextId dalam permintaan berikutnya.

Lihat referensi API REST message:send A2A untuk skema payload pesan lengkap.

Streaming respons secara bertahap

Untuk output streaming, kirim permintaan POST dengan isi pesan yang identik ke /v1/message:stream:

curl -N -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"A2A_ENDPOINT_URL/v1/message:stream" \
  -d '{
    "message": {
      "role": "ROLE_USER",
      "content": [
        {
          "text": "Say hello."
        }
      ],
      "messageId": "UNIQUE_UUID_STRING"
    }
  }'

Endpoint menampilkan array JSON objek potongan yang di-streaming melalui HTTP. Tambahkan fragmen content[].text secara berurutan saat tiba. Potongan yang di-streaming juga berisi metadata.sessionInfo dan metadata.assistToken.

Lihat referensi REST API message:streamA2Auntuk spesifikasi payload streaming.

Memanggil endpoint A2A menggunakan Python

Skrip Python ini menyelesaikan endpoint A2A di Agent Registry dan mengirim pesan menggunakan permintaan HTTP mentah:

# Install dependencies: pip install google-auth requests
import uuid
import google.auth
from google.auth.transport.requests import AuthorizedSession

# TODO(developer): Replace placeholder values with your project ID and location.
project_id = "PROJECT_ID"
location = "LOCATION"          # Registry location (for example: "us" or "eu")
target_display_name = "My Agent"
query_text = "What can you help me with?"

# Initialize credentials and authorized session
creds, _ = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
session = AuthorizedSession(creds)

# Step 1: Resolve the A2A endpoint URL from the Agent Registry
registry_url = (
    f"https://agentregistry.googleapis.com/v1/"
    f"projects/{project_id}/locations/{location}/agents"
)
response = session.get(registry_url)
response.raise_for_status()
agents = response.json().get("agents", [])

def get_a2a_url(agent_resource):
    for proto in agent_resource.get("protocols") or []:
        if proto.get("type") == "A2A_AGENT":
            for iface in proto.get("interfaces", []):
                if iface.get("protocolBinding") == "HTTP_JSON":
                    return iface.get("url")
    return None

target_agent = next(
    (a for a in agents if a.get("displayName") == target_display_name),
    None
)
if not target_agent:
    raise SystemExit(f"Agent '{target_display_name}' not found in registry.")

endpoint_url = get_a2a_url(target_agent)
if not endpoint_url:
    raise SystemExit("Target agent does not publish an HTTP_JSON A2A endpoint.")

# Step 2: Fetch and verify the agent card
card_resp = session.get(f"{endpoint_url}/v1/card")
card_resp.raise_for_status()
card = card_resp.json()
print("Resolved Agent:", card.get("name"))

# Step 3: Send an A2A message
body = {
    "message": {
        "role": "ROLE_USER",
        "content": [{"text": query_text}],
        "messageId": str(uuid.uuid4()),
    }
}
send_resp = session.post(f"{endpoint_url}/v1/message:send", json=body)
send_resp.raise_for_status()

reply_message = send_resp.json().get("message", {})
full_reply_text = "".join(
    part.get("text", "") for part in reply_message.get("content", [])
)
print("Agent Reply:", full_reply_text)

Menyederhanakan orkestrasi menggunakan ADK

Agent Development Kit (ADK) menyelesaikan endpoint registry secara otomatis dan menggabungkan agen A2A jarak jauh sebagai sub-agen:

from google.adk.integrations.agent_registry import AgentRegistry

# Initialize registry client
registry = AgentRegistry(project_id="PROJECT_ID", location="LOCATION")

# Resolve remote A2A agent directly by resource name
remote_agent = registry.get_remote_a2a_agent(
    agent_name="agents/AGENT_RESOURCE_ID"
)

Catatan tambahan

Endpoint A2A memiliki perilaku berikut:

Penamaan jalur yang ketat: Hanya GET {url}/v1/card, POST {url}/v1/message:send, dan POST {url}/v1/message:stream yang didukung untuk binding HTTP+JSON.
Validasi skema yang ketat: Meneruskan "user" biasa sebagai peran akan menampilkan error 400 Bad Request HTTP. Anda harus meneruskan string enum "ROLE_USER". Demikian pula, teks pesan harus berada di dalam array content, bukan parts, dan messageId sangat diperlukan.
Error pemanggilan agen non-A2A: Jika agen tidak memiliki entri protokol A2A_AGENT di registry (seperti agen bawaan atau terkelola tertentu), memanggil getCard di URL proxy-nya akan menampilkan 501 UNIMPLEMENTED ("... is not supported yet"), dan memanggil message:send akan menampilkan 400 INVALID_ARGUMENT ("Unsupported agent").
Nomor project di URL: Registry menampilkan URL A2A yang berisi nomor project, bukan project ID. Jangan ubah string numerik ini saat membuat permintaan HTTP.

Pemecahan masalah

Gunakan tabel berikut untuk memecahkan masalah error endpoint A2A umum:

Gejala	Kemungkinan penyebab	Resolusi
HTTP 404 pada permintaan `getCard`	Menggunakan alias jalur yang salah (seperti `/v1:getCard` atau `/.well-known/agent-card.json`).	Kirim permintaan GET secara ketat ke `GET {url}/v1/card`.
*HTTP 400 "Unknown name 'parts'"***	Menggunakan format isi klien AI lama atau generatif.	Tempatkan string teks di dalam `content`, bukan `parts`.
HTTP 400 nilai enum tidak valid untuk `role`	Meneruskan `"user"` atau `"user_role"` huruf kecil.	Tetapkan `message.role` persis ke `"ROLE_USER"`.
*HTTP 501 "is not supported yet"***	Memanggil `getCard` pada agen yang tidak memublikasikan antarmuka A2A.	Periksa array `protocols` resource registry untuk mengonfirmasi dukungan `A2A_AGENT` sebelum memanggil.
*HTTP 400 "Unsupported agent"***	Memanggil `message:send` pada agen non-A2A.	Pilih agen yang definisi registry-nya menyertakan binding protokol `A2A_AGENT` aktif.
`HTTP 401` atau `HTTP 403 Permission Denied`	Cakupan OAuth tidak ada, peran IAM tidak ada, atau header project kuota tidak ada.	Periksa peran IAM pemanggil (`agentregistry.viewer` dan `assistants.assist`); verifikasi cakupan `cloud-platform`; teruskan `-H "X-Goog-User-Project: PROJECT_ID"` jika menggunakan ADC.