Method: projects.locations.apps.assistantSessions.streamChatAiAssistant

Exécute Arc, l'assistant IA, pour la session d'assistant spécifiée en mode streaming.

Requête HTTP

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

L'URL utilise la syntaxe de transcodage gRPC.

Paramètres de chemin d'accès

Paramètres
name

string

Obligatoire. Session de l'assistant à utiliser pour exécuter l'assistant. Format : projects/{project}/locations/{location}/apps/{app}/assistantSessions/{assistantSession}

Corps de la requête

Le corps de la requête contient des données présentant la structure suivante :

Représentation JSON 
{
  "message": string,
  "attachedGcsUris": [
    string
  ],
  "contextToken": string,
  "confirmationResponse": {
    object (AssistantConfirmationResponse)
  },
  "clientCapabilities": [
    enum (StreamChatAiAssistantRequest.ClientCapability)
  ],
  "operationCompletedEvent": {
    object (OperationCompletedEvent)
  },
  "resumeFromSequenceNumber": string,
  "attachOnly": boolean
}
Champs
message

string

Facultatif. Message à envoyer à l'agent de l'assistant. Peut être vide lorsque confirmationResponse est défini (réponse à une confirmation en attente sans ajouter de nouveau message). Au moins l'un des deux doit être fourni.
attachedGcsUris[]

string

Facultatif. URI Cloud Storage des fichiers importés par l'utilisateur au cours de ce tour. Exemple : "gs://cxas-transient-uploads/uuid/prd.pdf"
contextToken

string

Facultatif. Jeton de contexte d'intégration opaque renvoyé par SessionService.GenerateOnboardingSuggestions. Lorsqu'il est défini et toujours actualisé, le serveur réutilise l'instantané d'intégration calculé pour l'état zéro au lieu de le recalculer pour le premier tour de conversation.
confirmationResponse

object (AssistantConfirmationResponse)

Facultatif. Réponse de l'utilisateur à un AssistantConfirmationRequest en attente. Lorsqu'il est défini, le serveur réactive l'agent mis en pause avec cette réponse au lieu de (ou en plus de) démarrer un nouveau tour de requête.
clientCapabilities[]

enum (StreamChatAiAssistantRequest.ClientCapability)

Facultatif. Fonctionnalités de réponse que ce client peut afficher. Le serveur n'émet que les événements qui nécessitent une fonctionnalité (par exemple, confirmationRequest) lorsque la fonctionnalité est déclarée. Ainsi, les anciens clients ne reçoivent jamais d'événements qu'ils supprimeraient sans notification.
operationCompletedEvent

object (OperationCompletedEvent)

Facultatif. Reprend une session d'assistant mise en pause en attendant la fin d'une opération de longue durée gérée par le client.
resumeFromSequenceNumber

string (int64 format)

Facultatif. Curseur facultatif pour reprendre et rejouer les événements d'un tour en cours ou terminé.
attachOnly

boolean

Facultatif. Option facultative permettant d'associer un tour en cours sans envoyer de nouveau message.

Corps de la réponse

Message de réponse pour SessionService.StreamChatAiAssistant.

Si la requête aboutit, le corps de la réponse contient des données qui ont la structure suivante :

Représentation 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.
}
Champs
eventId

string

Identifiant unique de l'événement.
eventTime

string (Timestamp format)

Code temporel de l'événement.

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
uiEvent

object (UiEvent)

Facultatif. Charge utile de l'événement d'UI.
turnMetadata

object (TurnMetadata)

Facultatif. Métadonnées au niveau du tour de parole et catégorisation des intents.
sequenceNumber

string (int64 format)

Facultatif. Numéro de séquence à croissance monotone pour ce tour de session.
turnInProgress

boolean

Facultatif. Indique si le tour est toujours en cours d'exécution en arrière-plan.
Charge utile de l'événement. Voici une liste de champs mutuellement exclusifs. Au maximum, un des champs sera défini dans une réponse :
textChunk

string

Jeton de texte (pour diffuser les réponses de Gemini mot par mot).
status

object (Status)

Mise à jour de l'état simple.
thoughtChunk

string

Fragment de texte de réflexion (raisonnement de l'agent avant de générer une réponse).
toolCall

object (ToolCall)

Événement d'exécution d'appel d'outil.
toolResponse

object (ToolResponse)

Événement de réponse à un appel d'outil.
artifactChunk

object (ArtifactChunk)

Événement d'artefact de document généré (deltas d'aperçu en direct + pointeur Cloud Storage final).
optionQuestionsChunk

object (OptionQuestionsChunk)

Options de clarification structurées analysées à partir du tour de modèle. La console les affiche sous la forme d'une liste d'options sélectionnables au lieu de texte brut.
confirmationRequest

object (AssistantConfirmationRequest)

Confirmation bloquante sur laquelle l'agent s'est arrêté. L'agent reprend lorsque la réponse arrive sur le confirmationResponse d'une requête ultérieure. Envoyé uniquement aux clients ayant déclaré la fonctionnalité CONFIRMATION_CARDS dans la requête.
sessionCheckpoint

object (SessionCheckpoint)

Événement de récapitulatif de point de contrôle/compactage de session contenant l'intention utilisateur et un résumé glissant.
resumeSnapshot

object (TurnResumeSnapshot)

Replay compacté d'un tour en cours, envoyé en tant que premier événement de chaque association ou reprise avant tout événement en direct. Le client remplace tout état affiché localement pour ce tour par le contenu de l'instantané.
handoff

object (TurnHandoffEvent)

Indique au client de se reconnecter de manière silencieuse avec resumeFromSequenceNumber : la tâche diffusant ce flux va disparaître et le tour se poursuivra ailleurs. Il ne s'agit pas d'une erreur. Le flux se termine normalement après cet événement.
turnCompleted

object (TurnCompletedEvent)

Le tour est terminé. Envoyé en tant que dernier événement de chaque tour, sur le flux d'origine et sur chaque flux associé ou repris, afin que les clients puissent mettre fin au tour sur un signal explicite au lieu de le déduire de la fermeture du flux.
Fin des champs mutuellement exclusifs.

Niveaux d'accès des autorisations

Nécessite l'un des niveaux d'accès OAuth suivants :

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

Pour plus d'informations, consultez la page Authentication Overview.

Autorisations IAM

Nécessite l'autorisation IAM suivante sur la ressource name :

  • ces.assistantSessions.get

Pour en savoir plus, consultez la documentation IAM.

AssistantConfirmationResponse

Réponse de l'utilisateur à un AssistantConfirmationRequest, envoyée lors de l'appel SessionService.StreamChatAiAssistant suivant pour réactiver l'agent mis en pause.

Représentation 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.
}
Champs
confirmationId

string

La AssistantConfirmationRequest.confirmation_id à laquelle il est répondu.
La réponse de l'utilisateur. Voici une liste de champs mutuellement exclusifs. Au maximum, un des champs sera défini dans une réponse :
confirmed

boolean

Réponse binaire : "true" approuve l'action mise en veille, "false" la refuse.
answerText

string

"submitText" de l'option choisie ou texte libre de l'utilisateur. L'action suspendue est annulée et le texte est transmis à l'agent pour qu'il agisse.
Fin des champs mutuellement exclusifs.

StreamChatAiAssistantRequest.ClientCapability

Fonctionnalités de réponse qu'un client peut déclarer.

Enums
CLIENT_CAPABILITY_UNSPECIFIED Capacité non spécifiée ; ignorée.
CONFIRMATION_CARDS Le client affiche les fiches AssistantConfirmationRequest et y répond via confirmationResponse.
CLIENT_MANAGED_LRO Le client gère les opérations de longue durée hors bande en interrogeant l'opération et en envoyant operationCompletedEvent pour reprendre le tour. Si elle n'est pas déclarée, le serveur gère l'interrogation LRO et termine le tour de manière intégrée.
PROJECT_SCOPE Le client affiche les événements au niveau du projet : cartes typedPayload, targetApp sur les appels d'outils et les réponses, targets sur les demandes de confirmation et touchedApps à la fin du tour.

OperationCompletedEvent

Événement envoyé par le client ou le nœud de calcul en arrière-plan pour reprendre une session de l'assistant une fois qu'une opération de longue durée (LRO) asynchrone est terminée.

Représentation JSON 
{
  "operationName": string,
  "targetResourceName": string,
  "operationType": string,
  "status": string,
  "deduplicationToken": string,
  "error": {
    object (Status)
  },
  "metadata": {
    object
  }
}
Champs
operationName

string

Nom de la ressource d'opération (par exemple, operations/{op}).
targetResourceName

string

Ressource principale ciblée ou produite par l'opération (par exemple, ID d'exécution de l'évaluation, ID d'application, ID d'ensemble de données).
operationType

string

Type d'opération ou nom de l'outil (par exemple, "run_evaluation", "copy_app", "export_app").
status

string

État de l'exécution de l'opération (par exemple, "SUCCEEDED", "FAILED", "CANCELLED").
deduplicationToken

string

Jeton de déduplication facultatif (par exemple, UUID) pour empêcher l'exécution de tours en double à partir d'onglets de navigateur simultanés.
error

object (Status)

État d'erreur canonique facultatif si l'opération a échoué.
metadata

object (Struct format)

Métadonnées de résultat structurées facultatives (par exemple, pass_rate, total_examples, export_uri).

ArtifactChunk

Fragment diffusé d'un artefact de document (par exemple, un TDD Markdown) généré par l'assistant. Les deltas de contenu sont diffusés pendant l'écriture du document afin que les clients puissent afficher un aperçu en direct. Le fragment FINALIZED contient l'URI Cloud Storage une fois que le fichier a été conservé.

Représentation JSON 
{
  "artifactId": string,
  "displayName": string,
  "mimeType": string,
  "contentDelta": string,
  "gcsUri": string,
  "state": enum (ArtifactChunk.State),
  "targetApp": string
}
Champs
artifactId

string

Identifiant de l'artefact, stable pour tous les fragments d'un artefact dans le flux.
displayName

string

Nom du fichier présenté à l'utilisateur, par exemple "hotel_booking_tdd.md". Défini sur STARTED (et répété sur FINALIZED).
mimeType

string

Type de média IANA du contenu de l'artefact, par exemple "text/markdown".
contentDelta

string

Contenu d'artefact incrémentiel. Défini sur les fragments DELTA.
gcsUri

string

Objet Cloud Storage dans lequel l'artefact a été conservé. Définie sur les fragments FINALISÉS.
state

enum (ArtifactChunk.State)

Position de ce fragment dans le cycle de vie.
targetApp

string

Uniquement en sortie. L'application pour laquelle cet artefact a été produit, le cas échéant. Format : projects/{project}/locations/{location}/apps/{app}

ArtifactChunk.State

Position du cycle de vie de ce fragment dans le flux de l'artefact.

Enums
STATE_UNSPECIFIED Valeur par défaut non utilisée.
STARTED L'assistant a commencé à générer l'artefact.
DELTA Incrément de contenu ; contentDelta est défini.
FINALIZED L'artefact a été conservé. gcsUri est défini.
FAILED Échec de la génération ou de la persistance ; l'artefact n'a pas été enregistré.
CLOSED Le streaming du document est terminé : son contenu a été entièrement diffusé via des fragments contentDelta. La persistance peut toujours suivre : un fragment FINALIZED avec un gcsUri est envoyé si et quand l'artefact est enregistré.

OptionQuestionsChunk

Options de clarification structurées que l'assistant demande à l'utilisateur de choisir, transduites côté serveur à partir du tour du modèle (le bloc d'options est supprimé du texte diffusé et conservé). La console affiche une liste d'options ancrée au-dessus de l'éditeur, dans laquelle vous pouvez naviguer à l'aide du clavier.

Représentation JSON 
{
  "questions": [
    {
      object (OptionQuestionsChunk.Question)
    }
  ]
}
Champs
questions[]

object (OptionQuestionsChunk.Question)

Questions posées lors de ce tour. Si plusieurs entrées sont disponibles, le pager "1 sur N " de la console s'affiche.

OptionQuestionsChunk.Question

Une question avec ses options.

Représentation JSON 
{
  "question": string,
  "options": [
    {
      object (OptionQuestionsChunk.Option)
    }
  ]
}
Champs
question

string

Texte de l'en-tête de la question.
options[]

object (OptionQuestionsChunk.Option)

Options sélectionnables, dans l'ordre de présentation.

OptionQuestionsChunk.Option

Une seule option sélectionnable.

Représentation JSON 
{
  "title": string,
  "details": string,
  "submitText": string
}
Champs
title

string

Titre court de l'option en texte brut (pas de Markdown, pas de numérotation).
details

string

Détails facultatifs sur les compromis affichés sous forme de texte secondaire.
submitText

string

Texte du message facultatif à envoyer lorsque l'option est choisie. La valeur par défaut est title lorsqu'elle est vide.

AssistantConfirmationRequest

Question ou confirmation bloquante à laquelle l'assistant doit répondre avant qu'une action de l'agent puisse se poursuivre. L'agent demandeur est mis en pause et ne reprend que lorsque la réponse arrive sur un StreamChatAiAssistantRequest.confirmation_response ultérieur.

Représentation JSON 
{
  "confirmationId": string,
  "context": string,
  "positiveLabel": string,
  "negativeLabel": string,
  "questions": [
    {
      object (OptionQuestionsChunk.Question)
    }
  ],
  "tool": string,
  "agentName": string,
  "expireTime": string,
  "targets": [
    {
      object (AssistantConfirmationRequest.Target)
    }
  ]
}
Champs
confirmationId

string

Identifiant mettant en corrélation cette requête avec sa réponse. Opaque pour les clients ; doit être répété textuellement dans la requête de réponse.
context

string

Contexte décrivant ce qui est confirmé (par exemple, l'action que l'agent souhaite effectuer ou la question à laquelle il doit répondre). Affiché en texte brut, et non en Markdown.
positiveLabel

string

Libellé de l'action d'approbation d'une confirmation binaire (par exemple, "Publier"). Non défini lorsque questions est renseigné.
negativeLabel

string

Libellé de l'action de refus d'une confirmation binaire (par exemple, "Pas encore"). Non défini lorsque questions est renseigné.
questions[]

object (OptionQuestionsChunk.Question)

Formulaire de confirmation à choix multiples. Lorsqu'elle est renseignée, la fiche affiche une liste d'options sélectionnables, et le submitText de l'option choisie (ou le texte libre de l'utilisateur) est renvoyé sous la forme AssistantConfirmationResponse.answer_text.
tool

string

Nom de l'appel d'outil sur lequel l'agent s'est arrêté (par exemple, "update_app"), pour l'en-tête de la fiche. Non défini pour les questions pures.
agentName

string

Libellé d'affichage de l'agent qui a déclenché la confirmation (par exemple, "Contract Architect"), pour l'en-tête de la fiche.
expireTime

string (Timestamp format)

Délai après lequel il n'est plus possible de répondre à cette confirmation. Une carte expirée est considérée comme inactive, et le serveur refuse la confirmation au tour suivant afin que l'agent en pause n'attende pas indéfiniment.

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
targets[]

object (AssistantConfirmationRequest.Target)

Tout ce que l'action confirmée modifiera, afin que la console puisse afficher "Mettre à jour 2 applications" et un badge par application. Vide pour les anciennes fiches à cible unique.

AssistantConfirmationRequest.Target

Une ressource que l'action confirmée va modifier.

Représentation JSON 
{
  "resource": string,
  "displayName": string,
  "action": string,
  "targetApp": string
}
Champs
resource

string

Ressource qui sera modifiée, sous la forme d'un nom de ressource complet.
displayName

string

Nom à afficher de la ressource ou de l'application, pour la fiche.
action

string

L'action, par exemple CREATE, UPDATE, DELETE, COPY, LINK.
targetApp

string

Application à laquelle appartient la ressource, ou vide pour une action limitée à un emplacement, comme la création d'une application. Format : projects/{project}/locations/{location}/apps/{app}

SessionCheckpoint

Point de contrôle de session contenant l'intention utilisateur inférée pour le titre de la session et l'UI.

Représentation JSON 
{
  "userIntent": string
}
Champs
userIntent

string

Objectif ou sujet de l'utilisateur déduit pour la session (par exemple, "Créer un agent d'assistance pour l'e-commerce").

TurnResumeSnapshot

Une rediffusion compactée d'un tour en cours : tout ce qui est nécessaire pour afficher la sortie visible du tour jusqu'à présent, ainsi que la position à partir de laquelle les événements en direct continuent.

Représentation JSON 
{
  "turnId": string,
  "resolvedSequenceNumber": string,
  "events": [
    {
      object (StreamChatAiAssistantResponse)
    }
  ],
  "orphanDeadlineTime": string
}
Champs
turnId

string

Identifie le tour auquel l'élément est associé.
resolvedSequenceNumber

string (int64 format)

Position représentée par cet instantané. Les événements en direct suivent avec un sequenceNumber strictement supérieur à celui-ci. Lorsqu'elle est inférieure à la valeur resumeFromSequenceNumber demandée par le client, la progression vidée est en retard par rapport à ce que le client a déjà affiché : le client doit supprimer le contenu affiché de ce tour au-delà de cette position avant d'appliquer l'instantané.
events[]

object (StreamChatAiAssistantResponse)

Événements compactés reconstruisant la sortie visible du tour, dans l'ordre de rendu, en utilisant les mêmes formes d'événement que le streaming en direct.
orphanDeadlineTime

string (Timestamp format)

Date à laquelle le tour sera arrêté si aucun client ne reste associé.

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

TurnHandoffEvent

Émis avant que cette tâche n'arrête de diffuser le flux en cours de tour (par exemple, un redémarrage du serveur). L'état du tour est conservé. Une reconnexion contenant resumeFromSequenceNumber le poursuit sur une autre tâche.

Représentation JSON 
{
  "turnId": string,
  "reason": enum (TurnHandoffEvent.Reason)
}
Champs
turnId

string

Identifie le tour à reprendre.
reason

enum (TurnHandoffEvent.Reason)

Raison pour laquelle le flux est transféré.

TurnHandoffEvent.Reason

Raison pour laquelle le flux est transféré.

Enums
REASON_UNSPECIFIED Non spécifié.
SERVER_RESTART La tâche de diffusion est en cours d'arrêt (push de version ou reprogrammation).

TurnCompletedEvent

Événement terminal d'un tour (voir StreamChatAiAssistantResponse.turn_completed).

Représentation JSON 
{
  "turnId": string,
  "reason": enum (TurnCompletedEvent.Reason),
  "finalSequenceNumber": string,
  "touchedApps": [
    string
  ]
}
Champs
turnId

string

Identifiant du virage qui s'est terminé. Correspond à TurnResumeSnapshot.turn_id et ActiveTurnInfo.turn_id.
reason

enum (TurnCompletedEvent.Reason)

Pourquoi le tour s'est terminé.
finalSequenceNumber

string (int64 format)

Numéro de séquence du dernier événement produit par le tour. Un client dont le curseur est plus bas a manqué du contenu et doit recharger la session pour le voir.
touchedApps[]

string

Applications ciblées ou modifiées lors de cette session, afin que la console puisse actualiser précisément les magasins de ces applications. Sessions limitées au projet uniquement. Format : projects/{project}/locations/{location}/apps/{app}

TurnCompletedEvent.Reason

Raison pour laquelle le tour s'est terminé, afin qu'un client qui s'est connecté tardivement puisse formuler le résultat au lieu de le deviner à partir d'un flux vide.

Enums
REASON_UNSPECIFIED Non spécifié.
COMPLETED Le tour s'est terminé. La session contient sa sortie validée.
ABANDONED Aucune tâche ne pilotait plus le tour ; il a été scellé à un partiel validé et ne peut pas être poursuivi.
RESUME_UNAVAILABLE Ce serveur ne gère pas l'association ni la reprise de la session. Rien n'a donc été suivi. Le client doit plutôt actualiser la session.

UiEvent

Représente une charge utile d'événement d'UI.

Représentation JSON 
{
  "mimeType": string,
  "jsonPayload": string
}
Champs
mimeType

string

Type de média (type MIME) indiquant le format de la charge utile de l'événement d'interface utilisateur (par exemple, "application/json+a2ui").
jsonPayload

string

Charge utile JSON représentant la surface A2UI.

TurnMetadata

Métadonnées au niveau du tour de parole et catégorisation des intents.

Représentation JSON 
{
  "contractRelated": boolean,
  "contractFinalized": boolean,
  "contractStreamingPhase": enum (TurnMetadata.ContractStreamingPhase),
  "contractDraftComplete": boolean
}
Champs
contractFinalized

boolean

Défini sur l'événement d'artefact final d'un tour dont le brouillon de contrat a été publié (une révision a été activée). Terminal pour le flux de clarification de ce brouillon : contractProgress est officiel et complet.
contractStreamingPhase

enum (TurnMetadata.ContractStreamingPhase)

Défini uniquement sur les estimations de progression en cours émises pendant la diffusion d'un artefact de contrat et sur l'événement revision-turn-start. Non défini sur les charges utiles de référence.
contractDraftComplete

boolean

Défini sur l'événement de terminal d'un brouillon de contrat dont chaque espace réservé est résolu (contractProgress est de 100 %), que le brouillon ait été publié ou non. Les clients complètent et ignorent l'affichage de la progression du contrat. La publication est signalée séparément par contractFinalized.

TurnMetadata.ContractStreamingPhase

Phase de streaming de la charge utile de progression du contrat.

Enums
CONTRACT_STREAMING_PHASE_UNSPECIFIED La charge utile fait autorité (calculée à partir d'un document de contrat complet, d'un instantané persistant ou de l'état de pré-brouillon). Les clients doivent remplacer toute progression précédemment reçue par celle-ci.
DRAFTING Un brouillon de contrat initial est en cours de diffusion. contractProgress est une estimation en cours : non décroissante dans une limite d'artefact, plafonnée en dessous de la plage faisant autorité, avec pillarBreakdowns portant totalItemCount == 0 pour marquer les états de pilier estimés.
REVISING Une révision d'un contrat existant est en cours de diffusion (par exemple, après l'envoi d'une annotation). Même sémantique d'estimation que DRAFTING.