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	Agenti di chat Core Assistant, Deep Research e Agent Designer (in precedenza low-code)
Autorizzazione IAM richiesta	discoveryengine.assistants.assist
Ambito OAuth richiesto	https://www.googleapis.com/auth/cloud-platform

Prima di iniziare

1. Abilita l'API Discovery Engine (discoveryengine.googleapis.com) nel tuo Google Cloud progetto.
2. Assicurati che la tua entità principale (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 app e la località

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.

Nota: l'ID motore in genere ha un suffisso numerico aggiunto al nome visualizzato (ad esempio my-app_1234567890).

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 finale {AGENT_ID} 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"

Importante: La raccolta agents viene pubblicata esclusivamente sull'endpoint v1alpha. La chiamata a questo endpoint di elenco su v1 o v1beta restituisce un errore HTTP 404 Not Found. Tuttavia, la chiamata di invocazione streamAssist stessa opera su v1.

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 o lowCodeAgentDefinition).

Per lo schema completo della risorsa agente, consulta il riferimento API REST agents.

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.

Nota: se un agente si basa su connettori o datastore interni (ad esempio gli agenti di domande e risposte sui documenti), la sua invocazione senza origini dati configurate genera una risposta "nessuna origine dati configurata" anziché un errore API.

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.

Per lo schema completo della richiesta, consulta il riferimento API REST streamAssist.

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 regione multipla 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 app e la località).
• 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()
    

Informazioni sulla 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: l'invocazione 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.

Limitazioni

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

• Tipi di agenti non supportati:
  • Gli agenti del flusso di lavoro non sono 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, consulta 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 invocare un flusso di lavoro dell'agente che esegue azioni mutative può comportare errori silenziosi o loop di esecuzione non basati su dati.

Risoluzione dei problemi

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

Sintomo	Causa probabile	Risoluzione
HTTP 404 durante l'elenco degli agenti	Chiamata di agents sull'endpoint v1 o v1beta.	Invia 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 breve saluto).	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.

Passaggi successivi

• Ottenere i risultati di ricerca da StreamAssist
• Riferimento API REST streamAssist
• Panoramica degli agenti