Chamar um agente específico com a API StreamAssist

Para chamar um agente registrado específico, forneça o campo opcional agentsSpec na solicitação de API REST streamAssist ou na chamada da biblioteca de cliente. A API AgentsSpec define a especificação dos agentes usados para atender à solicitação. O assistente encaminha as consultas diretamente para esse agente e preserva o contexto da sessão entre as conversas.

Resumo

Especificação	Detalhes
Método de API	projects.locations.collections.engines.assistants.streamAssist
Versões de endpoint	v1alpha para descobrir IDs de agentes; v1 para chamar streamAssist
Parâmetro principal	agentsSpec.agentSpecs[].agentId
Tipos de agentes compatíveis	Core Assistant, Deep Research, Workflow Builder agentes de chat (antigamente de pouco código) e fluxos de trabalho do Workflow Builder (consulte Chamar um fluxo de trabalho)
Permissão do IAM obrigatória	discoveryengine.assistants.assist
Escopo do OAuth obrigatório	https://www.googleapis.com/auth/cloud-platform

Antes de começar

1. Ative a API Discovery Engine (discoveryengine.googleapis.com) no seu Google Cloud projeto.
2. Verifique se o principal (conta de usuário ou conta de serviço) tem um papel que concede a permissão do IAM discoveryengine.assistants.assist, como Editor do Discovery Engine (roles/discoveryengine.editor) ou Admin do Gemini Enterprise (roles/discoveryengine.agentspaceAdmin).
3. Verifique se o app (mecanismo) do Gemini Enterprise foi criado e contém pelo menos um agente registrado.
4. Se você fizer a autenticação usando o Application Default Credentials (ADC), verifique se o cliente envia o cabeçalho do projeto de cota: -H "X-Goog-User-Project: PROJECT_ID".

Encontrar o ID e o local do app

O URL streamAssist exige o ID do mecanismo e o local dele (global, us ou eu). Se você só souber o nome de exibição do app, liste os mecanismos no seu projeto para localizar o ID subjacente:

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"

Na resposta, o formato do name do mecanismo é projects/{project}/locations/{location}/collections/default_collection/engines/{ENGINE_ID}. O segmento ENGINE_ID é o APP_ID necessário na chamada.

Observação: o ID do mecanismo geralmente tem um sufixo numérico anexado ao nome de exibição (por exemplo, my-app_1234567890).

Encontrar o ID do agente

O agentId é o segmento final do nome completo do recurso do agente na API Discovery Engine:

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

Os agentes registrados usam um ID numérico longo (por exemplo, 15492003793394502655) em vez de um nome de exibição amigável. Forneça apenas essa string numérica final {AGENT_ID} na sua solicitação.

Para listar os agentes registrados no seu app e descobrir os IDs numéricos deles, chame a coleção agents no 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: A coleção agents é veiculada exclusivamente no endpoint v1alpha. Chamar esse endpoint de lista em v1 ou v1beta retorna um erro HTTP 404 Not Found error. No entanto, a chamada de invocação streamAssist opera em v1.

Cada recurso de agente retornado inclui os seguintes campos:

• name: o caminho completo do recurso que termina em {AGENT_ID}.
• displayName: o nome legível por humanos mostrado no Google Cloud console.
• state: o estado operacional (como ENABLED ou PRIVATE).
• Um objeto de definição que indica o tipo de agente (como a2aAgentDefinition, lowCodeAgentDefinition ou workflowAgentDefinition).

Consulte a referência da API REST agents para o esquema completo de recursos do agente.

Enviar consultas para agentes

Para enviar consultas a um agente específico, crie a solicitação com o agentsSpec apropriado e execute-a usando bibliotecas de cliente ou REST.

Observação: se um agente depender de conectores internos ou repositórios de dados (como agentes de perguntas e respostas de documentos), a invocação dele sem fontes de dados configuradas vai gerar uma resposta "nenhuma fonte de dados configurada" em vez de um erro de API.

Estrutura do corpo da solicitação

Para encaminhar uma consulta a um agente específico, inclua o objeto agentsSpec opcional no corpo da solicitação POST:

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

Referência de campo

• agentsSpec (objeto, opcional): especificação dos agentes usados para atender à solicitação.
• agentsSpec.agentSpecs[] (matriz, opcional): uma lista de especificações de agentes. É possível especificar vários agentes nessa matriz.
• agentsSpec.agentSpecs[].agentId (string, obrigatório na especificação): o ID que identifica o recurso do agente registrado. Precisa estar em conformidade com a RFC-1034 com um comprimento máximo de 63 caracteres.

Consulte a referência da API REST streamAssist para o esquema completo da solicitação.

Chamar streamAssist

REST

O comando curl a seguir envia uma consulta a um agente específico usando a 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"
        }
      ]
    }
  }'
    

Substitua os seguintes marcadores de posição:

• LOCATION: a multirregião para o nome do host e o caminho do recurso (global, us ou eu). Se o app estiver no local global, omita o prefixo de local do nome do host (discoveryengine.googleapis.com).
• PROJECT_ID: o ID do projeto do Google Cloud .
• APP_ID: o ID do mecanismo do Gemini Enterprise (descoberto em Encontrar o ID e o local do app).
• AGENT_ID: o ID numérico do agente (descoberto em Encontrar o ID do agente).

Python

Este exemplo do Python chama streamAssist usando a biblioteca de cliente 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()
    

Entender a resposta de streaming

O endpoint streamAssist retorna um fluxo de blocos JSON no REST ou um iterador de objetos de resposta em bibliotecas de cliente:

• Texto da resposta: o texto de resposta incremental chega em answer.replies[].groundedContent.content.text. Conecte esses fragmentos de texto na ordem de recebimento para reconstruir a resposta completa.
• Fragmentos de raciocínio: os fragmentos marcados com "thought": true representam o processo de raciocínio interno do modelo. Filtre esses fragmentos ao apresentar a saída final aos usuários finais.
• Estado de execução: o campo answer.state progride de IN_PROGRESS para um estado terminal:
  • SUCCEEDED: a solicitação foi concluída e gerou uma resposta.
  • SKIPPED: a consulta foi ignorada ou ignorada. Inspecione assistSkippedReasons para mais detalhes (como NON_ASSIST_SEEKING_QUERY_IGNORED para saudações breves).
  • FAILED: a invocação encontrou um erro de execução.
• Continuidade da sessão: o bloco de terminal inclui sessionInfo.session (o nome do recurso da sessão) e um assistToken.

Continuar a conversa na mesma sessão

Para manter o contexto entre as conversas, transmita a string session de sessionInfo em solicitações subsequentes:

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 você omitir o campo session ou especificar - como o ID da sessão, a API vai gerar uma sessão nova e isolada automaticamente.

Chamar um fluxo de trabalho

Para executar um fluxo de trabalho do Workflow Builder, envie a mesma solicitação com o ID do fluxo de trabalho em agentsSpec.agentSpecs[].agentId. Cada chamada inicia uma execução manual do fluxo de trabalho.

• Versão executada: se o fluxo de trabalho for publicado, a chamada vai executar a versão publicada. As mudanças salvas no Workflow Builder, mas ainda não publicadas, não afetam os autores da chamada de API até que você as publique. Se o fluxo de trabalho nunca tiver sido publicado, a chamada vai executar o rascunho.
• Quem pode chamar: o proprietário e os admins do fluxo de trabalho podem chamá-lo. Outros usuários podem chamar um fluxo de trabalho publicado depois que ele for compartilhado com eles. Somente o proprietário ou um admin pode chamar um fluxo de trabalho que nunca foi publicado. Outros autores da chamada recebem HTTP 403.
• Acionadores: o fluxo de trabalho precisa ter exatamente um acionador manual. As chamadas falham para um fluxo de trabalho que combina um acionador manual com qualquer outro acionador ou que tem mais de um acionador manual.
• Entradas: não é possível definir as variáveis de entrada do acionador manual usando streamAssist. Se o acionador manual tiver uma entrada obrigatória, a execução vai falhar, mesmo que a entrada tenha um valor padrão. As entradas opcionais estão vazias e os valores padrão não são aplicados. O texto da consulta é transmitido aos nós LLM do fluxo de trabalho. Portanto, é possível incluir dados lá, mas eles não preenchem variáveis de entrada.

Limitações

As limitações a seguir se aplicam ao chamar agentes com streamAssist:

• Tipos de agentes não compatíveis: os agentes A2A ou ADK registrados em um app do Gemini Enterprise não são compatíveis com streamAssist. Para chamar um agente A2A diretamente usando o endpoint de registro, consulte Chamar um agente usando o endpoint A2A de registro.
• Ações mutáveis: a API streamAssist é otimizada para consultas conversacionais e recuperação somente leitura em conectores. A execução programática de ferramentas e ações mutáveis (como rascunho de e-mail, criação de eventos de agenda ou mensagens de chat) não é compatível com streamAssist. A tentativa de invocar um Agentic Workflow que executa ações mutáveis pode resultar em falhas silenciosas ou loops de execução não fundamentados.

Solução de problemas

Use a tabela a seguir para resolver problemas comuns de invocação de streamAssist:

Sintoma	Causa provável	Resolução
HTTP 404 ao listar agentes	Chamar agents no endpoint v1 ou v1beta.	Envie a solicitação de lista para o endpoint v1alpha.
A resposta parece genérica, apesar de definir agentsSpec	agentId numérico inválido ou a consulta é muito genérica para acionar o comportamento do domínio.	Confirme o ID numérico exato na lista de agentes v1alpha; envie uma consulta específica do domínio; verifique o texto de resposta para saber se há palavras específicas do agente.
Nenhum erro retornado, mas o agente de destino não foi executado	agentId malformado causou um fallback silencioso para a orquestração padrão.	Verifique se o agentId consiste apenas em dígitos e corresponde exatamente a um ID da lista de registro.
O estado da resposta retorna SKIPPED	A entrada foi avaliada como uma consulta que não busca assistência (como uma saudação breve).	Envie uma consulta de tarefa substantiva; inspecione assistSkippedReasons no payload de resposta.
HTTP 401 ou HTTP 403 Permission Denied	Escopo do OAuth ausente, papel do IAM insuficiente ou cabeçalho do projeto de cota ausente.	Verifique se o autor da chamada tem discoveryengine.assistants.assist; verifique se o escopo do OAuth inclui cloud-platform; adicione -H "X-Goog-User-Project: PROJECT_ID" se estiver usando o ADC.
HTTP 403 com Only the agent owner or an admin can run a draft of this agent.	O fluxo de trabalho nunca foi publicado, e o autor da chamada não é o proprietário nem um admin.	Publique o fluxo de trabalho no Workflow Builder e compartilhe-o com o autor da chamada.
HTTP 403 com User does not have permission to access the Agent.	O fluxo de trabalho não é compartilhado com o autor da chamada.	Compartilhe o fluxo de trabalho com o autor da chamada.
O fluxo de trabalho se comporta como uma versão mais antiga	A chamada executa a versão publicada, não as mudanças não publicadas no Workflow Builder.	Publique o fluxo de trabalho.
A chamada do fluxo de trabalho termina com answer.state FAILED e um erro INTERNAL	O fluxo de trabalho tem um acionador manual mais outro acionador ou mais de um acionador manual.	Mantenha um único acionador manual.

A seguir

• Receber resultados da pesquisa do StreamAssist
• Referência da API REST streamAssist
• Visão geral dos agentes