Method: projects.locations.apps.assistantSessions.streamChatAiAssistant

Executa o Arc, o assistente de IA, para a sessão de assistente especificada em um modo de streaming.

Solicitação HTTP

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

O URL usa a sintaxe de transcodificação gRPC.

Parâmetros de caminho

Parâmetros
name

string

Obrigatório. A sessão do assistente que será usada para executar o assistente. Formato: projects/{project}/locations/{location}/apps/{app}/assistantSessions/{assistantSession}

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

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

string

Opcional. A mensagem a ser enviada ao agente assistente. Pode ficar vazio quando confirmationResponse é definido (respondendo a uma confirmação pendente sem adicionar uma nova mensagem). Pelo menos um dos dois precisa ser fornecido.
attachedGcsUris[]

string

Opcional. URIs do Cloud Storage para arquivos enviados pelo usuário durante essa rodada. Exemplo: "gs://cxas-transient-uploads/uuid/prd.pdf"
contextToken

string

Opcional. Token de contexto de integração opaco retornado por SessionService.GenerateOnboardingSuggestions. Quando definido e ainda atualizado, o servidor reutiliza o snapshot de integração calculado para o estado zero em vez de recalcular para a primeira rodada de conversa.
confirmationResponse

object (AssistantConfirmationResponse)

Opcional. A resposta do usuário a um AssistantConfirmationRequest pendente. Quando definido, o servidor retoma o agente pausado com essa resposta em vez de (ou além de) iniciar uma nova rodada de comandos.
clientCapabilities[]

enum (StreamChatAiAssistantRequest.ClientCapability)

Opcional. Recursos de resposta que este cliente pode renderizar. O servidor só emite eventos que precisam de uma capacidade (por exemplo, confirmationRequest) quando ela é declarada. Assim, os clientes mais antigos nunca recebem eventos que seriam descartados silenciosamente.
operationCompletedEvent

object (OperationCompletedEvent)

Opcional. Retoma uma sessão do assistente pausada aguardando a conclusão de uma operação de longa duração gerenciada pelo cliente.
resumeFromSequenceNumber

string (int64 format)

Opcional. Cursor opcional para retomar e repetir eventos de uma rodada em andamento ou concluída.
attachOnly

boolean

Opcional. Flag opcional para anexar a uma conversa em andamento sem enviar uma nova mensagem.

Corpo da resposta

Mensagem de resposta para SessionService.StreamChatAiAssistant.

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

Representação 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 exclusivo do evento.
eventTime

string (Timestamp format)

Carimbo de data/hora de quando o evento ocorreu.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
uiEvent

object (UiEvent)

Opcional. Payload do evento UI.
turnMetadata

object (TurnMetadata)

Opcional. Metadados no nível da fala e categorização de intenção.
sequenceNumber

string (int64 format)

Opcional. Número de sequência monotonicamente crescente para este turno da sessão.
turnInProgress

boolean

Opcional. Indica se a curva ainda está sendo executada em segundo plano.
O payload do evento. Confira a seguir uma lista de campos mutuamente exclusivos. No máximo um dos campos será definido em uma resposta:
textChunk

string

Token de texto (para transmitir as respostas do Gemini palavra por palavra).
status

object (Status)

Atualização de status simples.
thoughtChunk

string

Bloco de texto de pensamento (raciocínio do agente antes de gerar a resposta).
toolCall

object (ToolCall)

Evento de execução de chamada de ferramenta.
toolResponse

object (ToolResponse)

Evento de resposta de chamada de ferramenta.
artifactChunk

object (ArtifactChunk)

Evento de artefato de documento gerado (deltas de prévia ao vivo + ponteiro final do Cloud Storage).
optionQuestionsChunk

object (OptionQuestionsChunk)

Opções de esclarecimento estruturadas analisadas na vez do modelo. O console renderiza esses valores como uma lista de opções selecionáveis, em vez de texto bruto.
confirmationRequest

object (AssistantConfirmationRequest)

Uma confirmação de bloqueio em que o agente foi pausado. O agente é retomado quando a resposta chega no confirmationResponse de uma solicitação posterior. Enviado apenas para clientes que declararam o recurso CONFIRMATION_CARDS na solicitação.
sessionCheckpoint

object (SessionCheckpoint)

Evento de recapitulação de checkpoint/compactação da sessão que contém a intenção do usuário e o resumo contínuo.
resumeSnapshot

object (TurnResumeSnapshot)

Uma repetição compactada de uma rodada em andamento, enviada como o primeiro evento de cada anexação ou retomada antes de qualquer evento ao vivo. O cliente substitui qualquer estado renderizado localmente para essa rodada pelo conteúdo do snapshot.
handoff

object (TurnHandoffEvent)

Informa ao cliente para se reconectar silenciosamente com resumeFromSequenceNumber: a tarefa que exibe esse stream está sendo encerrada, e a vez vai continuar em outro lugar. Não é um erro. O stream é concluído normalmente após esse evento.
turnCompleted

object (TurnCompletedEvent)

A vez acabou. Enviado como o último evento de cada turno, no stream original e em cada stream anexado ou retomado, para que os clientes possam encerrar o turno com um sinal explícito, em vez de inferir isso do fechamento do stream.
Fim dos campos mutuamente exclusivos.

Escopos de autorização

Requer um dos seguintes escopos do OAuth:

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

Para mais informações, consulte Authentication Overview.

Permissões do IAM

Requer a seguinte permissão do IAM no recurso name:

  • ces.assistantSessions.get

Para mais informações, consulte a documentação do IAM.

AssistantConfirmationResponse

A resposta do usuário a um AssistantConfirmationRequest, enviada na próxima chamada SessionService.StreamChatAiAssistant para retomar o agente pausado.

Representação 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

O AssistantConfirmationRequest.confirmation_id que está sendo respondido.
A resposta do usuário. Confira a seguir uma lista de campos mutuamente exclusivos. No máximo um dos campos será definido em uma resposta:
confirmed

boolean

Resposta binária: "true" aprova a ação pausada, "false" a recusa.
answerText

string

O submitText da opção escolhida ou o texto livre do usuário. A ação pausada é cancelada, e o texto é entregue ao agente para que ele tome as medidas necessárias.
Fim dos campos mutuamente exclusivos.

StreamChatAiAssistantRequest.ClientCapability

Recursos de resposta que um cliente pode declarar.

Tipos enumerados
CLIENT_CAPABILITY_UNSPECIFIED Recurso não especificado; ignorado.
CONFIRMATION_CARDS O cliente renderiza os cards AssistantConfirmationRequest e os responde usando confirmationResponse.
CLIENT_MANAGED_LRO O cliente gerencia operações de longa duração fora de banda, sondando a operação e enviando operationCompletedEvent para retomar a vez. Se não for declarado, o servidor vai gerenciar a sondagem de LRO e concluir a vez inline.
PROJECT_SCOPE O cliente renderiza eventos de escopo do projeto: cards typedPayload, targetApp em chamadas de ferramentas e respostas, targets em solicitações de confirmação e touchedApps na conclusão de turnos.

OperationCompletedEvent

Evento enviado pelo cliente ou worker em segundo plano para retomar uma sessão do assistente após a conclusão de uma operação de longa duração (LRO, na sigla em inglês) assíncrona.

Representação JSON 
{
  "operationName": string,
  "targetResourceName": string,
  "operationType": string,
  "status": string,
  "deduplicationToken": string,
  "error": {
    object (Status)
  },
  "metadata": {
    object
  }
}
Campos
operationName

string

O nome do recurso da operação (por exemplo, operations/{op}).
targetResourceName

string

O recurso principal visado ou produzido pela operação (por exemplo, ID da execução de avaliação, ID do app, ID do conjunto de dados).
operationType

string

O tipo de operação ou o nome da ferramenta (por exemplo, "run_evaluation", "copy_app", "export_app").
status

string

Status da execução da operação (por exemplo, "SUCCEEDED", "FAILED", "CANCELLED").
deduplicationToken

string

Token de eliminação de duplicação opcional (por exemplo, UUID) para evitar a execução de turnos duplicados em guias simultâneas do navegador.
error

object (Status)

Status de erro canônico opcional se a operação falhar.
metadata

object (Struct format)

Metadados de resultado estruturados opcionais (por exemplo, pass_rate, total_examples, export_uri).

ArtifactChunk

Um fragmento de um artefato de documento (por exemplo, um TDD de markdown) que o assistente está gerando. As diferenças de conteúdo são transmitidas enquanto o documento está sendo escrito para que os clientes possam renderizar uma prévia em tempo real. O bloco FINALIZED carrega o URI do Cloud Storage depois que o arquivo é mantido.

Representação JSON 
{
  "artifactId": string,
  "displayName": string,
  "mimeType": string,
  "contentDelta": string,
  "gcsUri": string,
  "state": enum (ArtifactChunk.State),
  "targetApp": string
}
Campos
artifactId

string

Identificador do artefato, estável em todos os blocos de um artefato no stream.
displayName

string

O nome do arquivo mostrado ao usuário, por exemplo, "hotel_booking_tdd.md". Definido como STARTED (e repetido em FINALIZED).
mimeType

string

O tipo de mídia IANA do conteúdo do artefato, por exemplo, "text/markdown".
contentDelta

string

Conteúdo de artefato incremental. Definido em blocos DELTA.
gcsUri

string

O objeto do Cloud Storage em que o artefato foi mantido. Definido em blocos FINALIZED.
state

enum (ArtifactChunk.State)

Posição do ciclo de vida desse bloco.
targetApp

string

Apenas saída. O app para o qual o artefato foi produzido, quando foi produzido para um. Formato: projects/{project}/locations/{location}/apps/{app}

ArtifactChunk.State

Posição do ciclo de vida desse bloco no stream do artefato.

Tipos enumerados
STATE_UNSPECIFIED Padrão não utilizado.
STARTED O assistente começou a gerar o artefato.
DELTA Um incremento de conteúdo; contentDelta está definido.
FINALIZED O artefato foi mantido. gcsUri está definido.
FAILED Falha na geração ou persistência. O artefato não foi salvo.
CLOSED O documento terminou de ser transmitido: o conteúdo foi totalmente entregue em blocos contentDelta. A persistência ainda pode ocorrer. Um bloco FINALIZED com um gcsUri é enviado se e quando o artefato é salvo.

OptionQuestionsChunk

Opções de esclarecimento estruturadas que o assistente pede para o usuário escolher, traduzidas do lado do servidor fora da vez do modelo (o bloco de opções é removido do texto transmitido e persistido). O console renderiza uma lista de opções navegável pelo teclado, fixada acima do editor.

Representação JSON 
{
  "questions": [
    {
      object (OptionQuestionsChunk.Question)
    }
  ]
}
Campos
questions[]

object (OptionQuestionsChunk.Question)

As perguntas feitas nesta rodada. Mais de uma entrada aciona o paginador "1 de N" do console.

OptionQuestionsChunk.Question

Uma pergunta com as opções.

Representação JSON 
{
  "question": string,
  "options": [
    {
      object (OptionQuestionsChunk.Option)
    }
  ]
}
Campos
question

string

É o texto do cabeçalho da pergunta.
options[]

object (OptionQuestionsChunk.Option)

As opções selecionáveis, em ordem de apresentação.

OptionQuestionsChunk.Option

Uma única opção selecionável.

Representação JSON 
{
  "title": string,
  "details": string,
  "submitText": string
}
Campos
title

string

Título curto da opção em texto simples (sem markdown, sem numeração).
details

string

Detalhes opcionais de compensação mostrados como texto secundário.
submitText

string

Texto opcional da mensagem a ser enviada quando a opção é escolhida. O padrão é title quando vazio.

AssistantConfirmationRequest

Uma pergunta ou confirmação que o assistente precisa que seja respondida antes que uma ação do agente possa continuar. O agente solicitante é pausado e só é retomado quando a resposta chega em um StreamChatAiAssistantRequest.confirmation_response posterior.

Representação 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

Identificador que correlaciona essa solicitação com a resposta dela. Invisível para os clientes. Precisa ser repetido literalmente na solicitação de resposta.
context

string

Contexto que descreve o que está sendo confirmado (por exemplo, a ação que o agente quer realizar ou a pergunta que precisa ser respondida). Renderizado como texto simples, não Markdown.
positiveLabel

string

Rótulo para a ação de aprovação de uma confirmação binária (por exemplo, "Publicar"). Não definido quando questions é preenchido.
negativeLabel

string

Rótulo para a ação de recusa de uma confirmação binária (por exemplo, "Ainda não"). Não definido quando questions é preenchido.
questions[]

object (OptionQuestionsChunk.Question)

Formulário de confirmação de múltipla escolha. Quando preenchido, o card renderiza uma lista de opções selecionáveis, e o submitText da opção escolhida (ou o texto de formato livre do usuário) é retornado como AssistantConfirmationResponse.answer_text.
tool

string

Nome da chamada de ferramenta em que o agente pausou (por exemplo, "update_app"), para o cabeçalho do card. Não definido para perguntas puras.
agentName

string

Rótulo de exibição do agente que gerou a confirmação (por exemplo, "Contract Architect") para o cabeçalho do card.
expireTime

string (Timestamp format)

Horário após o qual não é mais possível responder a essa confirmação. Um cartão expirado é renderizado como inativo, e o servidor recusa a confirmação na próxima vez para que o agente pausado não espere indefinidamente.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
targets[]

object (AssistantConfirmationRequest.Target)

Tudo o que a ação confirmada vai mudar para que o console possa renderizar "Atualizar 2 apps" e um selo por app. Vazio para cards legados de destino único.

AssistantConfirmationRequest.Target

Um recurso que será alterado pela ação confirmada.

Representação JSON 
{
  "resource": string,
  "displayName": string,
  "action": string,
  "targetApp": string
}
Campos
resource

string

O recurso que será alterado, como um nome de recurso completo.
displayName

string

Nome de exibição do recurso ou app para o card.
action

string

A ação, por exemplo, CREATE, UPDATE, DELETE, COPY, LINK.
targetApp

string

O app ao qual o recurso pertence ou vazio para uma ação com escopo de local, como criar um app. Formato: projects/{project}/locations/{location}/apps/{app}

TurnResumeSnapshot

Uma repetição compactada de uma rodada em andamento: tudo o que é necessário para renderizar a saída visível da rodada até o momento, além da posição em que os eventos ao vivo continuam.

Representação JSON 
{
  "turnId": string,
  "resolvedSequenceNumber": string,
  "events": [
    {
      object (StreamChatAiAssistantResponse)
    }
  ],
  "orphanDeadlineTime": string
}
Campos
turnId

string

Identifica a curva que está sendo anexada.
resolvedSequenceNumber

string (int64 format)

A posição que esse snapshot representa. Os eventos ao vivo seguem com sequenceNumber estritamente maior que esse. Quando menor que o resumeFromSequenceNumber solicitado pelo cliente, o progresso liberado fica atrás do que o cliente já renderizou: o cliente precisa descartar o conteúdo renderizado dessa vez além dessa posição antes de aplicar o snapshot.
events[]

object (StreamChatAiAssistantResponse)

Eventos compactados que reconstroem a saída visível da rodada, em ordem de renderização, usando as mesmas formas de evento da transmissão ao vivo.
orphanDeadlineTime

string (Timestamp format)

Quando a rodada será encerrada se nenhum cliente permanecer conectado.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

TurnHandoffEvent

Emitido antes que essa tarefa pare de exibir o stream no meio da conversa (por exemplo, uma reinicialização do servidor). O estado do turno é mantido. Uma reconexão com resumeFromSequenceNumber continua em outra tarefa.

Representação JSON 
{
  "turnId": string,
  "reason": enum (TurnHandoffEvent.Reason)
}
Campos
turnId

string

Identifica a curva para retomar.
reason

enum (TurnHandoffEvent.Reason)

Por que a transmissão está sendo transferida.

TurnHandoffEvent.Reason

Por que a transmissão está sendo transferida.

Tipos enumerados
REASON_UNSPECIFIED Não especificado.
SERVER_RESTART A tarefa de exibição está sendo encerrada (push de lançamento ou reprogramação).

TurnCompletedEvent

Evento terminal de uma rodada (consulte StreamChatAiAssistantResponse.turn_completed).

Representação JSON 
{
  "turnId": string,
  "reason": enum (TurnCompletedEvent.Reason),
  "finalSequenceNumber": string,
  "touchedApps": [
    string
  ]
}
Campos
turnId

string

Identificador da conversão que terminou. Corresponde a TurnResumeSnapshot.turn_id e ActiveTurnInfo.turn_id.
reason

enum (TurnCompletedEvent.Reason)

Por que a vez terminou.
finalSequenceNumber

string (int64 format)

Número de sequência do último evento produzido pela vez. Um cliente com um cursor mais baixo perdeu conteúdo e precisa recarregar a sessão para vê-lo.
touchedApps[]

string

Apps que foram segmentados ou alterados nesta rodada, para que o console possa atualizar exatamente as lojas desses apps. Somente sessões com escopo de projeto. Formato: projects/{project}/locations/{location}/apps/{app}

TurnCompletedEvent.Reason

Por que a vez terminou, para que um cliente que se conectou tarde possa expressar o resultado em vez de adivinhar com base em um stream vazio.

Tipos enumerados
REASON_UNSPECIFIED Não especificado.
COMPLETED A rodada foi concluída. A sessão mantém a saída confirmada.
ABANDONED Nenhuma tarefa estava mais impulsionando a vez. Ela foi selada para uma parcial confirmada e não pode ser continuada.
RESUME_UNAVAILABLE Este servidor não oferece anexação ou retomada para a sessão, então nada foi rastreado. O cliente precisa recarregar a sessão.

TurnMetadata

Metadados no nível da fala e categorização de intenção.

Representação JSON 
{
  "contractRelated": boolean,
  "contractFinalized": boolean,
  "contractStreamingPhase": enum (TurnMetadata.ContractStreamingPhase),
  "contractDraftComplete": boolean
}
Campos
contractFinalized

boolean

Definido no evento de artefato final de uma rodada em que o rascunho do contrato foi publicado (uma revisão foi ativada). Terminal para o fluxo de esclarecimento deste rascunho: contractProgress é autoritativo e completo.
contractStreamingPhase

enum (TurnMetadata.ContractStreamingPhase)

Definido apenas em estimativas de progresso em andamento emitidas enquanto uma barreira de artefato de contrato está sendo transmitida e no evento de início de turno de revisão. Não definido em payloads autoritativos.
contractDraftComplete

boolean

Definido no evento de terminal de um rascunho de contrato em que todos os marcadores de posição são resolvidos (contractProgress é 100%), independentemente de o rascunho ter sido publicado ou não. Os clientes concluem e dispensam a exibição do progresso do contrato. A publicação é informada separadamente por contractFinalized.

TurnMetadata.ContractStreamingPhase

Fase de streaming do payload de progresso do contrato.

Tipos enumerados
CONTRACT_STREAMING_PHASE_UNSPECIFIED O payload é oficial (calculado com base em um documento de contrato completo, um snapshot persistente ou o estado de pré-rascunho). Os clientes precisam substituir qualquer progresso recebido anteriormente por ele.
DRAFTING Um rascunho inicial do contrato está sendo transmitido. contractProgress é uma estimativa em andamento: não decrescente dentro de uma barreira de artefato, limitada abaixo do intervalo oficial, com pillarBreakdowns carregando totalItemCount == 0 para marcar os estados estimados do pilar.
REVISING Uma revisão de um contrato atual está sendo transmitida (por exemplo, após o envio de uma anotação). Mesma semântica de estimativa que DRAFTING.