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
  },
  "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}/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".
inputs[]

object (SessionInput)

Required. Inputs for the session.

Response body

Response message for SessionService.RunSession.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "outputs": [
    {
      object (SessionOutput)
    }
  ]
}
Fields
outputs[]

object (SessionOutput)

Outputs for the session.

Authorization scopes

Requires the following OAuth scope:

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

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.

SessionConfig

The configuration for the session.

JSON representation 
{
  "session": string,
  "inputAudioConfig": {
    object (InputAudioConfig)
  },
  "outputAudioConfig": {
    object (OutputAudioConfig)
  },
  "historicalContexts": [
    {
      object (Message)
    }
  ],
  "entryAgent": string,
  "deployment": string,
  "timeZone": string
}
Fields
session

string

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

object (InputAudioConfig)

Optional. Configuration for processing the input audio.
outputAudioConfig

object (OutputAudioConfig)

Optional. Configuration for generating the output audio.
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.
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}/agents/{agent}
deployment

string

Optional. The deployment of the app to use for the session. Format: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
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".

InputAudioConfig

InputAudioConfig configures how the CES agent should interpret incoming audio data.

JSON representation 
{
  "audioEncoding": enum (AudioEncoding),
  "sampleRateHertz": integer,
  "noiseSuppressionLevel": string
}
Fields
audioEncoding

enum (AudioEncoding)

Required. The encoding of the input audio data.
sampleRateHertz

integer

Optional. The sample rate (in Hertz) of the input audio data.
noiseSuppressionLevel

string

Optional. Whether to enable noise suppression on the input audio. Available values are "low", "moderate", "high", "very_high".

AudioEncoding

AudioEncoding specifies the encoding format for audio data.

Enums
AUDIO_ENCODING_UNSPECIFIED Unspecified audio encoding.
LINEAR16 16-bit linear PCM audio encoding.
MULAW 8-bit samples that compand 14-bit audio samples using G.711 PCMU/mu-law.
ALAW 8-bit samples that compand 14-bit audio samples using G.711 PCMU/A-law.

OutputAudioConfig

OutputAudioConfig configures how the CES agent should synthesize outgoing audio responses.

JSON representation 
{
  "audioEncoding": enum (AudioEncoding),
  "sampleRateHertz": integer
}
Fields
audioEncoding

enum (AudioEncoding)

Required. The encoding of the output audio data.
sampleRateHertz

integer

Optional. The sample rate (in Hertz) of the output audio data.

SessionInput

Input for the session.

JSON representation 
{
  "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.
}
Fields
willContinue

boolean

Optional. A flag to indicate if the current message is a fragment of a larger input in the bidi streaming session. When true, the agent will defer processing until a subsequent message with willContinue set to false is received.

Note: This flag has no effect on audio and DTMF inputs, which are always processed in real-time.
Union field input_type. The type of the input. input_type can be only one of the following:
text

string

Optional. Text data from the end user.
dtmf

string

Optional. DTMF digits from the end user.
audio

string (bytes format)

Optional. Audio data from the end user.

A base64-encoded string.
toolResponses

object (ToolResponses)

Optional. Execution results for the tool calls from the client.
image

object (Image)

Optional. Image data from the end user.
blob

object (Blob)

Optional. Blob data from the end user.
variables

object (Struct format)

Optional. Contextual variables for the session, keyed by name. Variables must be declared in the app first, otherwise they will be ignored.
event

object (Event)

Optional. Event input.

ToolResponses

Execution results for the requested tool calls from the client.

JSON representation 
{
  "toolResponses": [
    {
      object (ToolResponse)
    }
  ]
}
Fields
toolResponses[]

object (ToolResponse)

Optional. The list of tool execution results.

Blob

Represents a blob input or output in the conversation.

JSON representation 
{
  "mimeType": string,
  "data": string
}
Fields
mimeType

string

Required. The IANA standard MIME type of the source data.
data

string (bytes format)

Required. Raw bytes of the blob.

A base64-encoded string.

Event

Event input.

JSON representation 
{
  "event": string
}
Fields
event

string

Required. The name of the event.

SessionOutput

Output for the session.

JSON representation 
{
  "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.
}
Fields
turnIndex

integer

Indicates the sequential order of conversation turn to which this output belongs to, starting from 1.
turnCompleted

boolean

If true, the CES agent has detected the end of the current conversation turn and will provide no further output for this turn.
diagnosticInfo

object (SessionOutput.DiagnosticInfo)

Optional. Diagnostic information contains execution details during the processing of the input. Only populated in the last SessionOutput (with turnCompleted=true) for each turn.
Union field output_type. The type of the output. output_type can be only one of the following:
text

string

Output text from the CES agent.
audio

string (bytes format)

Output audio from the CES agent.

A base64-encoded string.
toolCalls

object (ToolCalls)

Request for the client to execute the tools.
citations

object (Citations)

Citations that provide the source information for the agent's generated text.
googleSearchSuggestions

object (GoogleSearchSuggestions)

The suggestions returned from Google Search as a result of invoking the GoogleSearchTool.
endSession

object (EndSession)

Indicates the session has ended.
payload

object (Struct format)

Custom payload with structured output from the CES agent.

ToolCalls

Request for the client to execute the tools and return the execution results before continuing the session.

JSON representation 
{
  "toolCalls": [
    {
      object (ToolCall)
    }
  ]
}
Fields
toolCalls[]

object (ToolCall)

Optional. The list of tool calls to execute.

Citations

Citations associated with the agent response.

JSON representation 
{
  "citedChunks": [
    {
      object (Citations.CitedChunk)
    }
  ]
}
Fields
citedChunks[]

object (Citations.CitedChunk)

List of cited pieces of information.

Citations.CitedChunk

Piece of cited information.

JSON representation 
{
  "uri": string,
  "title": string,
  "text": string
}
Fields
uri

string

URI used for citation.
title

string

Title of the cited document.
text

string

Text used for citaiton.

GoogleSearchSuggestions

Search suggestions from Google Search Tool.

JSON representation 
{
  "htmls": [
    string
  ],
  "webSearchQueries": [
    {
      object (WebSearchQuery)
    }
  ]
}
Fields
htmls[]

string

Compliant HTML and CSS styling for search suggestions. The provided HTML and CSS automatically adapts to your device settings, displaying in either light or dark mode indicated by @media(prefers-color-scheme).
webSearchQueries[]

object (WebSearchQuery)

List of queries used to perform the google search along with the search result URIs forming the search suggestions.

WebSearchQuery

Represents a single web search query and its associated search uri.

JSON representation 
{
  "query": string,
  "uri": string
}
Fields
query

string

The search query text.
uri

string

The URI to the Google Search results page for the query.

EndSession

Indicates the session has terminated, due to either successful completion (e.g. user says "Good bye!" ) or an agent escalation.

The agent will not process any further inputs after session is terminated and the client should half-close and disconnect after receiving all remaining responses from the agent.

JSON representation 
{
  "metadata": {
    object
  }
}
Fields
metadata

object (Struct format)

Optional. Provides additional information about the end session signal, such as the reason for ending the session.

SessionOutput.DiagnosticInfo

Contains execution details during the processing.

JSON representation 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "rootSpan": {
    object (Span)
  }
}
Fields
messages[]

object (Message)

List of the messages that happened during the processing.
rootSpan

object (Span)

A trace of the entire request processing, represented as a root span. This span can contain nested child spans for specific operations.