Llama a un agente específico con la API de StreamAssist

Para llamar a un agente registrado específico, proporciona el campo opcional agentsSpec en tu solicitud a la API de REST streamAssist o en la llamada a la biblioteca cliente. La API de AgentsSpec define la especificación de los agentes que se usan para atender la solicitud. El asistente enruta las consultas directamente a ese agente y conserva el contexto de la sesión en todas las interacciones.

Resumen

Especificación Detalles
Método de la API projects.locations.collections.engines.assistants.streamAssist
Versiones del extremo v1alpha para descubrir IDs de agentes; v1 para llamar a streamAssist
Parámetro clave agentsSpec.agentSpecs[].agentId
Tipos de agentes admitidos Agentes de chat de Core Assistant, Deep Research y Agent Designer (anteriormente, de poco código)
Permiso de IAM obligatorio discoveryengine.assistants.assist
Permiso de OAuth obligatorio https://www.googleapis.com/auth/cloud-platform

Antes de comenzar

  1. Habilita la API de Discovery Engine (discoveryengine.googleapis.com) en tu Google Cloud proyecto.
  2. Asegúrate de que tu principal (cuenta de usuario o cuenta de servicio) tenga un rol que otorgue el permiso de IAM discoveryengine.assistants.assist, como Editor de Discovery Engine (roles/discoveryengine.editor) o Administrador de Gemini Enterprise (roles/discoveryengine.agentspaceAdmin).
  3. Verifica que se haya creado tu app (motor) de Gemini Enterprise y que contenga al menos un agente registrado.
  4. Si te autenticas con las credenciales predeterminadas de la aplicación (ADC), asegúrate de que tu cliente envíe el encabezado del proyecto de cuota: -H "X-Goog-User-Project: PROJECT_ID".

Encuentra el ID y la ubicación de tu app

La URL de streamAssist requiere el ID de tu motor y su ubicación (global, us o eu). Si solo conoces el nombre visible de la app, enumera los motores de tu proyecto para ubicar el ID subyacente:

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"

En la respuesta, el formato name del motor es projects/{project}/locations/{location}/collections/default_collection/engines/{ENGINE_ID}. El segmento ENGINE_ID es el APP_ID que se requiere en la llamada.

Encuentra el ID del agente

El agentId es el segmento final del nombre completo del recurso del agente en la API de Discovery Engine:

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

Los agentes registrados usan un ID numérico largo (por ejemplo, 15492003793394502655) en lugar de un nombre visible descriptivo. Proporciona solo esta cadena numérica final {AGENT_ID} en tu solicitud.

Para enumerar los agentes registrados en tu app y descubrir sus IDs numéricos, llama a la colección agents en el extremo 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 que se muestra incluye los siguientes campos:

  • name: Es la ruta de acceso completa del recurso que termina en {AGENT_ID}.
  • displayName: Es el nombre legible que se muestra en la Google Cloud consola.
  • state: Es el estado operativo (como ENABLED o PRIVATE).
  • Un objeto de definición que indica el tipo de agente (como a2aAgentDefinition o lowCodeAgentDefinition).

Consulta la referencia de la API de REST agents para obtener el esquema completo del recurso del agente.

Envía consultas a los agentes

Para enviar consultas a un agente específico, debes construir tu solicitud con el agentsSpec adecuado y ejecutarla con REST o bibliotecas cliente.

Estructura del cuerpo de la solicitud

Para enrutar una consulta a un agente específico, incluye el objeto agentsSpec opcional en el cuerpo de la solicitud POST:

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

Referencia de campo

  • agentsSpec (objeto, opcional): Es la especificación de los agentes que se usan para atender la solicitud.
  • agentsSpec.agentSpecs[] (array, opcional): Es una lista de especificaciones de agentes. Puedes especificar varios agentes en este array.
  • agentsSpec.agentSpecs[].agentId (cadena, obligatoria dentro de la especificación): Es el ID que identifica el recurso del agente registrado. Debe ajustarse a RFC-1034 con una longitud máxima de 63 caracteres.

Consulta la referencia de la API de REST streamAssist para obtener el esquema completo de la solicitud.

Llama a streamAssist

REST

El siguiente comando curl envía una consulta a un agente específico con la API de 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"
        }
      ]
    }
  }'

Reemplaza los marcadores de posición que se indican más abajo:

  • LOCATION: Es la multirregión para el nombre de host y la ruta de acceso del recurso (global, us o eu). Si tu app reside en la ubicación global, omite el prefijo de ubicación del nombre de host (discoveryengine.googleapis.com).
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • APP_ID: Es el ID del motor de Gemini Enterprise (descubierto en Encuentra el ID y la ubicación de tu app).
  • AGENT_ID: Es el ID numérico del agente (descubierto en Encuentra el ID del agente).

Python

En este ejemplo de Python, se llama a streamAssist con la biblioteca 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()

Comprende la respuesta de transmisión

El extremo streamAssist muestra una transmisión de fragmentos JSON a través de REST o un iterador de objetos de respuesta en las bibliotecas cliente:

  • Texto de respuesta: El texto de respuesta incremental llega en answer.replies[].groundedContent.content.text. Concatena estos fragmentos de texto en orden de recepción para reconstruir la respuesta completa.
  • Fragmentos de razonamiento: Los fragmentos marcados con "thought": true representan el proceso de razonamiento interno del modelo. Filtra estos fragmentos cuando presentes el resultado final a los usuarios finales.
  • Estado de ejecución: El campo answer.state avanza de IN_PROGRESS a un estado terminal:
    • SUCCEEDED: La solicitud se completó y generó una respuesta.
    • SKIPPED: Se ignoró o se omitió la consulta. Inspecciona assistSkippedReasons para obtener detalles (como NON_ASSIST_SEEKING_QUERY_IGNORED para saludos breves).
    • FAILED: La invocación encontró un error de ejecución.
  • Continuidad de la sesión: El fragmento de terminal incluye sessionInfo.session (el nombre del recurso de la sesión) y un assistToken.

Continúa la conversación en la misma sesión

Para mantener el contexto en todas las interacciones, pasa la cadena session de sessionInfo en las solicitudes posteriores:

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"
        }
      ]
    }
  }'

Si omites el campo session o especificas - como el ID de la sesión, la API genera automáticamente una sesión nueva y aislada.

Limitaciones

Se aplican las siguientes limitaciones cuando se llama a agentes con streamAssist:

  • Tipos de agentes no admitidos:
    • No se admiten los agentes de flujo de trabajo.
    • No se admiten los agentes A2A o ADK registrados en una app de Gemini Enterprise a través de streamAssist. Para llamar a un agente A2A directamente con su extremo de registro, consulta Llama a un agente con su extremo de registro A2A.
  • Acciones mutativas: La API de streamAssist está optimizada para consultas conversacionales y recuperación de solo lectura a través de conectores. No se admite la ejecución programática de herramientas y acciones mutativas (como la redacción de correos electrónicos, la creación de eventos de calendario o la mensajería de chat) a través de streamAssist. Si intentas invocar un flujo de trabajo de agente que ejecuta acciones mutativas, es posible que se produzcan fallas silenciosas o bucles de ejecución no fundamentados.

Soluciona problemas

Usa la siguiente tabla para solucionar problemas comunes de invocación de streamAssist:

Síntoma Causa probable Solución
HTTP 404 cuando se enumeran agentes Llamar a agents en el extremo v1 o v1beta. Envía la solicitud de lista al extremo v1alpha.
La respuesta parece genérica a pesar de configurar agentsSpec agentId numérico no válido o la consulta es demasiado genérica para activar el comportamiento del dominio. Confirma el ID numérico exacto de la lista de agentes v1alpha; envía una consulta específica del dominio; verifica el texto de respuesta para obtener palabras específicas del agente.
No se muestra ningún error, pero el agente de destino no se ejecutó agentId con formato incorrecto causó una reserva silenciosa a la organización predeterminada. Verifica que el agentId conste solo de dígitos y coincida exactamente con un ID de la lista de registro.
El estado de la respuesta muestra SKIPPED La entrada se evaluó como una consulta que no busca asistencia (como un saludo breve). Envía una consulta de tarea sustantiva; inspecciona assistSkippedReasons en la carga útil de la respuesta.
HTTP 401 o HTTP 403 Permission Denied Falta el alcance de OAuth, el rol de IAM es insuficiente o falta el encabezado del proyecto de cuota. Verifica que la persona que llama tenga discoveryengine.assistants.assist; asegúrate de que el alcance de OAuth incluya cloud-platform; agrega -H "X-Goog-User-Project: PROJECT_ID" si usas ADC.

¿Qué sigue?