- Solicitud HTTP
- Parámetros de ruta
- Cuerpo de la solicitud
- Cuerpo de la respuesta
- Permisos de autorización
- Permisos de IAM
- AssistantConfirmationResponse
- StreamChatAiAssistantRequest.ClientCapability
- OperationCompletedEvent
- ArtifactChunk
- ArtifactChunk.State
- OptionQuestionsChunk
- OptionQuestionsChunk.Question
- OptionQuestionsChunk.Option
- AssistantConfirmationRequest
- AssistantConfirmationRequest.Target
- TurnResumeSnapshot
- TurnHandoffEvent
- TurnHandoffEvent.Reason
- TurnCompletedEvent
- TurnCompletedEvent.Reason
- TurnMetadata
- TurnMetadata.ContractStreamingPhase
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 |
Obligatorio. Es la sesión del asistente que se usará para ejecutarlo. Formato: |
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 ( |
| Campos | |
|---|---|
message |
Es opcional. Es el mensaje que se enviará al agente de asistencia. Puede estar vacío cuando se establece |
attachedGcsUris[] |
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 |
Es opcional. Es el token de contexto de integración opaco que devuelve |
confirmationResponse |
Es opcional. Es la respuesta del usuario a un |
clientCapabilities[] |
Es opcional. Son las funciones de respuesta que este cliente puede renderizar. El servidor solo emite eventos que necesitan una capacidad (p.ej., |
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 |
Es opcional. Cursor opcional para reanudar y volver a reproducir eventos de un turno en curso o completado. |
attachOnly |
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 ( |
| Campos | |
|---|---|
eventId |
Identificador único para el evento. |
eventTime |
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: |
uiEvent |
Es opcional. Es la carga útil del evento de IU. |
turnMetadata |
Es opcional. Metadatos a nivel de turno y categorización de intents |
sequenceNumber |
Es opcional. Es el número de secuencia que aumenta de forma monótona para este turno de sesión. |
turnInProgress |
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 |
Token de texto (para transmitir las respuestas de Gemini palabra por palabra) |
status |
Actualización de estado simple. |
thoughtChunk |
Es el fragmento de texto de pensamiento (el razonamiento del agente antes de generar la respuesta). |
toolCall |
Es el evento de ejecución de la llamada a la herramienta. |
toolResponse |
Es el evento de respuesta de la llamada a la herramienta. |
artifactChunk |
Evento de artefacto de documento generado (deltas de vista previa en vivo + puntero final de Cloud Storage). |
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 |
Es una confirmación de bloqueo en la que se detuvo el agente. El agente se reanuda cuando la respuesta llega en el |
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 |
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 |
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 |
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-platformhttps://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 |
La |
| 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 |
Respuesta binaria: true aprueba la acción pausada, false la rechaza. |
answerText |
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 ( |
| Campos | |
|---|---|
operationName |
Es el nombre del recurso de la operación (p.ej., |
targetResourceName |
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 |
Es el tipo de operación o el nombre de la herramienta (p.ej., "run_evaluation", "copy_app", "export_app"). |
status |
Es el estado de la ejecución de la operación (p.ej., "SUCCEEDED", "FAILED", "CANCELLED"). |
deduplicationToken |
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 |
Estado de error canónico opcional si la operación falló. |
metadata |
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 ( |
| Campos | |
|---|---|
artifactId |
Identificador del artefacto, estable en todos los fragmentos de un artefacto dentro de la transmisión. |
displayName |
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 |
Es el tipo de medio de IANA del contenido del artefacto, p.ej., "text/markdown". |
contentDelta |
Contenido incremental de artefactos. Se establece en fragmentos DELTA. |
gcsUri |
Es el objeto de Cloud Storage en el que se conservó el artefacto. Se establece en los fragmentos FINALIZADOS. |
state |
Es la posición del ciclo de vida de este fragmento. |
targetApp |
Solo salida. La app para la que se produjo este artefacto, cuando se produjo para una. Formato: |
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 ( |
| Campos | |
|---|---|
questions[] |
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 ( |
| Campos | |
|---|---|
question |
Es el texto del encabezado de la pregunta. |
options[] |
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 |
Título corto de la opción en texto sin formato (sin lenguaje de marcado ni numeración). |
details |
Detalles opcionales de compensación que se muestran como texto secundario. |
submitText |
Texto del mensaje opcional que se enviará cuando se elija la opción; el valor predeterminado es |
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 ( |
| Campos | |
|---|---|
confirmationId |
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 |
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 |
Es la etiqueta de la acción de aprobación de una confirmación binaria (p.ej., "Publicar"). No se establece cuando se propaga |
negativeLabel |
Etiqueta para la acción de rechazo de una confirmación binaria (p.ej., "Todavía no"). No se establece cuando se propaga |
questions[] |
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 |
tool |
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 |
Es la etiqueta de visualización del agente que generó la confirmación (p.ej., |
expireTime |
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: |
targets[] |
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 |
Es el recurso que cambiará, como un nombre de recurso completo. |
displayName |
Es el nombre visible del recurso o la app para la tarjeta. |
action |
La acción, p.ej., |
targetApp |
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: |
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 ( |
| Campos | |
|---|---|
turnId |
Identifica el turno al que se adjunta. |
resolvedSequenceNumber |
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[] |
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 |
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: |
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 ( |
| Campos | |
|---|---|
turnId |
Identifica el turno que se reanudará. |
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 ( |
| Campos | |
|---|---|
turnId |
Es el identificador del giro que finalizó. Coincide con TurnResumeSnapshot.turn_id y ActiveTurnInfo.turn_id. |
reason |
Por qué finalizó el turno |
finalSequenceNumber |
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[] |
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: |
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 ( |
| Campos | |
|---|---|
contractRelated |
Indica si este turno del asistente estuvo relacionado con un contrato (p.ej., redacción, alineación, extracción o revisión de contratos). |
contractFinalized |
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 |
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 |
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. |