Chiamare un agente specifico con l'API StreamAssist

Per chiamare un agente registrato specifico, fornisci il campo facoltativo agentsSpec nella richiesta dell'API REST streamAssist o nella chiamata della libreria client. L'API AgentsSpec definisce la specifica degli agenti utilizzati per gestire la richiesta. L'assistente indirizza le query direttamente all'agente e conserva il contesto della sessione tra i turni.

In sintesi

Specifica Dettagli
Metodo API projects.locations.collections.engines.assistants.streamAssist
Versioni dell'endpoint v1alpha per scoprire gli ID agente; v1 per chiamare streamAssist
Parametro chiave agentsSpec.agentSpecs[].agentId
Tipi di agenti supportati Core Assistant, Deep Research, agenti di chat di Workflow Builder (in precedenza low-code) e workflow di Workflow Builder (vedi Chiamare un workflow)
Autorizzazione IAM richiesta discoveryengine.assistants.assist
Ambito OAuth richiesto https://www.googleapis.com/auth/cloud-platform

Prima di iniziare

  1. Attiva l'API Discovery Engine (discoveryengine.googleapis.com) nel tuo Google Cloud progetto.
  2. Assicurati che la tua entità (account utente o account di servizio) abbia un ruolo che conceda l'autorizzazione IAM discoveryengine.assistants.assist, ad esempio Editor di Discovery Engine (roles/discoveryengine.editor) o Amministratore di Gemini Enterprise (roles/discoveryengine.agentspaceAdmin).
  3. Verifica che l'app (motore) Gemini Enterprise sia stata creata e contenga almeno un agente registrato.
  4. Se esegui l'autenticazione utilizzando le Credenziali predefinite dell'applicazione (ADC), assicurati che il client invii l'intestazione del progetto di quota: -H "X-Goog-User-Project: PROJECT_ID".

Trovare l'ID e la località dell'app

L'URL streamAssist richiede l'ID motore e la relativa località (global, us o eu). Se conosci solo il nome visualizzato dell'app, elenca i motori nel tuo progetto per individuare l'ID sottostante:

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"

Nella risposta, il formato name del motore è projects/{project}/locations/{location}/collections/default_collection/engines/{ENGINE_ID}. Il segmento ENGINE_ID è l'APP_ID richiesto nella chiamata.

Trovare l'ID agente

agentId è il segmento finale del nome completo della risorsa dell'agente nell'API Discovery Engine:

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

Gli agenti registrati utilizzano un ID numerico lungo (ad esempio, 15492003793394502655) anziché un nome visualizzato descrittivo. Fornisci solo questa stringa numerica {AGENT_ID} finale nella richiesta.

Per elencare gli agenti registrati nella tua app e scoprire i relativi ID numerici, chiama la raccolta agents sull'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"

Ogni risorsa agente restituita include i seguenti campi:

  • name: il percorso completo della risorsa che termina con {AGENT_ID}.
  • displayName: il nome leggibile mostrato nella Google Cloud console.
  • state: lo stato operativo (ad esempio ENABLED o PRIVATE).
  • Un oggetto di definizione che indica il tipo di agente (ad esempio a2aAgentDefinition, lowCodeAgentDefinition o workflowAgentDefinition).

Consulta il riferimento API REST agents per lo schema completo della risorsa agente.

Inviare query agli agenti

Per inviare query a un agente specifico, devi creare la richiesta con agentsSpec appropriato ed eseguirla utilizzando le librerie REST o client.

Struttura del corpo della richiesta

Per indirizzare una query a un agente specifico, includi l'oggetto facoltativo agentsSpec nel corpo della richiesta POST:

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

Riferimento ai campi

  • agentsSpec (oggetto, facoltativo): specifica degli agenti utilizzati per gestire la richiesta.
  • agentsSpec.agentSpecs[] (array, facoltativo): un elenco di specifiche dell'agente. Puoi specificare più agenti in questo array.
  • agentsSpec.agentSpecs[].agentId (stringa, obbligatoria nella specifica): l'ID che identifica la risorsa agente registrata. Deve essere conforme a RFC-1034 con una lunghezza massima di 63 caratteri.

Consulta il riferimento API REST streamAssist per lo schema completo della richiesta.

Chiamare streamAssist

REST

Il seguente comando curl invia una query a un agente specifico utilizzando l'API REST:

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

Sostituisci i seguenti segnaposto:

  • LOCATION: la multiregione per il nome host e il percorso della risorsa (global, us o eu). Se la tua app si trova nella località global, ometti il prefisso della località dal nome host (discoveryengine.googleapis.com).
  • PROJECT_ID: l' Google Cloud ID progetto.
  • APP_ID: l'ID motore Gemini Enterprise (individuato in Trovare l'ID e la località dell'app).
  • AGENT_ID: l'ID agente numerico (individuato in Trovare l'ID agente).

Python

Questo esempio Python chiama streamAssist utilizzando la libreria client 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()

Comprendere la risposta di streaming

L'endpoint streamAssist restituisce un flusso di blocchi JSON su REST o un iteratore di oggetti di risposta nelle librerie client:

  • Testo della risposta: il testo della risposta incrementale arriva in answer.replies[].groundedContent.content.text. Concatena questi frammenti di testo nell'ordine di ricezione per ricostruire la risposta completa.
  • Frammenti di ragionamento: i frammenti contrassegnati con "thought": true rappresentano il processo di ragionamento interno del modello. Filtra questi frammenti quando presenti l'output finale agli utenti finali.
  • Stato di esecuzione: il campo answer.state passa da IN_PROGRESS a uno stato terminale:
    • SUCCEEDED: la richiesta è stata completata e ha generato una risposta.
    • SKIPPED: la query è stata ignorata o bypassata. Esamina assistSkippedReasons per i dettagli (ad esempio, NON_ASSIST_SEEKING_QUERY_IGNORED per i saluti brevi).
    • FAILED: la chiamata ha rilevato un errore di esecuzione.
  • Continuità della sessione: il blocco terminale include sessionInfo.session (il nome della risorsa della sessione) e un assistToken.

Continuare la conversazione nella stessa sessione

Per mantenere il contesto tra i turni, passa la stringa session da sessionInfo nelle richieste successive:

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

Se ometti il campo session o specifichi - come ID sessione, l'API genera automaticamente una nuova sessione isolata.

Chiamare un workflow

Per eseguire un workflow di Workflow Builder, invia la stessa richiesta con l'ID del workflow in agentsSpec.agentSpecs[].agentId. Ogni chiamata avvia un'esecuzione manuale del workflow.

  • Versione in esecuzione: se il workflow è pubblicato, la chiamata esegue la versione pubblicata. Le modifiche salvate in Workflow Builder ma non ancora pubblicate non influiscono sui chiamanti API finché non le pubblichi. Se il workflow non è mai stato pubblicato, la chiamata esegue la bozza.
  • Chi può chiamarlo: il proprietario e gli amministratori del workflow possono chiamarlo. Gli altri utenti possono chiamare un workflow pubblicato dopo che è stato condiviso con loro. Solo il proprietario o un amministratore può chiamare un workflow che non è mai stato pubblicato; gli altri chiamanti ricevono HTTP 403.
  • Trigger: il workflow deve avere esattamente un trigger manuale. Le chiamate non vanno a buon fine per un workflow che combina un trigger manuale con qualsiasi altro trigger o che ha più di un trigger manuale.
  • Input: non puoi impostare le variabili di input del trigger manuale tramite streamAssist. Se il trigger manuale ha un input obbligatorio, l'esecuzione non va a buon fine, anche se l'input ha un valore predefinito. Gli input facoltativi sono vuoti e i relativi valori predefiniti non vengono applicati. Il testo della query viene passato ai nodi LLM del workflow, quindi puoi includere i dati, ma non riempie le variabili di input.

Limitazioni

Quando chiami gli agenti con streamAssist, si applicano le seguenti limitazioni:

  • Tipi di agenti non supportati: gli agenti A2A o ADK registrati in un'app Gemini Enterprise non sono supportati tramite streamAssist. Per chiamare direttamente un agente A2A utilizzando l'endpoint del registro, vedi Chiamare un agente utilizzando l'endpoint A2A del registro.
  • Azioni mutative: l'API streamAssist è ottimizzata per le query conversazionali e il recupero di sola lettura tramite i connettori. L'esecuzione programmatica di strumenti e azioni mutative (ad esempio, la stesura di email, la creazione di eventi di calendario o la messaggistica di chat) non è supportata tramite streamAssist. Il tentativo di chiamare un workflow dell'agente che esegue azioni mutative può comportare errori silenziosi o loop di esecuzione non basati su dati reali.

Risoluzione dei problemi

Utilizza la tabella seguente per risolvere i problemi relativi agli errori comuni di chiamata streamAssist:

Sintomo Causa probabile Risoluzione
HTTP 404 durante l'elenco degli agenti Chiamata di agents sull'endpoint v1 o v1beta. Invia invece la richiesta di elenco all'endpoint v1alpha.
La risposta sembra generica nonostante l'impostazione di agentsSpec agentId numerico non valido o la query è troppo generica per attivare il comportamento del dominio. Conferma l'ID numerico esatto dall'elenco degli agenti v1alpha; invia una query specifica del dominio; controlla il testo della risposta per la formulazione specifica dell'agente.
Nessun errore restituito, ma l'agente di destinazione non è stato eseguito agentId non valido ha causato un fallback silenzioso all'orchestrazione predefinita. Verifica che agentId sia composto solo da cifre e corrisponda esattamente a un ID dell'elenco del registro.
Lo stato della risposta restituisce SKIPPED L'input è stato valutato come una query non di assistenza (ad esempio, un saluto breve). Invia una query di attività sostanziale; esamina assistSkippedReasons nel payload della risposta.
HTTP 401 o HTTP 403 Permission Denied Ambito OAuth mancante, ruolo IAM insufficiente o intestazione del progetto di quota mancante. Verifica che il chiamante abbia discoveryengine.assistants.assist; assicurati che l'ambito OAuth includa cloud-platform; aggiungi -H "X-Goog-User-Project: PROJECT_ID" se utilizzi ADC.
HTTP 403 con Only the agent owner or an admin can run a draft of this agent. Il workflow non è mai stato pubblicato e il chiamante non è il proprietario o un amministratore. Pubblica il workflow in Workflow Builder e condividilo con il chiamante.
HTTP 403 con User does not have permission to access the Agent. Il workflow non è condiviso con il chiamante. Condividi il workflow con il chiamante.
Il workflow si comporta come una versione precedente La chiamata esegue la versione pubblicata, non le modifiche non pubblicate in Workflow Builder. Pubblica il workflow.
La chiamata del workflow termina con answer.state FAILED e un errore INTERNAL Il workflow ha un trigger manuale più un altro trigger o più di un trigger manuale. Mantieni un singolo trigger manuale.

Passaggi successivi