Memanggil agen tertentu dengan StreamAssist API

Untuk memanggil agen terdaftar tertentu, berikan kolom agentsSpec opsional dalam permintaan REST API atau panggilan library klien streamAssist Anda. AgentsSpec API menentukan spesifikasi agen yang digunakan untuk menyajikan permintaan. Asisten akan 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 kunci agentsSpec.agentSpecs[].agentId
Jenis agen yang didukung Asisten Inti, Deep Research, agen chat Workflow Builder (sebelumnya low-code), dan alur kerja Workflow Builder (lihat Memanggil alur kerja)
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 dan lokasinya (global, us, atau eu). Jika Anda hanya mengetahui nama tampilan aplikasi, cantumkan mesin dalam 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 dikenali. 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 menyertakan 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, lowCodeAgentDefinition, atau workflowAgentDefinition).

Lihat referensi REST API agents untuk mengetahui skema resource agen yang lengkap.

Mengirim kueri ke agen

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

Struktur isi permintaan

Untuk merutekan 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 menyajikan permintaan.
  • agentsSpec.agentSpecs[] (array, opsional): Daftar spesifikasi agen. Anda dapat menentukan beberapa agen dalam array ini.
  • agentsSpec.agentSpecs[].agentId (string, diperlukan dalam spesifikasi): ID yang mengidentifikasi resource agen terdaftar. Harus sesuai dengan RFC-1034 dengan panjang maksimum 63 karakter.

Lihat referensi REST API streamAssist untuk mengetahui skema permintaan lengkap.

Memanggil streamAssist

REST

Perintah curl berikut mengirimkan 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 penerimaan untuk merekonstruksi jawaban lengkap.
  • Fragmen penalaran: Fragmen yang ditandai dengan "thought": true mewakili proses penalaran internal model. Filter fragmen ini saat menampilkan output akhir kepada pengguna akhir.
  • Status eksekusi: Kolom answer.state berlanjut dari IN_PROGRESS ke status terminal:
    • SUCCEEDED: Permintaan selesai dan menghasilkan jawaban.
    • SKIPPED: Kueri diabaikan atau dilewati. Periksa assistSkippedReasons untuk mengetahui detailnya (seperti NON_ASSIST_SEEKING_QUERY_IGNORED untuk salam singkat).
    • FAILED: Pemanggilan mengalami error eksekusi.
  • Kontinuitas sesi: Chunk terminal menyertakan 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 otomatis membuat sesi baru yang terisolasi.

Memanggil alur kerja

Untuk menjalankan alur kerja Workflow Builder, kirim permintaan yang sama dengan ID alur kerja di agentsSpec.agentSpecs[].agentId. Setiap panggilan memulai operasi manual alur kerja.

  • Versi yang berjalan: Jika alur kerja dipublikasikan, panggilan akan menjalankan versi yang dipublikasikan. Perubahan yang disimpan di Workflow Builder, tetapi belum dipublikasikan, tidak akan memengaruhi pemanggil API hingga Anda memublikasikannya. Jika alur kerja belum pernah dipublikasikan, panggilan akan menjalankan drafnya.
  • Siapa yang dapat memanggilnya: Pemilik dan admin alur kerja dapat memanggilnya. Pengguna lain dapat memanggil alur kerja yang dipublikasikan setelah dibagikan kepada mereka. Hanya pemilik atau admin yang dapat memanggil alur kerja yang belum pernah dipublikasikan; pemanggil lain akan menerima HTTP 403.
  • Pemicu: Alur kerja harus memiliki tepat satu pemicu manual. Panggilan gagal untuk alur kerja yang menggabungkan pemicu manual dengan pemicu lain, atau yang memiliki lebih dari satu pemicu manual.
  • Input: Anda tidak dapat menetapkan variabel input pemicu manual melalui streamAssist. Jika pemicu manual memiliki input yang diperlukan, operasi akan gagal, meskipun input memiliki nilai default. Input opsional kosong, dan nilai defaultnya tidak diterapkan. Teks kueri diteruskan ke node LLM alur kerja, sehingga Anda dapat menyertakan data di sana, tetapi tidak mengisi variabel input.

Batasan

Batasan berikut berlaku saat memanggil agen dengan streamAssist:

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

Pemecahan masalah

Gunakan tabel berikut untuk memecahkan masalah error pemanggilan streamAssist yang 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 umum meskipun telah menetapkan agentsSpec 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 kata-kata khusus agen.
Tidak ada error yang ditampilkan, tetapi agen target tidak dieksekusi agentId yang salah format menyebabkan penggantian otomatis ke orkestrasi default. Pastikan agentId hanya terdiri dari angka dan sama persis dengan ID dari daftar pendaftaran.
Status respons menampilkan SKIPPED Input dievaluasi sebagai kueri yang tidak meminta bantuan (seperti salam 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. Pastikan pemanggil memiliki discoveryengine.assistants.assist; pastikan cakupan OAuth menyertakan cloud-platform; tambahkan -H "X-Goog-User-Project: PROJECT_ID" jika menggunakan ADC.
HTTP 403 dengan Only the agent owner or an admin can run a draft of this agent. Alur kerja belum pernah dipublikasikan, dan pemanggil bukan pemilik atau adminnya. Publikasikan alur kerja di Workflow Builder dan bagikan kepada penelepon.
HTTP 403 dengan User does not have permission to access the Agent. Alur kerja tidak dibagikan kepada pemanggil. Bagikan alur kerja kepada penelepon.
Alur kerja berperilaku seperti versi lama Panggilan akan menjalankan versi yang dipublikasikan, bukan perubahan yang belum dipublikasikan di Workflow Builder. Publikasikan alur kerja.
Panggilan alur kerja berakhir dengan answer.state FAILED dan error INTERNAL Alur kerja memiliki pemicu manual dan pemicu lain, atau lebih dari satu pemicu manual. Pertahankan satu pemicu manual.

Langkah berikutnya