Method: projects.locations.apps.sessions.runSession

Inicia uma interação de turno único com o agente do CES em uma sessão.

Solicitação HTTP

POST https://ces.googleapis.com/v1/{config.session=projects/*/locations/*/apps/*/sessions/*}:runSession

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

Parâmetros de caminho

Parâmetros
config.session

string

Obrigatório. O identificador exclusivo da sessão. Formato: projects/{project}/locations/{location}/apps/{app}/sessions/{session}

Corpo da solicitação

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

Representação JSON 
{
  "config": {
    "session": string,
    "inputAudioConfig": {
      "audioEncoding": enum (AudioEncoding),
      "sampleRateHertz": integer,
      "noiseSuppressionLevel": string
    },
    "outputAudioConfig": {
      "audioEncoding": enum (AudioEncoding),
      "sampleRateHertz": integer
    },
    "historicalContexts": [
      {
        "role": string,
        "chunks": [
          {
            object (Chunk)
          }
        ],
        "eventTime": string
      }
    ],
    "entryAgent": string,
    "deployment": string,
    "timeZone": string,
    "remoteDialogflowQueryParameters": {
      "webhookHeaders": {
        string: string,
        ...
      },
      "payload": {
        object
      },
      "endUserMetadata": {
        object
      }
    }
  },
  "inputs": [
    {
      object (SessionInput)
    }
  ]
}
Campos
config.inputAudioConfig

object (InputAudioConfig)

Opcional. Configuração para processar o áudio de entrada.
config.outputAudioConfig

object (OutputAudioConfig)

Opcional. Configuração para gerar o áudio de saída.
config.historicalContexts[]

object (Message)

Opcional. O contexto histórico da sessão, incluindo entradas do usuário, respostas do agente e outras mensagens. Normalmente, o agente do CES gerencia a sessão automaticamente para que o cliente não precise preencher esse campo explicitamente. No entanto, o cliente pode substituir os contextos históricos para forçar o início da sessão em um determinado estado.
config.entryAgent

string

Opcional. O agente de entrada para processar a sessão. Se não for especificado, a sessão será processada pelo root agent do app. Formato: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
config.deployment

string

Opcional. A implantação do app a ser usado na sessão. Formato: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
config.timeZone

string

Opcional. O fuso horário do usuário. Se fornecido, o agente vai usar o fuso horário para variáveis relacionadas a data e hora. Caso contrário, o agente vai usar o fuso horário especificado em App.time_zone_settings.

O formato é o fuso horário do banco de dados IANA. Por exemplo: "America/Los_Angeles".
config.remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

Opcional. QueryParameters a serem enviados ao agente remoto do Dialogflow quando o controle da sessão for transferido para ele.
inputs[]

object (SessionInput)

Obrigatório. Entradas para a sessão.

Corpo da resposta

Mensagem de resposta para SessionService.RunSession.

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

Representação JSON 
{
  "outputs": [
    {
      object (SessionOutput)
    }
  ]
}
Campos
outputs[]

object (SessionOutput)

Saídas da sessão.

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 session:

  • ces.sessions.runSession

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

SessionConfig

A configuração da sessão.

Representação JSON 
{
  "session": string,
  "inputAudioConfig": {
    object (InputAudioConfig)
  },
  "outputAudioConfig": {
    object (OutputAudioConfig)
  },
  "historicalContexts": [
    {
      object (Message)
    }
  ],
  "entryAgent": string,
  "deployment": string,
  "timeZone": string,
  "remoteDialogflowQueryParameters": {
    object (SessionConfig.RemoteDialogflowQueryParameters)
  }
}
Campos
session

string

Obrigatório. O identificador exclusivo da sessão. Formato: projects/{project}/locations/{location}/apps/{app}/sessions/{session}
inputAudioConfig

object (InputAudioConfig)

Opcional. Configuração para processar o áudio de entrada.
outputAudioConfig

object (OutputAudioConfig)

Opcional. Configuração para gerar o áudio de saída.
historicalContexts[]

object (Message)

Opcional. O contexto histórico da sessão, incluindo entradas do usuário, respostas do agente e outras mensagens. Normalmente, o agente do CES gerencia a sessão automaticamente para que o cliente não precise preencher esse campo explicitamente. No entanto, o cliente pode substituir os contextos históricos para forçar o início da sessão em um determinado estado.
entryAgent

string

Opcional. O agente de entrada para processar a sessão. Se não for especificado, a sessão será processada pelo root agent do app. Formato: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
deployment

string

Opcional. A implantação do app a ser usado na sessão. Formato: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
timeZone

string

Opcional. O fuso horário do usuário. Se fornecido, o agente vai usar o fuso horário para variáveis relacionadas a data e hora. Caso contrário, o agente vai usar o fuso horário especificado em App.time_zone_settings.

O formato é o fuso horário do banco de dados IANA. Por exemplo: "America/Los_Angeles".
remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

Opcional. QueryParameters a serem enviados ao agente remoto do Dialogflow quando o controle da sessão for transferido para ele.

InputAudioConfig

O InputAudioConfig configura como o agente do CES deve interpretar os dados de áudio recebidos.

Representação JSON 
{
  "audioEncoding": enum (AudioEncoding),
  "sampleRateHertz": integer,
  "noiseSuppressionLevel": string
}
Campos
audioEncoding

enum (AudioEncoding)

Obrigatório. A codificação dos dados de áudio de entrada.
sampleRateHertz

integer

Obrigatório. A taxa de amostragem (em Hertz) dos dados de áudio de entrada.
noiseSuppressionLevel

string

Opcional. Define se a redução de ruído será ativada no áudio de entrada. Os valores disponíveis são "low", "moderate", "high", "very_high".

AudioEncoding

AudioEncoding especifica o formato de codificação para dados de áudio.

Tipos enumerados
AUDIO_ENCODING_UNSPECIFIED Codificação de áudio não especificada.
LINEAR16 Codificação de áudio PCM linear de 16 bits.
MULAW Amostras de 8 bits resultantes do compand de amostras de áudio de 14 bits em que foi usado G.711 PCMU/mu-law.
ALAW Amostras de 8 bits resultantes do compand de amostras de áudio de 14 bits em que foi usado G.711 PCMU/A-law.

OutputAudioConfig

O OutputAudioConfig configura como o agente do CES deve sintetizar as respostas de áudio enviadas.

Representação JSON 
{
  "audioEncoding": enum (AudioEncoding),
  "sampleRateHertz": integer
}
Campos
audioEncoding

enum (AudioEncoding)

Obrigatório. A codificação dos dados de áudio de saída.
sampleRateHertz

integer

Obrigatório. A taxa de amostragem (em Hertz) dos dados de áudio de saída.

SessionConfig.RemoteDialogflowQueryParameters

QueryParameters a serem enviados ao agente remoto do Dialogflow quando o controle da sessão for transferido para ele.

Representação JSON 
{
  "webhookHeaders": {
    string: string,
    ...
  },
  "payload": {
    object
  },
  "endUserMetadata": {
    object
  }
}
Campos
webhookHeaders

map (key: string, value: string)

Opcional. Os cabeçalhos HTTP a serem enviados como webhookHeaders em QueryParameters.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
payload

object (Struct format)

Opcional. O payload a ser enviado em QueryParameters.
endUserMetadata

object (Struct format)

Opcional. Os metadados do usuário final a serem enviados em QueryParameters.

SessionInput

Entrada para a sessão.

Representação JSON 
{
  "willContinue": boolean,

  // Union field input_type can be only one of the following:
  "text": string,
  "dtmf": string,
  "audio": string,
  "toolResponses": {
    object (ToolResponses)
  },
  "image": {
    object (Image)
  },
  "blob": {
    object (Blob)
  },
  "variables": {
    object
  },
  "event": {
    object (Event)
  }
  // End of list of possible types for union field input_type.
}
Campos
willContinue

boolean

Opcional. Uma flag para indicar se a mensagem atual é um fragmento de uma entrada maior na sessão de streaming bidirecional.

Quando definido como true, o agente adia o processamento até receber uma mensagem subsequente em que willContinue seja false ou até que o sistema detecte um ponto final na entrada de áudio.

OBSERVAÇÃO: esse campo não se aplica a entradas de áudio e DTMF, já que elas são sempre processadas automaticamente com base no sinal de encerramento.
Campo de união input_type. O tipo da entrada. input_type pode ser apenas de um dos tipos a seguir:
text

string

Opcional. Dados de texto do usuário final.
dtmf

string

Opcional. Dígitos DTMF do usuário final.
audio

string (bytes format)

Opcional. Dados de áudio do usuário final.

Uma string codificada em base64.
toolResponses

object (ToolResponses)

Opcional. Resultados da execução das chamadas de função do cliente.
image

object (Image)

Opcional. Dados de imagem do usuário final.
blob

object (Blob)

Opcional. Dados de blob do usuário final.
variables

object (Struct format)

Opcional. Variáveis contextuais da sessão, com chave pelo nome. Somente as variáveis declaradas no app serão usadas pelo agente da CES.

Variáveis não reconhecidas ainda serão enviadas ao [agente do Dialogflow][Agent.RemoteDialogflowAgent] como parâmetros de sessão adicionais.
event

object (Event)

Opcional. Entrada de evento.

ToolResponses

Resultados da execução das chamadas de função solicitadas do cliente.

Representação JSON 
{
  "toolResponses": [
    {
      object (ToolResponse)
    }
  ]
}
Campos
toolResponses[]

object (ToolResponse)

Opcional. A lista de resultados da execução da ferramenta.

Evento

Entrada de evento.

Representação JSON 
{
  "event": string
}
Campos
event

string

Obrigatório. O nome do evento.

SessionOutput

Saída da sessão.

Representação JSON 
{
  "turnIndex": integer,
  "turnCompleted": boolean,
  "diagnosticInfo": {
    object (SessionOutput.DiagnosticInfo)
  },

  // Union field output_type can be only one of the following:
  "text": string,
  "audio": string,
  "toolCalls": {
    object (ToolCalls)
  },
  "citations": {
    object (Citations)
  },
  "googleSearchSuggestions": {
    object (GoogleSearchSuggestions)
  },
  "endSession": {
    object (EndSession)
  },
  "payload": {
    object
  }
  // End of list of possible types for union field output_type.
}
Campos
turnIndex

integer

Indica a ordem sequencial da rodada de conversa a que esta saída pertence, começando em 1.
turnCompleted

boolean

Se for verdadeiro, o agente do CES detectou o fim da conversa atual e não vai fornecer mais resultados para essa vez.
diagnosticInfo

object (SessionOutput.DiagnosticInfo)

Opcional. As informações de diagnóstico contêm detalhes da execução durante o processamento da entrada. Preenchido apenas no último SessionOutput (com turnCompleted=true) para cada turno.
Campo de união output_type. O tipo da saída. output_type pode ser apenas de um dos tipos a seguir:
text

string

Texto de saída do agente da CES.
audio

string (bytes format)

Saída de áudio do agente da CES.

Uma string codificada em base64.
toolCalls

object (ToolCalls)

Solicitação para o cliente executar as ferramentas.
citations

object (Citations)

Citações que fornecem as informações de origem do texto gerado pelo agente.
googleSearchSuggestions

object (GoogleSearchSuggestions)

As sugestões retornadas da Pesquisa Google como resultado da invocação do GoogleSearchTool.
endSession

object (EndSession)

Indica que a sessão foi encerrada.
payload

object (Struct format)

Payload personalizado com saída estruturada do agente da CES.

ToolCalls

Solicitação para que o cliente execute as ferramentas e retorne os resultados da execução antes de continuar a sessão.

Representação JSON 
{
  "toolCalls": [
    {
      object (ToolCall)
    }
  ]
}
Campos
toolCalls[]

object (ToolCall)

Opcional. A lista de chamadas de ferramentas a serem executadas.

Citações

Citações associadas à resposta do agente.

Representação JSON 
{
  "citedChunks": [
    {
      object (Citations.CitedChunk)
    }
  ]
}
Campos
citedChunks[]

object (Citations.CitedChunk)

Lista de informações citadas.

Citations.CitedChunk

Parte das informações citadas.

Representação JSON 
{
  "uri": string,
  "title": string,
  "text": string
}
Campos
uri

string

URI usado para citação.
title

string

Título do documento citado.
text

string

Texto usado para citação.

GoogleSearchSuggestions

Sugestões de pesquisa de Google Search Tool.

Representação JSON 
{
  "htmls": [
    string
  ],
  "webSearchQueries": [
    {
      object (WebSearchQuery)
    }
  ]
}
Campos
htmls[]

string

Estilo HTML e CSS compatível para sugestões de pesquisa. O HTML e o CSS fornecidos se adaptam automaticamente às configurações do dispositivo, sendo exibidos no modo claro ou escuro indicado por @media(prefers-color-scheme).
webSearchQueries[]

object (WebSearchQuery)

Lista de consultas usadas para realizar a pesquisa no Google, além dos URIs de resultados da pesquisa que formam as sugestões de pesquisa.

WebSearchQuery

Representa uma única consulta de pesquisa na Web e o URI de pesquisa associado.

Representação JSON 
{
  "query": string,
  "uri": string
}
Campos
query

string

O texto da consulta de pesquisa.
uri

string

O URI da página de resultados da Pesquisa Google para a consulta.

EndSession

Indica que a sessão foi encerrada devido à conclusão bem-sucedida (por exemplo, o usuário diz "Tchau!" ) ou uma transferência para um agente.

O agente não vai processar mais entradas depois que a sessão for encerrada, e o cliente vai fazer um fechamento parcial e se desconectar após receber todas as respostas restantes do agente.

Representação JSON 
{
  "metadata": {
    object
  }
}
Campos
metadata

object (Struct format)

Opcional. Fornece mais informações sobre o indicador de fim de sessão, como o motivo do encerramento.

SessionOutput.DiagnosticInfo

Contém detalhes da execução durante o processamento.

Representação JSON 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "rootSpan": {
    object (Span)
  }
}
Campos
messages[]

object (Message)

Lista das mensagens que ocorreram durante o processamento.
rootSpan

object (Span)

Um rastreamento de todo o processamento da solicitação, representado como um período raiz. Esse intervalo pode conter intervalos filhos aninhados para operações específicas.