Method: projects.locations.apps.sessions.runSession

Initiates a single-turn interaction with the CES agent within a session.

HTTP request

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

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
config.session

string

Required. The unique identifier of the session. Format: projects/{project}/locations/{location}/apps/{app}/sessions/{session}

Request body

The request body contains data with the following structure:

JSON representation 
{
  "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
      }
    },
    "enableTextStreaming": boolean
  },
  "inputs": [
    {
      object (SessionInput)
    }
  ]
}
Fields
config.inputAudioConfig

object (InputAudioConfig)

Optional. Configuration for processing the input audio.
config.outputAudioConfig

object (OutputAudioConfig)

Optional. Configuration for generating the output audio.
config.historicalContexts[]

object (Message)

Optional. The historical context of the session, including user inputs, agent responses, and other messages. Typically, CES agent would manage session automatically so client doesn't need to explicitly populate this field. However, client can optionally override the historical contexts to force the session start from certain state.
config.entryAgent

string

Optional. The entry agent to handle the session. If not specified, the session will be handled by the root agent of the app. Format: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
config.deployment

string

Optional. The deployment of the app to use for the session. Format: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
config.timeZone

string

Optional. The time zone of the user. If provided, the agent will use the time zone for date and time related variables. Otherwise, the agent will use the time zone specified in the App.time_zone_settings.

The format is the IANA Time Zone Database time zone, e.g. "America/Los_Angeles".
config.useToolFakes

boolean

Optional. Whether to use tool fakes for the session. If this field is set, the agent will attempt use tool fakes instead of calling the real tools.
config.remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

Optional. QueryParameters to send to the remote Dialogflow agent when the session control is transferred to the remote agent.
config.enableTextStreaming

boolean

Optional. Whether to enable streaming text outputs from the model. By default, text outputs from the model are collected before sending to the client. NOTE: This is only supported for text (non-voice) sessions via sessions.streamRunSession or BidiRunSession.
inputs[]

object (SessionInput)

Required. Inputs for the session.

Response body

If successful, the response body contains an instance of RunSessionResponse.

Authorization scopes

Requires one of the following OAuth scopes:

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

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the session resource:

  • ces.sessions.runSession

For more information, see the IAM documentation.