Chiamare un agente specifico con l'API StreamAssist

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

In sintesi

Specifica Dettagli
Metodo API projects.locations.collections.engines.assistants.streamAssist
Versioni degli 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 Chiama un workflow)
Autorizzazione IAM obbligatoria discoveryengine.assistants.assist
Ambito OAuth obbligatorio https://www.googleapis.com/auth/cloud-platform

Prima di iniziare

  1. Abilita l'API Discovery Engine (discoveryengine.googleapis.com) nel tuo progetto Google Cloud .
  2. Assicurati che la tua entità (account utente o account di servizio) abbia un ruolo che concede l'autorizzazione IAM discoveryengine.assistants.assist, ad esempio Discovery Engine Editor (roles/discoveryengine.editor) o Gemini Enterprise Admin (roles/discoveryengine.agentspaceAdmin).
  3. Verifica che l'app (engine) 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".

Trova l'ID app e la posizione

L'URL streamAssist richiede l'ID del motore e la sua 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 è il APP_ID richiesto nella chiamata.

Trova 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 facile da ricordare. Fornisci solo questa stringa numerica {AGENT_ID} finale nella richiesta.

Per elencare gli agenti registrati nella tua app e scoprire i loro 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 console Google Cloud .
  • 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 dell'agente.

Invia query agli agenti

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

Struttura del corpo della richiesta

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

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

Riferimento per i 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 all'interno della 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 di richiesta completo.

Call 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 multi-regione sia per il nome host sia per 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'ID progetto Google Cloud .
  • APP_ID: l'ID del tuo motore Gemini Enterprise (scoperto in Trova l'ID e la località dell'app).
  • AGENT_ID: l'ID agente numerico (scoperto in Trova l'ID agente).

Python

Questo esempio di 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()

Comprendi la risposta in streaming

L'endpoint streamAssist restituisce uno stream 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. Controlla assistSkippedReasons per i dettagli (ad esempio NON_ASSIST_SEEKING_QUERY_IGNORED per i saluti brevi).
    • FAILED: la chiamata ha riscontrato un errore di esecuzione.
  • Continuità della sessione: il chunk finale include sessionInfo.session (il nome della risorsa della sessione) e un assistToken.

Continua 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.

Chiama 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 eseguita: 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. 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 dati lì, ma non compila 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 il relativo endpoint del registry, consulta Chiama un agente utilizzando il relativo endpoint A2A del registry.
  • Azioni di modifica: l'API streamAssist è ottimizzata per le query di conversazione e il recupero di sola lettura tramite i connettori. L'esecuzione programmatica di strumenti e azioni mutativi (come la bozza di email, la creazione di eventi nel calendario o i messaggi chat) non è supportata su streamAssist. Il tentativo di richiamare un Agentic Workflows che esegue azioni mutative potrebbe causare errori silenziosi o loop di esecuzione non fondati.

Risoluzione dei problemi

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

Sintomo Causa probabile Risoluzione
HTTP 404 durante la visualizzazione dell'elenco degli agenti Chiamata a agents sull'endpoint v1 o v1beta. Invia la richiesta di elenco all'endpoint v1alpha.
La risposta sembra generica nonostante l'impostazione agentsSpec Valore numerico agentId non valido o query troppo generica per attivare il comportamento del dominio. Conferma l'ID numerico esatto dall'elenco degli agenti v1alpha; invia una query specifica per il dominio; controlla il testo della risposta per verificare la presenza di termini specifici dell'agente.
Nessun errore restituito, ma l'agente di destinazione non è stato eseguito agentId con formato non corretto 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 Input valutato come una query che non richiede assistenza (ad esempio un breve saluto). Invia una query per un'attività sostanziale; controlla 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 flusso di lavoro 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 al 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