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	Core Assistant, Deep Research, agentes de chat de Workflow Builder (antes de poco código) y flujos de trabajo de Workflow Builder (consulta Cómo llamar a un flujo de trabajo)
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 tu app de Gemini Enterprise (motor) esté creada y 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".

Cómo encontrar 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 requerido en la llamada.

Nota: Por lo general, el ID del motor tiene un sufijo numérico agregado al nombre visible (por ejemplo, my-app_1234567890).

Cómo encontrar el ID del agente

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

Importante: La colección agents se entrega exclusivamente en el extremo v1alpha. Si llamas a este extremo de lista en v1 o v1beta, se muestra un error 404 Not Found de HTTP. Sin embargo, la llamada de invocación streamAssist en sí opera en v1.

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 por humanos 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, lowCodeAgentDefinition o workflowAgentDefinition).

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 crear tu solicitud con el agentsSpec adecuado y ejecutarla con REST o bibliotecas cliente.

Nota: Si un agente depende de conectores internos o almacenes de datos (como los agentes de preguntas y respuestas de documentos), invocarlo sin fuentes de datos configuradas genera una respuesta "no data sources configured" en lugar de un error de API.

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 de tu motor de Gemini Enterprise (descubierto en Cómo encontrar el ID y la ubicación de tu app).
• AGENT_ID: Es el ID numérico del agente (descubierto en Cómo encontrar el ID del agente).

Python

En este ejemplo de Python, se llama a streamAssist con la biblioteca cliente de 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 la 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 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 sesión, la API genera automáticamente una sesión nueva y aislada.

Cómo llamar a un flujo de trabajo

Para ejecutar un flujo de trabajo de Workflow Builder, envía la misma solicitud con el ID del flujo de trabajo en agentsSpec.agentSpecs[].agentId. Cada llamada inicia una ejecución manual del flujo de trabajo.

• Versión que se ejecuta: Si se publica el flujo de trabajo, la llamada ejecuta su versión publicada. Los cambios guardados en Workflow Builder, pero que aún no se publicaron, no afectan a las llamadas a la API hasta que los publiques. Si el flujo de trabajo nunca se publicó, la llamada ejecuta su borrador.
• Quién puede llamarlo: El propietario y los administradores del flujo de trabajo pueden llamarlo. Otros usuarios pueden llamar a un flujo de trabajo publicado después de que se comparte con ellos. Solo el propietario o un administrador pueden llamar a un flujo de trabajo que nunca se publicó; otros llamadores reciben HTTP 403.
• Activadores: El flujo de trabajo debe tener exactamente un activador manual. Las llamadas fallan para un flujo de trabajo que combina un activador manual con cualquier otro activador o que tiene más de un activador manual.
• Entradas: No puedes configurar las variables de entrada del activador manual a través de streamAssist. Si el activador manual tiene una entrada obligatoria, la ejecución falla, incluso si la entrada tiene un valor predeterminado. Las entradas opcionales están vacías y no se aplican sus valores predeterminados. El texto de la consulta se pasa a los nodos LLM del flujo de trabajo, por lo que puedes incluir datos allí, pero no completa las variables de entrada.

Limitaciones

Las siguientes limitaciones se aplican cuando se llama a agentes con streamAssist:

• Tipos de agentes no admitidos: Los agentes A2A o ADK registrados en una app de Gemini Enterprise no son compatibles con streamAssist. Para llamar a un agente A2A directamente con su extremo de registro, consulta Cómo llamar a un agente con su extremo A2A de registro.
• 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 creació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 relacionados con errores 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 una redacción específica 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 permiso de OAuth, el rol de IAM es insuficiente o falta el encabezado del proyecto de cuota.	Verifica que el llamador tenga discoveryengine.assistants.assist; asegúrate de que el permiso de OAuth incluya cloud-platform; agrega -H "X-Goog-User-Project: PROJECT_ID" si usas ADC.
HTTP 403 con Only the agent owner or an admin can run a draft of this agent.	El flujo de trabajo nunca se publicó y el llamador no es su propietario ni un administrador.	Publica el flujo de trabajo en Workflow Builder y compártelo con el llamador.
HTTP 403 con User does not have permission to access the Agent.	El flujo de trabajo no se comparte con el llamador.	Comparte el flujo de trabajo con el llamador.
El flujo de trabajo se comporta como una versión anterior	La llamada ejecuta la versión publicada, no los cambios no publicados en Workflow Builder.	Publica el flujo de trabajo.
La llamada al flujo de trabajo termina con answer.state FAILED y un error INTERNAL	El flujo de trabajo tiene un activador manual más otro activador o más de un activador manual.	Mantén un solo activador manual.

¿Qué sigue?

• Obtén resultados de la búsqueda de StreamAssist
• Referencia de la API de REST de streamAssist
• Descripción general de los agentes