Method: projects.locations.apps.assistantSessions.streamChatAiAssistant

Esegue Arc, l'assistente AI, per la sessione dell'assistente specificata in modalità di streaming.

Richiesta HTTP

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

L'URL utilizza la sintassi di transcodifica gRPC.

Parametri di percorso

Parametri
name

string

Obbligatorio. La sessione dell'assistente da utilizzare per eseguire l'assistente. Formato: projects/{project}/locations/{location}/apps/{app}/assistantSessions/{assistantSession}

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

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

string

Facoltativo. Il messaggio da inviare all'agente assistente. Può essere vuoto quando è impostato confirmationResponse (risposta a una conferma in attesa senza aggiungere un nuovo messaggio); deve essere fornito almeno uno dei due.
attachedGcsUris[]

string

Facoltativo. URI Cloud Storage per i file caricati dall'utente durante questo turno. Esempio: "gs://cxas-transient-uploads/uuid/prd.pdf"
contextToken

string

Facoltativo. Token di contesto di onboarding opaco restituito da SessionService.GenerateOnboardingSuggestions. Se impostato e ancora aggiornato, il server riutilizza lo snapshot di onboarding calcolato per lo stato zero anziché ricalcolarlo per il primo turno di conversazione.
confirmationResponse

object (AssistantConfirmationResponse)

Facoltativo. La risposta dell'utente a un AssistantConfirmationRequest in attesa. Se impostato, il server riprende l'agente in pausa con questa risposta anziché (o in aggiunta a) avviare un nuovo turno di prompt.
clientCapabilities[]

enum (StreamChatAiAssistantRequest.ClientCapability)

Facoltativo. Funzionalità di risposta che questo client può visualizzare. Il server emette solo eventi che richiedono una funzionalità (ad es. confirmationRequest) quando questa viene dichiarata, in modo che i client meno recenti non ricevano mai eventi che verrebbero ignorati senza preavviso.
operationCompletedEvent

object (OperationCompletedEvent)

Facoltativo. Riprende una sessione dell'assistente messa in pausa in attesa del completamento di un'operazione a lunga esecuzione gestita dal client.
resumeFromSequenceNumber

string (int64 format)

Facoltativo. Cursore facoltativo per riprendere e riprodurre gli eventi di un turno in corso o completato.
attachOnly

boolean

Facoltativo. Flag facoltativo da allegare a un turno in corso esistente senza inviare un nuovo messaggio.

Corpo della risposta

Messaggio di risposta per SessionService.StreamChatAiAssistant.

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Rappresentazione 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.
}
Campi
eventId

string

Identificatore univoco dell'evento.
eventTime

string (Timestamp format)

Timestamp di quando si è verificato l'evento.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
uiEvent

object (UiEvent)

Facoltativo. Payload dell'evento UI.
turnMetadata

object (TurnMetadata)

Facoltativo. Metadati a livello di turno e categorizzazione degli intenti.
sequenceNumber

string (int64 format)

Facoltativo. Numero di sequenza che aumenta monotonicamente per questo turno della sessione.
turnInProgress

boolean

Facoltativo. Indica se il turno è ancora attivo in background.
Il payload dell'evento. Di seguito è riportato un elenco di campi che si escludono a vicenda. In una risposta verrà impostato al massimo uno dei campi:
textChunk

string

Token di testo (per lo streaming delle risposte di Gemini parola per parola).
status

object (Status)

Semplice aggiornamento dello stato.
thoughtChunk

string

Frammento di testo del pensiero (ragionamento dell'agente prima di generare la risposta).
toolCall

object (ToolCall)

Evento di esecuzione della chiamata allo strumento.
toolResponse

object (ToolResponse)

Evento di risposta alla chiamata allo strumento.
artifactChunk

object (ArtifactChunk)

Evento dell'artefatto del documento generato (delta dell'anteprima in tempo reale + puntatore Cloud Storage finale).
optionQuestionsChunk

object (OptionQuestionsChunk)

Opzioni di chiarimento strutturate analizzate dal turno del modello. La console li visualizza come un elenco di opzioni selezionabili anziché come testo non elaborato.
confirmationRequest

object (AssistantConfirmationRequest)

Una conferma di blocco su cui l'agente è in pausa. L'agente riprende quando la risposta arriva nel campo confirmationResponse di una richiesta successiva. Inviato solo ai client che hanno dichiarato la funzionalità CONFIRMATION_CARDS nella richiesta.
sessionCheckpoint

object (SessionCheckpoint)

Evento di riepilogo del checkpoint/della compattazione della sessione contenente l'user intent e il riepilogo continuo.
resumeSnapshot

object (TurnResumeSnapshot)

Una riproduzione compressa di un turno in corso, inviata come primo evento di ogni collegamento o ripresa prima di qualsiasi evento live. Il client sostituisce qualsiasi stato di rendering locale per questo turno con i contenuti dello snapshot.
handoff

object (TurnHandoffEvent)

Indica al client di riconnettersi silenziosamente con resumeFromSequenceNumber: l'attività che gestisce questo stream sta per essere interrotta e il turno continuerà altrove. Non si tratta di un errore; lo stream viene completato normalmente dopo questo evento.
turnCompleted

object (TurnCompletedEvent)

Il turno è terminato. Inviato come ultimo evento di ogni turno, nello stream originale e in ogni stream collegato o ripreso, in modo che i client possano terminare il turno con un indicatore esplicito anziché dedurlo dalla chiusura dello stream.
Fine dei campi che si escludono a vicenda.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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

Per saperne di più, consulta la Authentication Overview.

Autorizzazioni IAM

Richiede la seguente autorizzazione IAM per la risorsa name:

  • ces.assistantSessions.get

Per saperne di più, consulta la documentazione di IAM.

AssistantConfirmationResponse

La risposta dell'utente a un AssistantConfirmationRequest, inviata alla chiamata SessionService.StreamChatAiAssistant successiva per riprendere l'agente in pausa.

Rappresentazione 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.
}
Campi
confirmationId

string

La AssistantConfirmationRequest.confirmation_id a cui viene data risposta.
La risposta dell'utente. Di seguito è riportato un elenco di campi che si escludono a vicenda. In una risposta verrà impostato al massimo uno dei campi:
confirmed

boolean

Risposta binaria: true approva l'azione messa in pausa, false la rifiuta.
answerText

string

Il submitText dell'opzione scelta o il testo dell'utente in formato libero. L'azione in pausa viene annullata e il testo viene consegnato all'agente affinché agisca di conseguenza.
Fine dei campi che si escludono a vicenda.

StreamChatAiAssistantRequest.ClientCapability

Funzionalità di risposta che un client può dichiarare.

Enum
CLIENT_CAPABILITY_UNSPECIFIED Funzionalità non specificata; ignorata.
CONFIRMATION_CARDS Il client esegue il rendering delle schede AssistantConfirmationRequest e risponde tramite confirmationResponse.
CLIENT_MANAGED_LRO Il client gestisce le operazioni a lunga esecuzione fuori banda eseguendo il polling dell'operazione e inviando operationCompletedEvent per riprendere il turno. Se non viene dichiarato, il server gestisce il polling LRO e completa il turno in linea.
PROJECT_SCOPE Il client esegue il rendering degli eventi con ambito di progetto: typedPayload schede, targetApp sulle chiamate allo strumento e sulle risposte, targets sulle richieste di conferma e touchedApps sul completamento del turno.

OperationCompletedEvent

Evento inviato dal client o dal worker in background per riprendere una sessione dell'assistente dopo il completamento di un'operazione a lunga esecuzione (LRO) asincrona.

Rappresentazione JSON 
{
  "operationName": string,
  "targetResourceName": string,
  "operationType": string,
  "status": string,
  "deduplicationToken": string,
  "error": {
    object (Status)
  },
  "metadata": {
    object
  }
}
Campi
operationName

string

Il nome della risorsa dell'operazione (ad es. operations/{op}).
targetResourceName

string

La risorsa principale scelta come target o prodotta dall'operazione (ad es. ID esecuzione della valutazione, ID app, ID set di dati).
operationType

string

Il tipo di operazione o il nome dello strumento (ad es. "run_evaluation", "copy_app", "export_app").
status

string

Stato dell'esecuzione dell'operazione (ad es. "SUCCEEDED", "FAILED", "CANCELLED").
deduplicationToken

string

Token di deduplicazione facoltativo (ad es. UUID) per impedire l'esecuzione di turni duplicati da schede del browser simultanee.
error

object (Status)

Stato di errore canonico facoltativo se l'operazione non è riuscita.
metadata

object (Struct format)

Metadati facoltativi dei risultati strutturati (ad es. pass_rate, total_examples, export_uri).

ArtifactChunk

Un frammento in streaming di un artefatto di documento (ad es. un TDD in markdown) che l'assistente sta generando. I delta dei contenuti vengono trasmessi in streaming durante la scrittura del documento, in modo che i client possano eseguire il rendering di un'anteprima dal vivo; il chunk FINALIZED contiene l'URI Cloud Storage una volta che il file è stato reso persistente.

Rappresentazione JSON 
{
  "artifactId": string,
  "displayName": string,
  "mimeType": string,
  "contentDelta": string,
  "gcsUri": string,
  "state": enum (ArtifactChunk.State),
  "targetApp": string
}
Campi
artifactId

string

Identificatore dell'artefatto, stabile in tutti i chunk di un artefatto all'interno dello stream.
displayName

string

Il nome file mostrato all'utente, ad esempio "hotel_booking_tdd.md". Impostato su STARTED (e ripetuto su FINALIZED).
mimeType

string

Il tipo di media IANA dei contenuti dell'artefatto, ad esempio "text/markdown".
contentDelta

string

Contenuti dell'elemento incrementale. Impostato su blocchi DELTA.
gcsUri

string

L'oggetto Cloud Storage in cui è stato salvato l'artefatto. Impostato su blocchi FINALIZED.
state

enum (ArtifactChunk.State)

Posizione del ciclo di vita di questo chunk.
targetApp

string

Solo output. L'app per cui è stato prodotto questo artefatto, se è stato prodotto per un'app. Formato: projects/{project}/locations/{location}/apps/{app}

ArtifactChunk.State

Posizione del ciclo di vita di questo chunk all'interno dello stream dell'artefatto.

Enum
STATE_UNSPECIFIED Valore predefinito non utilizzato.
STARTED L'assistente ha iniziato a generare l'artefatto.
DELTA Un incremento dei contenuti; contentDelta è impostato.
FINALIZED L'artefatto è stato reso persistente; gcsUri è impostato.
FAILED Generazione o persistenza non riuscita; l'artefatto non è stato salvato.
CLOSED Lo streaming del documento è terminato: i suoi contenuti sono stati pubblicati completamente tramite i chunk contentDelta. La persistenza potrebbe comunque seguire; un chunk FINALIZED con un gcsUri viene inviato se e quando l'artefatto viene salvato.

OptionQuestionsChunk

Opzioni di chiarimento strutturate tra cui l'assistente chiede all'utente di scegliere, trasdotte lato server dal turno del modello (il blocco di opzioni viene rimosso dal testo in streaming e persistente). La console mostra un elenco di opzioni navigabile da tastiera ancorato sopra l'editor.

Rappresentazione JSON 
{
  "questions": [
    {
      object (OptionQuestionsChunk.Question)
    }
  ]
}
Campi
questions[]

object (OptionQuestionsChunk.Question)

Le domande poste in questo turno. Più di una voce attiva il pager "1 di N" della console.

OptionQuestionsChunk.Question

Una domanda con le relative opzioni.

Rappresentazione JSON 
{
  "question": string,
  "options": [
    {
      object (OptionQuestionsChunk.Option)
    }
  ]
}
Campi
question

string

Il testo dell'intestazione della domanda.
options[]

object (OptionQuestionsChunk.Option)

Le opzioni selezionabili, in ordine di presentazione.

OptionQuestionsChunk.Option

Una singola opzione selezionabile.

Rappresentazione JSON 
{
  "title": string,
  "details": string,
  "submitText": string
}
Campi
title

string

Titolo breve dell'opzione in testo normale (senza markdown, senza numerazione).
details

string

Dettagli facoltativi sul compromesso mostrati come testo secondario.
submitText

string

Testo del messaggio facoltativo da inviare quando viene scelta l'opzione; il valore predefinito è title se vuoto.

AssistantConfirmationRequest

Una domanda o una conferma di blocco a cui l'assistente deve rispondere prima che un'azione dell'agente possa procedere. L'agente richiedente viene messo in pausa e riprende solo quando la risposta arriva in un StreamChatAiAssistantRequest.confirmation_response successivo.

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

string

Identificatore che mette in correlazione questa richiesta con la relativa risposta. Opaco per i client; deve essere ripetuto alla lettera nella richiesta di risposta.
context

string

Contesto che descrive ciò che viene confermato (ad es. l'azione che l'agente vuole intraprendere o la domanda a cui deve rispondere). Visualizzato come testo normale, non come Markdown.
positiveLabel

string

Etichetta per l'azione di approvazione di una conferma binaria (ad es. "Pubblica"). Non impostato quando questions è compilato.
negativeLabel

string

Etichetta per l'azione di rifiuto di una conferma binaria (ad es. "Non ancora"). Non impostato quando questions è compilato.
questions[]

object (OptionQuestionsChunk.Question)

Modulo di conferma a scelta multipla. Se compilata, la scheda mostra un elenco di opzioni selezionabili e il valore submitText dell'opzione scelta (o il testo dell'utente in formato libero) viene restituito come AssistantConfirmationResponse.answer_text.
tool

string

Nome della chiamata allo strumento su cui l'agente ha fatto una pausa (ad es. "update_app"), per l'intestazione della scheda. Non impostato per domande pure.
agentName

string

Etichetta di visualizzazione dell'agente che ha generato la conferma (ad es. "Contract Architect"), per l'intestazione della scheda.
expireTime

string (Timestamp format)

Ora dopo la quale non è più possibile rispondere a questa conferma. Una carta scaduta viene visualizzata come non attiva e il server rifiuta la conferma al turno successivo, in modo che l'agente in pausa non attenda indefinitamente.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
targets[]

object (AssistantConfirmationRequest.Target)

Tutto ciò che verrà modificato dall'azione confermata, in modo che la console possa visualizzare "Aggiorna 2 app" e un badge per app. Vuoto per le schede legacy con un singolo target.

AssistantConfirmationRequest.Target

Una risorsa che verrà modificata dall'azione confermata.

Rappresentazione JSON 
{
  "resource": string,
  "displayName": string,
  "action": string,
  "targetApp": string
}
Campi
resource

string

La risorsa che verrà modificata, come nome completo della risorsa.
displayName

string

Nome visualizzato della risorsa o dell'app per la scheda.
action

string

L'azione, ad esempio CREATE, UPDATE, DELETE, COPY, LINK.
targetApp

string

L'app a cui appartiene la risorsa o vuota per un'azione con ambito di località, ad esempio la creazione di un'app. Formato: projects/{project}/locations/{location}/apps/{app}

SessionCheckpoint

Checkpoint della sessione contenente l'user intent dedotto per il titolo della sessione e l'UI.

Rappresentazione JSON 
{
  "userIntent": string
}
Campi
userIntent

string

Argomento o obiettivo dell'utente dedotto per la sessione (ad es. "Creazione di un agente di assistenza per l'e-commerce").

TurnResumeSnapshot

Una ripetizione compressa di un turno in corso: tutto il necessario per eseguire il rendering dell'output visibile del turno finora, oltre alla posizione da cui continuano gli eventi dal vivo.

Rappresentazione JSON 
{
  "turnId": string,
  "resolvedSequenceNumber": string,
  "events": [
    {
      object (StreamChatAiAssistantResponse)
    }
  ],
  "orphanDeadlineTime": string
}
Campi
turnId

string

Identifica la svolta a cui è collegata.
resolvedSequenceNumber

string (int64 format)

La posizione rappresentata da questo snapshot. Gli eventi dal vivo seguono con sequenceNumber rigorosamente maggiore di questo. Se è inferiore al valore resumeFromSequenceNumber richiesto dal client, l'avanzamento dello svuotamento è in ritardo rispetto a quanto già visualizzato dal client: il client deve ignorare i contenuti visualizzati di questo turno oltre questa posizione prima di applicare lo snapshot.
events[]

object (StreamChatAiAssistantResponse)

Eventi compattati che ricostruiscono l'output visibile del turno, in ordine di rendering, utilizzando le stesse forme di eventi del live streaming.
orphanDeadlineTime

string (Timestamp format)

Quando il turno verrà chiuso se non rimangono client collegati.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

TurnHandoffEvent

Generato prima che questa attività interrompa la pubblicazione dello stream a metà turno (ad esempio, un riavvio del server). Lo stato del turno viene mantenuto; una riconnessione con resumeFromSequenceNumber lo continua su un'altra attività.

Rappresentazione JSON 
{
  "turnId": string,
  "reason": enum (TurnHandoffEvent.Reason)
}
Campi
turnId

string

Identifica la svolta da riprendere.
reason

enum (TurnHandoffEvent.Reason)

Il motivo per cui lo stream viene trasferito.

TurnHandoffEvent.Reason

Il motivo per cui lo stream viene trasferito.

Enum
REASON_UNSPECIFIED Non specificato.
SERVER_RESTART L'attività di gestione è in fase di arresto (push della release o riprogrammazione).

TurnCompletedEvent

Evento terminale di un turno (vedi StreamChatAiAssistantResponse.turn_completed).

Rappresentazione JSON 
{
  "turnId": string,
  "reason": enum (TurnCompletedEvent.Reason),
  "finalSequenceNumber": string,
  "touchedApps": [
    string
  ]
}
Campi
turnId

string

Identificatore della svolta terminata; corrisponde a TurnResumeSnapshot.turn_id e ActiveTurnInfo.turn_id.
reason

enum (TurnCompletedEvent.Reason)

Il motivo per cui il turno è terminato.
finalSequenceNumber

string (int64 format)

Numero di sequenza dell'ultimo evento prodotto dal turno. Un client il cui cursore è più basso ha perso dei contenuti e deve ricaricare la sessione per visualizzarli.
touchedApps[]

string

Le app che sono state scelte come target o modificate in questo turno, in modo che la console possa aggiornare esattamente gli store di queste app. Solo sessioni con ambito di progetto. Formato: projects/{project}/locations/{location}/apps/{app}

TurnCompletedEvent.Reason

Il motivo per cui il turno è terminato, in modo che un client che si è collegato in ritardo possa formulare il risultato anziché indovinarlo da uno stream vuoto.

Enum
REASON_UNSPECIFIED Non specificato.
COMPLETED Il turno è stato completato; la sessione conserva l'output di cui è stato eseguito il commit.
ABANDONED Nessuna attività stava più guidando il turno; è stato sigillato in un parziale impegnato e non può essere continuato.
RESUME_UNAVAILABLE Questo server non supporta il collegamento o il ripristino della sessione, quindi non è stato eseguito il tailing. Il client deve ricaricare la sessione.

UiEvent

Rappresenta un payload di eventi della UI.

Rappresentazione JSON 
{
  "mimeType": string,
  "jsonPayload": string
}
Campi
mimeType

string

Il tipo di media (tipo MIME) che indica il formato del payload dell'evento UI (ad es. "application/json+a2ui").
jsonPayload

string

Il payload JSON che rappresenta la piattaforma A2UI.

TurnMetadata

Metadati a livello di turno e categorizzazione degli intenti.

Rappresentazione JSON 
{
  "contractRelated": boolean,
  "contractFinalized": boolean,
  "contractStreamingPhase": enum (TurnMetadata.ContractStreamingPhase),
  "contractDraftComplete": boolean
}
Campi
contractFinalized

boolean

Impostato sull'evento dell'artefatto finale di un turno la cui bozza di contratto è stata pubblicata (è stata attivata una revisione). Terminale per il flusso di chiarimento di questa bozza: contractProgress è autorevole e completo.
contractStreamingPhase

enum (TurnMetadata.ContractStreamingPhase)

Impostato solo sulle stime di avanzamento in corso emesse durante lo streaming di un recinto di artefatti del contratto e sull'evento revision-turn-start. Non impostato sui payload autorevoli.
contractDraftComplete

boolean

Impostato sull'evento terminale di una bozza di contratto in cui ogni segnaposto è stato risolto (contractProgress è 100%), indipendentemente dal fatto che la bozza sia stata pubblicata o meno. I client completano e ignorano la visualizzazione dello stato di avanzamento del contratto; la pubblicazione viene segnalata separatamente da contractFinalized.

TurnMetadata.ContractStreamingPhase

Fase di streaming del payload di avanzamento del contratto.

Enum
CONTRACT_STREAMING_PHASE_UNSPECIFIED Il payload è autorevole (calcolato da un documento di contratto completo, uno snapshot persistente o lo stato pre-bozza). I client devono sostituire con questo valore qualsiasi stato di avanzamento ricevuto in precedenza.
DRAFTING È in corso lo streaming di una bozza iniziale del contratto. contractProgress è una stima in corso: non decrescente all'interno di un recinto di artefatti, limitata al di sotto dell'intervallo autorevole, con pillarBreakdowns che riporta totalItemCount == 0 per contrassegnare gli stati dei pilastri stimati.
REVISING È in corso la revisione di un contratto esistente (ad esempio dopo l'invio di un'annotazione). Stessa semantica di stima di DRAFTING.