Method: projects.locations.apps.sessions.runSession

Inicia una interacción de un solo turno con el agente de CES dentro de una sesión.

Solicitud HTTP

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

La URL usa la sintaxis de la transcodificación gRPC.

Parámetros de ruta

Parámetros
config.session

string

Obligatorio. Es el identificador único de la sesión. Formato: projects/{project}/locations/{location}/apps/{app}/sessions/{session}

Cuerpo de la solicitud

El cuerpo de la solicitud contiene datos con la siguiente estructura:

Representación 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)

Es opcional. Es la configuración para procesar el audio de entrada.
config.outputAudioConfig

object (OutputAudioConfig)

Es opcional. Es la configuración para generar el audio de salida.
config.historicalContexts[]

object (Message)

Es opcional. El contexto histórico de la sesión, incluidas las entradas del usuario, las respuestas del agente y otros mensajes. Por lo general, el agente de CES administra la sesión automáticamente, por lo que el cliente no necesita completar este campo de forma explícita. Sin embargo, el cliente puede anular de forma opcional los contextos históricos para forzar el inicio de la sesión desde un estado determinado.
config.entryAgent

string

Es opcional. Es el agente de entrada para controlar la sesión. Si no se especifica, la sesión la controlará el root agent de la app. Formato: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
config.deployment

string

Es opcional. Es la implementación de la app que se usará para la sesión. Formato: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
config.timeZone

string

Es opcional. Zona horaria del usuario. Si se proporciona, el agente usará la zona horaria para las variables relacionadas con la fecha y la hora. De lo contrario, el agente usará la zona horaria especificada en App.time_zone_settings.

El formato es la zona horaria de la base de datos de zonas horarias de IANA, p.ej., "America/Los_Angeles".
config.remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

Es opcional. QueryParameters que se enviarán al agente remoto de Dialogflow cuando se transfiera el control de la sesión al agente remoto.
inputs[]

object (SessionInput)

Obligatorio. Son las entradas de la sesión.

Cuerpo de la respuesta

Mensaje de respuesta para SessionService.RunSession.

Si se ejecuta correctamente, el cuerpo de la respuesta contiene datos con la siguiente estructura:

Representación JSON 
{
  "outputs": [
    {
      object (SessionOutput)
    }
  ]
}
Campos
outputs[]

object (SessionOutput)

Son los resultados de la sesión.

Permisos de autorización

Se necesita uno de los siguientes permisos de OAuth:

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

Para obtener más información, consulta Authentication Overview.

Permisos de IAM

Se requiere el siguiente permiso de IAM en el recurso session:

  • ces.sessions.runSession

Para obtener más información, consulta la documentación de IAM.

SessionConfig

Es la configuración de la sesión.

Representación 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

Obligatorio. Es el identificador único de la sesión. Formato: projects/{project}/locations/{location}/apps/{app}/sessions/{session}
inputAudioConfig

object (InputAudioConfig)

Es opcional. Es la configuración para procesar el audio de entrada.
outputAudioConfig

object (OutputAudioConfig)

Es opcional. Es la configuración para generar el audio de salida.
historicalContexts[]

object (Message)

Es opcional. El contexto histórico de la sesión, incluidas las entradas del usuario, las respuestas del agente y otros mensajes. Por lo general, el agente de CES administra la sesión automáticamente, por lo que el cliente no necesita completar este campo de forma explícita. Sin embargo, el cliente puede anular de forma opcional los contextos históricos para forzar el inicio de la sesión desde un estado determinado.
entryAgent

string

Es opcional. Es el agente de entrada para controlar la sesión. Si no se especifica, la sesión la controlará el root agent de la app. Formato: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
deployment

string

Es opcional. Es la implementación de la app que se usará para la sesión. Formato: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
timeZone

string

Es opcional. Zona horaria del usuario. Si se proporciona, el agente usará la zona horaria para las variables relacionadas con la fecha y la hora. De lo contrario, el agente usará la zona horaria especificada en App.time_zone_settings.

El formato es la zona horaria de la base de datos de zonas horarias de IANA, p.ej., "America/Los_Angeles".
remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

Es opcional. QueryParameters que se enviarán al agente remoto de Dialogflow cuando se transfiera el control de la sesión al agente remoto.

InputAudioConfig

InputAudioConfig configura cómo el agente de CES debe interpretar los datos de audio entrantes.

Representación JSON 
{
  "audioEncoding": enum (AudioEncoding),
  "sampleRateHertz": integer,
  "noiseSuppressionLevel": string
}
Campos
audioEncoding

enum (AudioEncoding)

Obligatorio. Es la codificación de los datos de audio de entrada.
sampleRateHertz

integer

Obligatorio. Es la tasa de muestreo (en hercios) de los datos de audio de entrada.
noiseSuppressionLevel

string

Es opcional. Indica si se debe habilitar la supresión de ruido en el audio de entrada. Los valores disponibles son "low", "moderate", "high" y "very_high".

AudioEncoding

AudioEncoding especifica el formato de codificación para los datos de audio.

Enums
AUDIO_ENCODING_UNSPECIFIED Codificación de audio no especificada.
LINEAR16 Codificación de audio PCM lineal de 16 bits.
MULAW Las muestras de 8 bits que comprimen las muestras de audio de 14 bits mediante la ley PCMU/mu-law de G.711.
ALAW Las muestras de 8 bits que comprimen las muestras de audio de 14 bits con la ley PCMU/A-law de G.711.

OutputAudioConfig

OutputAudioConfig configura cómo el agente de CES debe sintetizar las respuestas de audio salientes.

Representación JSON 
{
  "audioEncoding": enum (AudioEncoding),
  "sampleRateHertz": integer
}
Campos
audioEncoding

enum (AudioEncoding)

Obligatorio. Es la codificación de los datos de audio de salida.
sampleRateHertz

integer

Obligatorio. Es la tasa de muestreo (en hercios) de los datos de audio de salida.

SessionConfig.RemoteDialogflowQueryParameters

QueryParameters que se enviarán al agente remoto de Dialogflow cuando se transfiera el control de la sesión al agente remoto.

Representación JSON 
{
  "webhookHeaders": {
    string: string,
    ...
  },
  "payload": {
    object
  },
  "endUserMetadata": {
    object
  }
}
Campos
webhookHeaders

map (key: string, value: string)

Es opcional. Son los encabezados HTTP que se enviarán como webhookHeaders en QueryParameters.

Un objeto que contiene una lista de pares "key": value. Ejemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
payload

object (Struct format)

Es opcional. Es la carga útil que se enviará en QueryParameters.
endUserMetadata

object (Struct format)

Es opcional. Son los metadatos del usuario final que se enviarán en QueryParameters.

SessionInput

Es la entrada de la sesión.

Representación 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

Es opcional. Es una marca que indica si el mensaje actual es un fragmento de una entrada más grande en la sesión de transmisión bidireccional.

Cuando se establece en true, el agente aplaza el procesamiento hasta que recibe un mensaje posterior en el que willContinue es false o hasta que el sistema detecta un extremo en la entrada de audio.

NOTA: Este campo no se aplica a las entradas de audio y DTMF, ya que siempre se procesan automáticamente según la señal de finalización.
Campo de unión input_type. Es el tipo de entrada. input_type puede ser solo uno de los parámetros siguientes:
text

string

Es opcional. Son los datos de texto del usuario final.
dtmf

string

Es opcional. Dígitos de DTMF del usuario final.
audio

string (bytes format)

Es opcional. Son los datos de audio del usuario final.

Es una cadena codificada en Base64.
toolResponses

object (ToolResponses)

Es opcional. Son los resultados de la ejecución de las llamadas a herramientas del cliente.
image

object (Image)

Es opcional. Son los datos de imagen del usuario final.
blob

object (Blob)

Es opcional. Son los datos de BLOB del usuario final.
variables

object (Struct format)

Es opcional. Son las variables contextuales de la sesión, con la clave establecida por el nombre. El agente de CES solo usará las variables declaradas en la app.

Las variables no reconocidas se seguirán enviando al [agente de Dialogflow][Agent.RemoteDialogflowAgent] como parámetros de sesión adicionales.
event

object (Event)

Es opcional. Es la entrada del evento.

ToolResponses

Son los resultados de la ejecución de las llamadas a herramientas solicitadas desde el cliente.

Representación JSON 
{
  "toolResponses": [
    {
      object (ToolResponse)
    }
  ]
}
Campos
toolResponses[]

object (ToolResponse)

Es opcional. Es la lista de resultados de la ejecución de la herramienta.

Evento

Es la entrada del evento.

Representación JSON 
{
  "event": string
}
Campos
event

string

Obligatorio. Es el nombre del evento.

SessionOutput

Es el resultado de la sesión.

Representación 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 el orden secuencial del turno de conversación al que pertenece esta respuesta, comenzando desde 1.
turnCompleted

boolean

Si es verdadero, el agente de CES detectó el final del turno de conversación actual y no proporcionará más resultados para este turno.
diagnosticInfo

object (SessionOutput.DiagnosticInfo)

Es opcional. La información de diagnóstico contiene detalles de la ejecución durante el procesamiento de la entrada. Solo se completa en el último SessionOutput (con turnCompleted=true) de cada turno.
Campo de unión output_type. Es el tipo de salida. output_type puede ser solo uno de los parámetros siguientes:
text

string

Es el texto de salida del agente de CES.
audio

string (bytes format)

Audio de salida del agente de CES.

Es una cadena codificada en Base64.
toolCalls

object (ToolCalls)

Solicitud para que el cliente ejecute las herramientas.
citations

object (Citations)

Son las citas que proporcionan la información de la fuente del texto generado por el agente.
googleSearchSuggestions

object (GoogleSearchSuggestions)

Son las sugerencias que devuelve la Búsqueda de Google como resultado de invocar GoogleSearchTool.
endSession

object (EndSession)

Indica que finalizó la sesión.
payload

object (Struct format)

Es una carga útil personalizada con resultados estructurados del agente de CES.

ToolCalls

Solicitud para que el cliente ejecute las herramientas y muestre los resultados de la ejecución antes de continuar con la sesión.

Representación JSON 
{
  "toolCalls": [
    {
      object (ToolCall)
    }
  ]
}
Campos
toolCalls[]

object (ToolCall)

Es opcional. Es la lista de llamadas a herramientas que se ejecutarán.

Citas

Son las citas asociadas con la respuesta del agente.

Representación JSON 
{
  "citedChunks": [
    {
      object (Citations.CitedChunk)
    }
  ]
}
Campos
citedChunks[]

object (Citations.CitedChunk)

Lista de fragmentos de información citados.

Citations.CitedChunk

Es un fragmento de información citado.

Representación JSON 
{
  "uri": string,
  "title": string,
  "text": string
}
Campos
uri

string

Es el URI que se usa para la cita.
title

string

Es el título del documento citado.
text

string

Es el texto que se usa para la cita.

GoogleSearchSuggestions

Sugerencias de búsqueda de Google Search Tool.

Representación JSON 
{
  "htmls": [
    string
  ],
  "webSearchQueries": [
    {
      object (WebSearchQuery)
    }
  ]
}
Campos
htmls[]

string

Estilo HTML y CSS compatible para las sugerencias de búsqueda. El HTML y CSS proporcionados se adaptan automáticamente a la configuración de tu dispositivo, lo que se muestra en modo oscuro o claro indicado por @media(prefers-color-scheme).
webSearchQueries[]

object (WebSearchQuery)

Es la lista de las búsquedas que se usaron para realizar la Búsqueda de Google, junto con los URIs de los resultados de la búsqueda que forman las sugerencias de búsqueda.

WebSearchQuery

Representa una sola búsqueda web y su URI de búsqueda asociado.

Representación JSON 
{
  "query": string,
  "uri": string
}
Campos
query

string

Es el texto de la búsqueda.
uri

string

Es el URI de la página de resultados de la Búsqueda de Google para la búsqueda.

EndSession

Indica que la sesión finalizó, ya sea por una finalización exitosa (p.ej., el usuario dice "Adiós") ) o una derivación del agente.

El agente no procesará más entradas después de que finalice la sesión, y el cliente debe cerrar la mitad de la conexión y desconectarse después de recibir todas las respuestas restantes del agente.

Representación JSON 
{
  "metadata": {
    object
  }
}
Campos
metadata

object (Struct format)

Es opcional. Proporciona información adicional sobre el evento de finalización de la sesión, como el motivo por el que se finalizó.

SessionOutput.DiagnosticInfo

Contiene detalles de la ejecución durante el procesamiento.

Representación JSON 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "rootSpan": {
    object (Span)
  }
}
Campos
messages[]

object (Message)

Es la lista de los mensajes que se produjeron durante el procesamiento.
rootSpan

object (Span)

Es un registro de todo el procesamiento de la solicitud, representado como un intervalo raíz. Este intervalo puede contener intervalos secundarios anidados para operaciones específicas.