Memanggil agen tertentu dengan StreamAssist API

Untuk memanggil agen terdaftar tertentu, berikan kolom agentsSpec opsional dalam permintaan streamAssist REST API atau panggilan library klien Anda. AgentsSpec API menentukan spesifikasi agen yang digunakan untuk menayangkan permintaan. Asisten mengarahkan kueri langsung ke agen tersebut dan mempertahankan konteks sesi di seluruh giliran.

Selayang pandang

Spesifikasi Detail
Metode API projects.locations.collections.engines.assistants.streamAssist
Versi endpoint v1alpha untuk menemukan ID agen; v1 untuk memanggil streamAssist
Parameter utama agentsSpec.agentSpecs[].agentId
Jenis agen yang didukung Agen chat Core Assistant, Deep Research, dan Agent Designer (sebelumnya low-code)
Izin IAM yang diperlukan discoveryengine.assistants.assist
Cakupan OAuth yang diperlukan https://www.googleapis.com/auth/cloud-platform

Sebelum memulai

  1. Aktifkan Discovery Engine API (discoveryengine.googleapis.com) di project Google Cloud Anda.
  2. Pastikan akun utama Anda (akun pengguna atau akun layanan) memiliki peran yang memberikan izin IAM discoveryengine.assistants.assist, seperti Discovery Engine Editor (roles/discoveryengine.editor) atau Gemini Enterprise Admin (roles/discoveryengine.agentspaceAdmin).
  3. Pastikan aplikasi Gemini Enterprise Anda (mesin) telah dibuat dan berisi setidaknya satu agen terdaftar.
  4. Jika Anda melakukan autentikasi menggunakan Kredensial Default Aplikasi (ADC), pastikan klien Anda mengirim header project kuota: -H "X-Goog-User-Project: PROJECT_ID".

Menemukan ID dan lokasi aplikasi Anda

URL streamAssist memerlukan ID mesin telusur dan lokasinya (global, us, atau eu). Jika Anda hanya mengetahui nama tampilan aplikasi, cantumkan mesin telusur di project Anda untuk menemukan ID yang mendasarinya:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines"

Dalam respons, format name mesin adalah projects/{project}/locations/{location}/collections/default_collection/engines/{ENGINE_ID}. Segmen ENGINE_ID adalah APP_ID yang diperlukan dalam panggilan.

Menemukan ID agen

agentId adalah segmen terakhir dari nama resource lengkap agen di Discovery Engine API:

projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/assistants/{assistant}/agents/{AGENT_ID}

Agen terdaftar menggunakan ID numerik panjang (misalnya, 15492003793394502655), bukan nama tampilan yang mudah diingat. Berikan hanya string numerik {AGENT_ID} akhir ini dalam permintaan Anda.

Untuk mencantumkan agen yang terdaftar ke aplikasi Anda dan menemukan ID numeriknya, panggil koleksi agents di endpoint v1alpha:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents"

Setiap resource agen yang ditampilkan mencakup kolom berikut:

  • name: Jalur resource lengkap yang diakhiri dengan {AGENT_ID}.
  • displayName: Nama yang dapat dibaca manusia yang ditampilkan di konsol Google Cloud .
  • state: Status operasional (seperti ENABLED atau PRIVATE).
  • Objek definisi yang menunjukkan jenis agen (seperti a2aAgentDefinition atau lowCodeAgentDefinition).

Lihat referensi REST API agents untuk skema resource agen lengkap.

Mengirim kueri ke agen

Untuk mengirim kueri ke agen tertentu, Anda harus membuat permintaan dengan agentsSpec yang sesuai dan mengeksekusinya menggunakan REST atau library klien.

Struktur isi permintaan

Untuk mengarahkan kueri ke agen tertentu, sertakan objek agentsSpec opsional dalam isi permintaan POST Anda:

{
  "query": {
    "text": "QUERY_TEXT"
  },
  "session": "SESSION_RESOURCE_NAME",
  "agentsSpec": {
    "agentSpecs": [
      {
        "agentId": "AGENT_ID"
      }
    ]
  }
}

Referensi kolom

  • agentsSpec (objek, opsional): Spesifikasi agen yang digunakan untuk menayangkan permintaan.
  • agentsSpec.agentSpecs[] (array, opsional): Daftar spesifikasi agen. Anda dapat menentukan beberapa agen dalam array ini.
  • agentsSpec.agentSpecs[].agentId (string, wajib dalam spesifikasi): ID yang mengidentifikasi resource agen terdaftar. Harus sesuai dengan RFC-1034 dengan panjang maksimum 63 karakter.

Lihat referensi REST API streamAssist untuk skema permintaan lengkap.

Memanggil streamAssist

REST

Perintah curl berikut mengirim kueri ke agen tertentu menggunakan REST API:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant:streamAssist" \
  -d '{
    "query": {
      "text": "List all contact cards."
    },
    "agentsSpec": {
      "agentSpecs": [
        {
          "agentId": "AGENT_ID"
        }
      ]
    }
  }'

Ganti placeholder berikut:

  • LOCATION: Multi-region untuk nama host dan jalur resource (global, us, atau eu). Jika aplikasi Anda berada di lokasi global, hapus awalan lokasi dari nama host (discoveryengine.googleapis.com).
  • PROJECT_ID: Project ID Google Cloud Anda.
  • APP_ID: ID mesin Gemini Enterprise Anda (ditemukan di Menemukan ID dan lokasi aplikasi Anda).
  • AGENT_ID: ID agen numerik (ditemukan di Menemukan ID agen).

Python

Contoh Python ini memanggil streamAssist menggunakan library klien google-cloud-discoveryengine:

# Install library: pip install google-cloud-discoveryengine
from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Replace placeholder values with your project and agent details.
project_id = "PROJECT_ID"
location = "LOCATION"          # For example: "us", "eu", or "global"
engine_id = "APP_ID"
agent_id = "AGENT_ID"          # The numeric agent ID
query_text = "List all contact cards."

client_options = (
    ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
    if location != "global"
    else None
)
client = discoveryengine.AssistantServiceClient(client_options=client_options)

assistant_path = client.assistant_path(
    project=project_id,
    location=location,
    collection="default_collection",
    engine=engine_id,
    assistant="default_assistant",
)

request = discoveryengine.StreamAssistRequest(
    name=assistant_path,
    query=discoveryengine.Query(text=query_text),
    agents_spec=discoveryengine.StreamAssistRequest.AgentsSpec(
        agent_specs=[
            discoveryengine.StreamAssistRequest.AgentsSpec.AgentSpec(
                agent_id=agent_id,
            )
        ]
    ),
)

for response in client.stream_assist(request=request):
    for reply in response.answer.replies:
        # Filter out model reasoning fragments (thought: true)
        if hasattr(reply, "grounded_content") and reply.grounded_content.content:
            print(reply.grounded_content.content.text, end="", flush=True)

print()

Memahami respons streaming

Endpoint streamAssist menampilkan aliran potongan JSON melalui REST, atau iterator objek respons di library klien:

  • Teks jawaban: Teks respons inkremental tiba di answer.replies[].groundedContent.content.text. Gabungkan fragmen teks ini dalam urutan tanda terima untuk merekonstruksi jawaban lengkap.
  • Fragmen penalaran: Fragmen yang ditandai dengan "thought": true merepresentasikan proses penalaran internal model. Memfilter fragmen ini saat menampilkan output akhir kepada pengguna akhir.
  • Status eksekusi: Kolom answer.state berkembang dari IN_PROGRESS ke status akhir:
    • SUCCEEDED: Permintaan selesai dan menghasilkan jawaban.
    • SKIPPED: Kueri diabaikan atau dilewati. Periksa assistSkippedReasons untuk mengetahui detailnya (seperti NON_ASSIST_SEEKING_QUERY_IGNORED untuk sapaan singkat).
    • FAILED: Pemanggilan mengalami error eksekusi.
  • Kelanjutan sesi: Chunk terminal mencakup sessionInfo.session (nama resource sesi) dan assistToken.

Melanjutkan percakapan dalam sesi yang sama

Untuk mempertahankan konteks di seluruh giliran, teruskan string session dari sessionInfo dalam permintaan berikutnya:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant:streamAssist" \
  -d '{
    "session": "projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/sessions/SESSION_ID",
    "query": {
      "text": "Who is John Doe?"
    },
    "agentsSpec": {
      "agentSpecs": [
        {
          "agentId": "AGENT_ID"
        }
      ]
    }
  }'

Jika Anda menghilangkan kolom session atau menentukan - sebagai ID sesi, API akan membuat sesi baru yang terisolasi secara otomatis.

Batasan

Batasan berikut berlaku saat memanggil agen dengan streamAssist:

  • Jenis agen yang tidak didukung:
    • Agen alur kerja tidak didukung.
    • Agen A2A atau ADK yang terdaftar ke aplikasi Gemini Enterprise tidak didukung melalui streamAssist. Untuk memanggil agen A2A secara langsung menggunakan endpoint registrinya, lihat Memanggil agen menggunakan endpoint A2A registrinya.
  • Tindakan mutatif: API streamAssist dioptimalkan untuk kueri percakapan dan pengambilan hanya baca melalui konektor. Eksekusi alat dan tindakan mutatif secara terprogram (seperti penulisan draf email, pembuatan acara kalender, atau pengiriman pesan chat) tidak didukung melalui streamAssist. Mencoba memanggil alur kerja agen yang menjalankan tindakan mutatif dapat menyebabkan kegagalan diam-diam atau loop eksekusi yang tidak berdasar.

Pemecahan masalah

Gunakan tabel berikut untuk memecahkan masalah error pemanggilan streamAssist umum:

Gejala Kemungkinan penyebab Resolusi
HTTP 404 saat mencantumkan agen Memanggil agents di endpoint v1 atau v1beta. Kirim permintaan daftar ke endpoint v1alpha.
Respons tampak generik meskipun agentsSpec telah ditetapkan agentId numerik tidak valid, atau kueri terlalu umum untuk memicu perilaku domain. Konfirmasi ID numerik yang tepat dari daftar agen v1alpha; kirim kueri khusus domain; periksa teks respons untuk mengetahui kata-kata khusus agen.
Tidak ada error yang ditampilkan, tetapi agen target tidak dieksekusi agentId yang salah bentuk menyebabkan penggantian otomatis ke orkestrasi default. Verifikasi bahwa agentId hanya terdiri dari digit dan sama persis dengan ID dari daftar registri.
Status respons menampilkan SKIPPED Input dievaluasi sebagai kueri yang tidak memerlukan bantuan (seperti sapaan singkat). Kirim kueri tugas substantif; periksa assistSkippedReasons dalam payload respons.
HTTP 401 atau HTTP 403 Permission Denied Cakupan OAuth tidak ada, peran IAM tidak memadai, atau header project kuota tidak ada. Verifikasi bahwa pemanggil memiliki discoveryengine.assistants.assist; pastikan cakupan OAuth mencakup cloud-platform; tambahkan -H "X-Goog-User-Project: PROJECT_ID" jika menggunakan ADC.

Langkah berikutnya