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/v1beta/{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,
    "useToolFakes": boolean,
    "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.useToolFakes

boolean

Opcional. Indica se serão usados simulacros de ferramentas na sessão. Se esse campo estiver definido, o agente vai tentar usar simulações de ferramentas em vez de chamar as ferramentas reais.
config.remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

Opcional. QueryParameters a serem enviados ao agente remoto do Dialogflow quando o controle da sessão é 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,
  "useToolFakes": boolean,
  "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".
useToolFakes

boolean

Opcional. Indica se serão usados simulacros de ferramentas na sessão. Se esse campo estiver definido, o agente vai tentar usar simulações de ferramentas em vez de chamar as ferramentas reais.
remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

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

SessionConfig.RemoteDialogflowQueryParameters

QueryParameters a serem enviados ao agente remoto do Dialogflow quando o controle da sessão é 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.

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.