Memanggil agen menggunakan endpoint A2A registrinya

Agen Agent2Agent (A2A) di Agent Registry memberitahukan 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 orchestrator 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, messageId unik
Izin IAM yang diperlukan	roles/agentregistry.viewer (penemuan) dan discoveryengine.assistants.assist (pemanggilan)

Sebelum memulai

1. Aktifkan Agent Registry API (agentregistry.googleapis.com) dan Discovery Engine API (discoveryengine.googleapis.com) di project Google Cloud Anda.
2. Jika agen tidak dibuat langsung di aplikasi Gemini Enterprise Anda, impor agen dari Agent Registry dan beri pengguna akhir akses ke agen tersebut. Untuk mengetahui petunjuknya, lihat Mengimpor agen A2A dari Registry Agen.
3. 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 khusus yang mencakup discoveryengine.assistants.assist.
4. Jika Anda melakukan autentikasi menggunakan Kredensial Default Aplikasi (ADC), konfigurasikan klien Anda untuk mengirim header project kuota: -H "X-Goog-User-Project: PROJECT_ID".
5. Secara opsional, instal library Agent Development Kit (ADK) jika Anda berencana 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 url yang diiklankan terlebih dahulu di Agent Registry. Cantumkan 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 CLI Google Cloud :

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

Catatan: Jika grup perintah agent-registry tidak dikenali, jalankan gcloud components update untuk mengupdate distribusi CLI Anda.

Dalam resource agen yang ditampilkan, periksa array protocols. Temukan entri yang memiliki 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"
        }
      ]
    }
  ]
}

Penting: Gunakan string url yang ditampilkan secara verbatim. Untuk agen Gemini Enterprise, URL ini merutekan traffic melalui proxy A2A Discovery Engine dan menyematkan nomor project Google Cloud Anda, bukan project ID. Tidak semua agen terdaftar mengekspos antarmuka A2A; jika protocols kosong atau menghilangkan A2A_AGENT, agen tidak dapat dipanggil melalui A2A.

Lihat referensi REST API projects.locations.agents untuk mengetahui skema resource agen yang 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"

Contoh payload respons:

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

Catatan: Pastikan Anda meminta /v1/card. Variasi jalur alternatif (seperti /v1:getCard, /v1/getCard, atau /.well-known/agent-card.json) menampilkan error HTTP 404 Not Found pada binding protokol 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 mengharuskan role 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 REST API A2A message:send untuk mengetahui skema payload pesan lengkap.

Menampilkan 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 fragmen tersebut tiba. Bagian yang di-streaming juga berisi metadata.sessionInfo dan metadata.assistToken.

Lihat Referensi API REST message:stream A2A untuk mengetahui spesifikasi payload streaming.

Memanggil endpoint A2A menggunakan Python

Skrip Python ini me-resolve 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) otomatis me-resolve endpoint registry 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: Integrasi ini memerlukan google-adk[a2a]>=1.29.0. Untuk mengetahui detail selengkapnya, lihat Menyelesaikan endpoint dan membangun orchestrator.

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 ketat: Meneruskan "user" biasa sebagai peran akan menampilkan error HTTP 400 Bad Request. 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 mengubah string numerik ini saat membuat permintaan HTTP.

Pemecahan masalah

Gunakan tabel berikut untuk memecahkan masalah error endpoint A2A yang 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 hanya 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" dalam huruf kecil.	Tetapkan message.role ke "ROLE_USER".
HTTP 501 *"belum didukung"*	Memanggil getCard pada agen yang tidak memublikasikan antarmuka A2A.	Periksa array protocols resource registry untuk mengonfirmasi dukungan A2A_AGENT sebelum melakukan panggilan.
HTTP 400 *"Unsupported agent"*	Memanggil message:send pada agen non-A2A.	Pilih agen yang definisi registry-nya menyertakan binding protokol A2A_AGENT yang 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.

Referensi terkait

• Ringkasan Agent Registry
• Menelusuri agen dan alat di Registry Agen
• Menyelesaikan endpoint dan membangun orchestrator (ADK)
• Referensi API REST message:send A2A