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 interações.

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 de chave agentsSpec.agentSpecs[].agentId
Tipos de agentes compatíveis Core Assistant, Deep Research, agentes de chat do Workflow Builder (antigo 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 projeto do Google Cloud .
  2. Verifique se o principal (conta de usuário ou de 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 Administrador do Gemini Enterprise (roles/discoveryengine.agentspaceAdmin).
  3. Verifique se o app do Gemini Enterprise (mecanismo) 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 requer o ID do mecanismo e o local dele (global, us ou eu). Se você souber apenas o nome de exibição do app, liste os mecanismos no projeto para localizar o ID:

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 mecanismo name é projects/{project}/locations/{location}/collections/default_collection/engines/{ENGINE_ID}. O segmento ENGINE_ID é o APP_ID obrigatório na chamada.

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 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"

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 console do Google Cloud .
  • 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 ver o esquema completo de recursos do agente.

Enviar consultas para agentes

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

Estrutura do corpo da solicitação

Para encaminhar uma consulta a um agente específico, inclua o objeto opcional agentsSpec 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 do agente. É possível especificar vários agentes nessa matriz.
  • agentsSpec.agentSpecs[].agentId (string, obrigatória na especificação): o ID que identifica o recurso do agente registrado. Precisa estar em conformidade com RFC-1034 e ter no máximo 63 caracteres.

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

Chamar streamAssist

REST

O comando curl a seguir envia uma consulta para 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 do 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 (encontrado em Encontrar o ID e o local do app).
  • AGENT_ID: o ID numérico do agente (encontrado em Encontrar o ID do agente).

Python

Este exemplo em 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 stream de blocos JSON por REST ou um iterador de objetos de resposta em bibliotecas de cliente:

  • Texto da resposta: o texto da resposta incremental chega em answer.replies[].groundedContent.content.text. Concatene 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 o resultado final aos usuários finais.
  • Estado de execução: o campo answer.state avança 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 ver 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 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 interações, transmita a string session de sessionInfo nas solicitações seguintes:

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 nova sessão 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 de chamadas de API até que você as publique. Se o fluxo de trabalho nunca tiver sido publicado, a chamada vai executar o rascunho dele.
  • Quem pode chamar: o proprietário e os administradores do fluxo de trabalho. Outros usuários podem chamar um fluxo de trabalho publicado depois que ele é compartilhado com eles. Somente o proprietário ou um administrador pode chamar um fluxo de trabalho que nunca foi publicado. Outros autores de chamada recebem HTTP 403.
  • Gatilhos: o fluxo de trabalho precisa ter exatamente um gatilho manual. As chamadas falham em um fluxo de trabalho que combina um gatilho manual com qualquer outro gatilho ou que tem mais de um gatilho manual.
  • Entradas: não é possível definir as variáveis de entrada do gatilho manual usando streamAssist. Se o gatilho 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 delas não são aplicados. O texto da consulta é transmitido para os nós de LLM do fluxo de trabalho. Assim, é possível incluir dados nele, mas ele não preenche as variáveis de entrada.

Limitações

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

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

Solução de problemas

Use a tabela a seguir para resolver erros comuns de invocação do 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 O valor numérico agentId é 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 e verifique se o texto da resposta tem uma linguagem específica do agente.
Nenhum erro retornado, mas o agente de destino não foi executado O agentId corrompido 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 registros.
O estado de resposta retorna SKIPPED Entrada avaliada como uma consulta que não busca assistência (como uma saudação breve). Envie uma consulta de tarefa substantiva e 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, se o escopo do OAuth inclui cloud-platform e 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 administrador. Publique o fluxo de trabalho no Workflow Builder e compartilhe 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 gatilho manual e outro gatilho, ou mais de um gatilho manual. Manter um único gatilho manual.

A seguir