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 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 do endpoint	v1alpha para descobrir IDs de agentes; v1 para chamar streamAssist
Parâmetro principal	agentsSpec.agentSpecs[].agentId
Tipos de agentes compatíveis	Agentes de chat do Core Assistant, do Deep Research e do Agent Designer (antigamente, de pouco código)
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 Administrador do Gemini Enterprise (roles/discoveryengine.agentspaceAdmin).
3. Verifique se o app 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 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 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 normalmente 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 solicitação.

Para listar os agentes registrados no 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 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 ou lowCodeAgentDefinition).

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 armazenamentos 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 stream de blocos JSON por 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. 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 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 interações, 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.

Limitações

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

• Tipos de agentes não compatíveis:
  • Agentes de fluxo de trabalho não são compatíveis.
  • 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 mutativas: a API streamAssist é otimizada para consultas conversacionais e recuperação somente leitura em conectores. A execução programática de ferramentas e ações mutativas (como rascunho de e-mail, criação de eventos de agenda ou mensagens de chat) não é compatível com streamAssist. Tentar invocar um fluxo de trabalho de agente que executa ações mutativas pode resultar em falhas silenciosas ou loops de execução não fundamentados.

Solução de problemas

Use a tabela a seguir para resolver erros comuns de invocação 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 da 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.

A seguir

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