Method: projects.locations.apps.assistantSessions.streamChatAiAssistant

Ejecuta Arc, el asistente de IA, para la sesión de asistente especificada en un formato de transmisión.

Solicitud HTTP

POST https://ces.googleapis.com/v1beta/{name=projects/*/locations/*/apps/*/assistantSessions/*}:streamChatAiAssistant

La URL usa la sintaxis de la transcodificación gRPC.

Parámetros de ruta

Parámetros
name

string

Obligatorio. Es la sesión del asistente que se usará para ejecutarlo. Formato: projects/{project}/locations/{location}/apps/{app}/assistantSessions/{assistantSession}

Cuerpo de la solicitud

El cuerpo de la solicitud contiene datos con la siguiente estructura:

Representación JSON
{
  "message": string,
  "attachedGcsUris": [
    string
  ],
  "contextToken": string,
  "confirmationResponse": {
    object (AssistantConfirmationResponse)
  },
  "clientCapabilities": [
    enum (StreamChatAiAssistantRequest.ClientCapability)
  ],
  "operationCompletedEvent": {
    object (OperationCompletedEvent)
  },
  "resumeFromSequenceNumber": string,
  "attachOnly": boolean
}
Campos
message

string

Es opcional. Es el mensaje que se enviará al agente de asistencia. Puede estar vacío cuando se establece confirmationResponse (responder una confirmación pendiente sin agregar un mensaje nuevo); se debe proporcionar al menos uno de los dos.

attachedGcsUris[]

string

Es opcional. Son los URIs de Cloud Storage para los archivos que subió el usuario durante este turno. Ejemplo: "gs://cxas-transient-uploads/uuid/prd.pdf"

contextToken

string

Es opcional. Es el token de contexto de integración opaco que devuelve SessionService.GenerateOnboardingSuggestions. Cuando se establece y aún está actualizado, el servidor reutiliza la instantánea de incorporación calculada para el estado cero en lugar de volver a calcularla para el primer turno de conversación.

confirmationResponse

object (AssistantConfirmationResponse)

Es opcional. Es la respuesta del usuario a un AssistantConfirmationRequest pendiente. Cuando se establece, el servidor reanuda el agente pausado con esta respuesta en lugar de (o además de) iniciar un nuevo turno de instrucción.

clientCapabilities[]

enum (StreamChatAiAssistantRequest.ClientCapability)

Es opcional. Son las funciones de respuesta que este cliente puede renderizar. El servidor solo emite eventos que necesitan una capacidad (p.ej., confirmationRequest) cuando se declara la capacidad, por lo que los clientes más antiguos nunca reciben eventos que descartarían de forma silenciosa.

operationCompletedEvent

object (OperationCompletedEvent)

Es opcional. Reanuda una sesión de asistente que se detuvo mientras esperaba que se completara una operación de larga duración administrada por el cliente.

resumeFromSequenceNumber

string (int64 format)

Es opcional. Cursor opcional para reanudar y volver a reproducir eventos de un turno en curso o completado.

attachOnly

boolean

Es opcional. Es una marca opcional para adjuntar a un turno en curso existente sin enviar un mensaje nuevo.

Cuerpo de la respuesta

Mensaje de respuesta para SessionService.StreamChatAiAssistant.

Si se ejecuta correctamente, el cuerpo de la respuesta contiene datos con la siguiente estructura:

Representación JSON
{
  "eventId": string,
  "eventTime": string,
  "uiEvent": {
    object (UiEvent)
  },
  "turnMetadata": {
    object (TurnMetadata)
  },
  "sequenceNumber": string,
  "turnInProgress": boolean,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "textChunk": string,
  "status": {
    object (Status)
  },
  "thoughtChunk": string,
  "toolCall": {
    object (ToolCall)
  },
  "toolResponse": {
    object (ToolResponse)
  },
  "artifactChunk": {
    object (ArtifactChunk)
  },
  "optionQuestionsChunk": {
    object (OptionQuestionsChunk)
  },
  "confirmationRequest": {
    object (AssistantConfirmationRequest)
  },
  "sessionCheckpoint": {
    object (SessionCheckpoint)
  },
  "resumeSnapshot": {
    object (TurnResumeSnapshot)
  },
  "handoff": {
    object (TurnHandoffEvent)
  },
  "turnCompleted": {
    object (TurnCompletedEvent)
  }
  // End of mutually exclusive fields.
}
Campos
eventId

string

Identificador único para el evento.

eventTime

string (Timestamp format)

Es la marca de tiempo de cuando ocurrió el evento.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

uiEvent

object (UiEvent)

Es opcional. Es la carga útil del evento de IU.

turnMetadata

object (TurnMetadata)

Es opcional. Metadatos a nivel de turno y categorización de intents

sequenceNumber

string (int64 format)

Es opcional. Es el número de secuencia que aumenta de forma monótona para este turno de sesión.

turnInProgress

boolean

Es opcional. Indica si el turno aún se está ejecutando de forma activa en segundo plano.

Es la carga útil del evento. La siguiente es una lista de campos mutuamente excluyentes. Como máximo, se establecerá uno de los campos en una respuesta:
textChunk

string

Token de texto (para transmitir las respuestas de Gemini palabra por palabra)

status

object (Status)

Actualización de estado simple.

thoughtChunk

string

Es el fragmento de texto de pensamiento (el razonamiento del agente antes de generar la respuesta).

toolCall

object (ToolCall)

Es el evento de ejecución de la llamada a la herramienta.

toolResponse

object (ToolResponse)

Es el evento de respuesta de la llamada a la herramienta.

artifactChunk

object (ArtifactChunk)

Evento de artefacto de documento generado (deltas de vista previa en vivo + puntero final de Cloud Storage).

optionQuestionsChunk

object (OptionQuestionsChunk)

Son las opciones de aclaración estructuradas que se analizan a partir del turno del modelo. La consola los renderiza como una lista de opciones seleccionables en lugar de texto sin procesar.

confirmationRequest

object (AssistantConfirmationRequest)

Es una confirmación de bloqueo en la que se detuvo el agente. El agente se reanuda cuando la respuesta llega en el confirmationResponse de una solicitud posterior. Solo se envía a los clientes que declararon la capacidad CONFIRMATION_CARDS en la solicitud.

sessionCheckpoint

object (SessionCheckpoint)

Es el evento de resumen de compactación o punto de control de la sesión que contiene la intención del usuario y el resumen continuo.

resumeSnapshot

object (TurnResumeSnapshot)

Es una repetición compactada de un turno en curso, que se envía como el primer evento de cada conexión o reanudación antes de cualquier evento en vivo. El cliente reemplaza cualquier estado renderizado de forma local para este turno por el contenido de la instantánea.

handoff

object (TurnHandoffEvent)

Le indica al cliente que se vuelva a conectar de forma silenciosa con resumeFromSequenceNumber: la tarea que entrega esta transmisión desaparecerá y el turno continuará en otro lugar. No es un error; la transmisión se completa con normalidad después de este evento.

turnCompleted

object (TurnCompletedEvent)

Finalizó el turno. Se envía como el último evento de cada turno, en la transmisión original y en cada transmisión adjunta o reanudada, para que los clientes puedan finalizar el turno con una señal explícita en lugar de inferirla del cierre de la transmisión.

Fin de los campos mutuamente excluyentes.

Permisos de autorización

Se necesita uno de los siguientes permisos de OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/ces

Para obtener más información, consulta Authentication Overview.

Permisos de IAM

Se requiere el siguiente permiso de IAM en el recurso name:

  • ces.assistantSessions.get

Para obtener más información, consulta la documentación de IAM.

AssistantConfirmationResponse

Es la respuesta del usuario a un AssistantConfirmationRequest, que se envía en la siguiente llamada a SessionService.StreamChatAiAssistant para reanudar el agente en pausa.

Representación JSON
{
  "confirmationId": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "confirmed": boolean,
  "answerText": string
  // End of mutually exclusive fields.
}
Campos
confirmationId

string

La AssistantConfirmationRequest.confirmation_id que se está respondiendo.

Es la respuesta del usuario. La siguiente es una lista de campos mutuamente excluyentes. Como máximo, se establecerá uno de los campos en una respuesta:
confirmed

boolean

Respuesta binaria: true aprueba la acción pausada, false la rechaza.

answerText

string

El submitText de la opción elegida o el texto de formato libre del usuario. Se cancela la acción pausada y se entrega el texto al agente para que actúe en consecuencia.

Fin de los campos mutuamente excluyentes.

StreamChatAiAssistantRequest.ClientCapability

Son las funciones de respuesta que puede declarar un cliente.

Enums
CLIENT_CAPABILITY_UNSPECIFIED Capacidad no especificada; se ignora.
CONFIRMATION_CARDS El cliente renderiza las tarjetas AssistantConfirmationRequest y las responde a través de confirmationResponse.
CLIENT_MANAGED_LRO El cliente administra las operaciones de larga duración fuera de banda sondeando la operación y enviando operationCompletedEvent para reanudar el turno. Si no se declara, el servidor administra el sondeo de LRO y completa el turno de forma intercalada.
PROJECT_SCOPE El cliente renderiza eventos de alcance del proyecto: tarjetas typedPayload, targetApp en llamadas a la herramienta y respuestas, targets en solicitudes de confirmación y touchedApps en la finalización del turno.

OperationCompletedEvent

Es el evento que envía el cliente o el trabajador en segundo plano para reanudar una sesión de asistente después de que se completa una operación de larga duración (LRO) asíncrona.

Representación JSON
{
  "operationName": string,
  "targetResourceName": string,
  "operationType": string,
  "status": string,
  "deduplicationToken": string,
  "error": {
    object (Status)
  },
  "metadata": {
    object
  }
}
Campos
operationName

string

Es el nombre del recurso de la operación (p.ej., operations/{op}).

targetResourceName

string

Es el recurso principal al que se orienta o que produce la operación (p.ej., ID de ejecución de la evaluación, ID de la app o ID del conjunto de datos).

operationType

string

Es el tipo de operación o el nombre de la herramienta (p.ej., "run_evaluation", "copy_app", "export_app").

status

string

Es el estado de la ejecución de la operación (p.ej., "SUCCEEDED", "FAILED", "CANCELLED").

deduplicationToken

string

Es un token de anulación de duplicación opcional (p.ej., UUID) para evitar la ejecución de turnos duplicados desde pestañas del navegador simultáneas.

error

object (Status)

Estado de error canónico opcional si la operación falló.

metadata

object (Struct format)

Metadatos de resultados estructurados opcionales (p.ej., pass_rate, total_examples, export_uri).

ArtifactChunk

Un fragmento transmitido de un artefacto de documento (p.ej., un TDD de Markdown) que genera el asistente. Los cambios de contenido se transmiten mientras se escribe el documento para que los clientes puedan renderizar una vista previa en vivo. El fragmento FINALIZED lleva el URI de Cloud Storage una vez que se conserva el archivo.

Representación JSON
{
  "artifactId": string,
  "displayName": string,
  "mimeType": string,
  "contentDelta": string,
  "gcsUri": string,
  "state": enum (ArtifactChunk.State),
  "targetApp": string
}
Campos
artifactId

string

Identificador del artefacto, estable en todos los fragmentos de un artefacto dentro de la transmisión.

displayName

string

Es el nombre del archivo que se muestra al usuario, p.ej., "hotel_booking_tdd.md". Se establece en STARTED (y se repite en FINALIZED).

mimeType

string

Es el tipo de medio de IANA del contenido del artefacto, p.ej., "text/markdown".

contentDelta

string

Contenido incremental de artefactos. Se establece en fragmentos DELTA.

gcsUri

string

Es el objeto de Cloud Storage en el que se conservó el artefacto. Se establece en los fragmentos FINALIZADOS.

state

enum (ArtifactChunk.State)

Es la posición del ciclo de vida de este fragmento.

targetApp

string

Solo salida. La app para la que se produjo este artefacto, cuando se produjo para una. Formato: projects/{project}/locations/{location}/apps/{app}

ArtifactChunk.State

Es la posición del ciclo de vida de este fragmento dentro del flujo del artefacto.

Enums
STATE_UNSPECIFIED Valor predeterminado sin usar.
STARTED El asistente comenzó a generar el artefacto.
DELTA Un incremento de contenido; se establece contentDelta.
FINALIZED Se conservó el artefacto; se estableció gcsUri.
FAILED Se produjo un error en la generación o la persistencia, por lo que no se guardó el artefacto.
CLOSED El documento terminó de transmitirse: su contenido se entregó por completo a través de fragmentos de contentDelta. Es posible que la persistencia continúe; se envía un fragmento FINALIZED con un gcsUri si se guarda el artefacto y cuando se guarda.

OptionQuestionsChunk

Son opciones de aclaración estructuradas que el asistente le pide al usuario que elija, traducidas del lado del servidor fuera del turno del modelo (el bloque de opciones se quita del texto transmitido y persistente). La consola renderiza una lista de opciones navegable con el teclado que se fija sobre el cuadro de redacción.

Representación JSON
{
  "questions": [
    {
      object (OptionQuestionsChunk.Question)
    }
  ]
}
Campos
questions[]

object (OptionQuestionsChunk.Question)

Las preguntas que se hicieron en este turno. Si hay más de una entrada, se activa el paginador "1 de N" de la consola.

OptionQuestionsChunk.Question

Una pregunta con sus opciones.

Representación JSON
{
  "question": string,
  "options": [
    {
      object (OptionQuestionsChunk.Option)
    }
  ]
}
Campos
question

string

Es el texto del encabezado de la pregunta.

options[]

object (OptionQuestionsChunk.Option)

Son las opciones que se pueden seleccionar, en orden de presentación.

OptionQuestionsChunk.Option

Una sola opción seleccionable.

Representación JSON
{
  "title": string,
  "details": string,
  "submitText": string
}
Campos
title

string

Título corto de la opción en texto sin formato (sin lenguaje de marcado ni numeración).

details

string

Detalles opcionales de compensación que se muestran como texto secundario.

submitText

string

Texto del mensaje opcional que se enviará cuando se elija la opción; el valor predeterminado es title cuando está vacío.

AssistantConfirmationRequest

Es una pregunta o confirmación de bloqueo que el asistente necesita que se responda antes de que pueda continuar una acción del agente. El agente que realiza la solicitud se pausa y se reanuda solo cuando la respuesta llega en un StreamChatAiAssistantRequest.confirmation_response posterior.

Representación JSON
{
  "confirmationId": string,
  "context": string,
  "positiveLabel": string,
  "negativeLabel": string,
  "questions": [
    {
      object (OptionQuestionsChunk.Question)
    }
  ],
  "tool": string,
  "agentName": string,
  "expireTime": string,
  "targets": [
    {
      object (AssistantConfirmationRequest.Target)
    }
  ]
}
Campos
confirmationId

string

Es el identificador que correlaciona esta solicitud con su respuesta. Es opaco para los clientes; se debe repetir de forma literal en la solicitud de respuesta.

context

string

Contexto que describe lo que se confirma (p.ej., la acción que el agente quiere realizar o la pregunta que necesita responder). Se renderiza como texto sin formato, no como Markdown.

positiveLabel

string

Es la etiqueta de la acción de aprobación de una confirmación binaria (p.ej., "Publicar"). No se establece cuando se propaga questions.

negativeLabel

string

Etiqueta para la acción de rechazo de una confirmación binaria (p.ej., "Todavía no"). No se establece cuando se propaga questions.

questions[]

object (OptionQuestionsChunk.Question)

Formulario de confirmación de opción múltiple. Cuando se completa, la tarjeta renderiza una lista de opciones seleccionables y el submitText de la opción elegida (o el texto de formato libre del usuario) se devuelve como AssistantConfirmationResponse.answer_text.

tool

string

Es el nombre de la llamada a la herramienta en la que se detuvo el agente (p.ej., "update_app") para el encabezado de la tarjeta. No se establece para preguntas puras.

agentName

string

Es la etiqueta de visualización del agente que generó la confirmación (p.ej., "Contract Architect") para el encabezado de la tarjeta.

expireTime

string (Timestamp format)

Es el tiempo después del cual ya no se puede responder esta confirmación. Una tarjeta vencida se renderiza como inactiva y el servidor rechaza la confirmación en el siguiente turno para que el agente pausado no espere de forma indefinida.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

targets[]

object (AssistantConfirmationRequest.Target)

Todo lo que cambiará la acción confirmada, para que la consola pueda renderizar "Actualizar 2 apps" y una insignia por app. Se deja vacío para las tarjetas heredadas de un solo objetivo.

AssistantConfirmationRequest.Target

Un recurso que cambiará la acción confirmada.

Representación JSON
{
  "resource": string,
  "displayName": string,
  "action": string,
  "targetApp": string
}
Campos
resource

string

Es el recurso que cambiará, como un nombre de recurso completo.

displayName

string

Es el nombre visible del recurso o la app para la tarjeta.

action

string

La acción, p.ej., CREATE, UPDATE, DELETE, COPY, LINK.

targetApp

string

Es la app a la que pertenece el recurso o está vacía para una acción con alcance de ubicación, como crear una app. Formato: projects/{project}/locations/{location}/apps/{app}

TurnResumeSnapshot

Es una repetición compactada de un turno en curso: todo lo necesario para renderizar el resultado visible del turno hasta el momento, además de la posición desde la que continúan los eventos en vivo.

Representación JSON
{
  "turnId": string,
  "resolvedSequenceNumber": string,
  "events": [
    {
      object (StreamChatAiAssistantResponse)
    }
  ],
  "orphanDeadlineTime": string
}
Campos
turnId

string

Identifica el turno al que se adjunta.

resolvedSequenceNumber

string (int64 format)

Es la posición que representa esta instantánea. Los eventos en vivo siguen con un sequenceNumber estrictamente mayor que este. Cuando es inferior al resumeFromSequenceNumber que solicitó el cliente, el progreso vaciado se retrasa con respecto a lo que el cliente ya renderizó: el cliente debe descartar el contenido renderizado de este turno más allá de esta posición antes de aplicar la instantánea.

events[]

object (StreamChatAiAssistantResponse)

Son eventos compactados que reconstruyen el resultado visible del turno, en orden de renderización, con las mismas formas de eventos que la transmisión en vivo.

orphanDeadlineTime

string (Timestamp format)

Cuándo se cerrará el turno si no queda ningún cliente conectado.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

TurnHandoffEvent

Se emite antes de que esta tarea deje de entregar la transmisión a mitad del turno (p.ej., un reinicio del servidor). El estado del turno se conserva; una reconexión que lleva resumeFromSequenceNumber lo continúa en otra tarea.

Representación JSON
{
  "turnId": string,
  "reason": enum (TurnHandoffEvent.Reason)
}
Campos
turnId

string

Identifica el turno que se reanudará.

reason

enum (TurnHandoffEvent.Reason)

Por qué se transfiere la transmisión

TurnHandoffEvent.Reason

Por qué se transfiere la transmisión

Enums
REASON_UNSPECIFIED Sin especificar.
SERVER_RESTART La tarea de entrega se está cerrando (envío de versión o reprogramación).

TurnCompletedEvent

Es el evento de terminal de un turno (consulta StreamChatAiAssistantResponse.turn_completed).

Representación JSON
{
  "turnId": string,
  "reason": enum (TurnCompletedEvent.Reason),
  "finalSequenceNumber": string,
  "touchedApps": [
    string
  ]
}
Campos
turnId

string

Es el identificador del giro que finalizó. Coincide con TurnResumeSnapshot.turn_id y ActiveTurnInfo.turn_id.

reason

enum (TurnCompletedEvent.Reason)

Por qué finalizó el turno

finalSequenceNumber

string (int64 format)

Es el número de secuencia del último evento que produjo el turno. Un cliente cuyo cursor esté más abajo se perdió contenido y debería volver a cargar la sesión para verlo.

touchedApps[]

string

Las apps que se modificaron o se orientaron en este turno, de modo que la consola pueda actualizar exactamente los almacenes de esas apps. Solo sesiones con permiso de proyecto. Formato: projects/{project}/locations/{location}/apps/{app}

TurnCompletedEvent.Reason

Por qué finalizó el turno, de modo que un cliente que se unió tarde pueda expresar el resultado en lugar de adivinarlo a partir de una transmisión vacía.

Enums
REASON_UNSPECIFIED Sin especificar.
COMPLETED El turno se ejecutó hasta completarse; la sesión conserva su resultado confirmado.
ABANDONED Ninguna tarea impulsaba el turno, se selló a un parcial confirmado y no se puede continuar.
RESUME_UNAVAILABLE Este servidor no admite adjuntar ni reanudar la sesión, por lo que no se hizo un seguimiento de nada. En su lugar, el cliente debería volver a cargar la sesión.

TurnMetadata

Metadatos a nivel de turno y categorización de intents

Representación JSON
{
  "contractRelated": boolean,
  "contractFinalized": boolean,
  "contractStreamingPhase": enum (TurnMetadata.ContractStreamingPhase),
  "contractDraftComplete": boolean
}
Campos
contractFinalized

boolean

Se establece en el evento de artefacto final de un turno cuyo borrador de contrato se publicó (se activó una revisión). Terminal para el flujo de aclaración de este borrador: contractProgress es autoritativo y completo.

contractStreamingPhase

enum (TurnMetadata.ContractStreamingPhase)

Se establece solo en las estimaciones de progreso en curso emitidas mientras se transmite una barrera de artefactos de contrato y en el evento de inicio de turno de revisión. No se establece en las cargas útiles autorizadas.

contractDraftComplete

boolean

Se establece en el evento de terminal de un borrador de contrato en el que se resuelve cada marcador de posición (contractProgress es 100%), independientemente de si se publicó el borrador. Los clientes completan y descartan la visualización del progreso del contrato en él; la publicación se informa por separado mediante contractFinalized.

TurnMetadata.ContractStreamingPhase

Es la fase de transmisión de la carga útil del progreso del contrato.

Enums
CONTRACT_STREAMING_PHASE_UNSPECIFIED La carga útil es autoritativa (se calcula a partir de un documento de contrato completo, una instantánea persistente o el estado previo al borrador). Los clientes deben reemplazar cualquier progreso recibido anteriormente por este.
DRAFTING Se está transmitiendo un borrador inicial del contrato. contractProgress es una estimación en curso: no disminuye dentro de un límite de artefacto, tiene un límite inferior al rango de autoridad y pillarBreakdowns tiene totalItemCount == 0 para marcar los estados estimados de los pilares.
REVISING Se está transmitiendo una revisión de un contrato existente (por ejemplo, después de un envío de anotaciones). Tiene la misma semántica de estimación que DRAFTING.