Method: projects.locations.apps.sessions.runSession

在会话中启动与 CES 代理的单轮互动。

HTTP 请求

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

网址采用 gRPC 转码语法。

路径参数

参数
config.session

string

必需。会话的唯一标识符。格式：projects/{project}/locations/{location}/apps/{app}/sessions/{session}

请求正文

请求正文中包含结构如下的数据：

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)
    }
  ]
}
字段
config.inputAudioConfig

object (InputAudioConfig)

可选。用于处理输入音频的配置。
config.outputAudioConfig

object (OutputAudioConfig)

可选。用于生成输出音频的配置。
config.historicalContexts[]

object (Message)

可选。会话的历史背景信息，包括用户输入、智能体回答和其他消息。通常，CES 代理会自动管理会话，因此客户端无需明确填充此字段。不过，客户端可以选择替换历史上下文，强制会话从特定状态开始。
config.entryAgent

string

可选。处理会话的初始客服人员。如果未指定，会话将由应用的 root agent 处理。格式：projects/{project}/locations/{location}/apps/{app}/agents/{agent}
config.deployment

string

可选。会话要使用的应用部署。格式：projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
config.timeZone

string

可选。用户的时区。如果提供，代理将使用该时区来处理与日期和时间相关的变量。否则，代理将使用 App.time_zone_settings 中指定的时区。

格式为 IANA 时区数据库中的时区，例如“America/Los_Angeles”。
config.remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

可选。当会话控制权转移到远程 Dialogflow 代理时，要发送给远程代理的 QueryParameters。
inputs[]

object (SessionInput)

必需。会话的输入。

响应正文

SessionService.RunSession 的响应消息。

如果成功，响应正文将包含结构如下的数据：

JSON 表示法 
{
  "outputs": [
    {
      object (SessionOutput)
    }
  ]
}
字段
outputs[]

object (SessionOutput)

会话的输出。

授权范围

需要以下 OAuth 范围之一：

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

如需了解详情，请参阅 Authentication Overview。

IAM 权限

需要拥有 session 资源的以下 IAM 权限：

  • ces.sessions.runSession

如需了解详情，请参阅 IAM 文档。

SessionConfig

会话的配置。

JSON 表示法 
{
  "session": string,
  "inputAudioConfig": {
    object (InputAudioConfig)
  },
  "outputAudioConfig": {
    object (OutputAudioConfig)
  },
  "historicalContexts": [
    {
      object (Message)
    }
  ],
  "entryAgent": string,
  "deployment": string,
  "timeZone": string,
  "remoteDialogflowQueryParameters": {
    object (SessionConfig.RemoteDialogflowQueryParameters)
  }
}
字段
session

string

必需。会话的唯一标识符。格式：projects/{project}/locations/{location}/apps/{app}/sessions/{session}
inputAudioConfig

object (InputAudioConfig)

可选。用于处理输入音频的配置。
outputAudioConfig

object (OutputAudioConfig)

可选。用于生成输出音频的配置。
historicalContexts[]

object (Message)

可选。会话的历史背景信息，包括用户输入、智能体回答和其他消息。通常，CES 代理会自动管理会话，因此客户端无需明确填充此字段。不过，客户端可以选择替换历史上下文，强制会话从特定状态开始。
entryAgent

string

可选。处理会话的初始客服人员。如果未指定，会话将由应用的 root agent 处理。格式：projects/{project}/locations/{location}/apps/{app}/agents/{agent}
deployment

string

可选。会话要使用的应用部署。格式：projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
timeZone

string

可选。用户的时区。如果提供，代理将使用该时区来处理与日期和时间相关的变量。否则，代理将使用 App.time_zone_settings 中指定的时区。

格式为 IANA 时区数据库中的时区，例如“America/Los_Angeles”。
remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

可选。当会话控制权转移到远程 Dialogflow 代理时，要发送给远程代理的 QueryParameters。

InputAudioConfig

InputAudioConfig 用于配置 CES 代理应如何解读传入的音频数据。

JSON 表示法 
{
  "audioEncoding": enum (AudioEncoding),
  "sampleRateHertz": integer,
  "noiseSuppressionLevel": string
}
字段
audioEncoding

enum (AudioEncoding)

必需。输入音频数据的编码。
sampleRateHertz

integer

必需。输入音频数据的采样率（以赫兹为单位）。
noiseSuppressionLevel

string

可选。是否对输入音频启用噪声抑制。可选的值包括“low”“moderate”“high”“very_high”。

AudioEncoding

AudioEncoding 用于指定音频数据的编码格式。

枚举
AUDIO_ENCODING_UNSPECIFIED 未指定音频编码。
LINEAR16 16 位线性 PCM 音频编码。
MULAW 8 位采样，使用 G.711 PCMU/mu-law 压缩 14 位音频采样。
ALAW 8 位采样，使用 G.711 PCMU/A-law 压缩 14 位音频采样。

OutputAudioConfig

OutputAudioConfig 用于配置 CES 代理应如何合成传出的音频响应。

JSON 表示法 
{
  "audioEncoding": enum (AudioEncoding),
  "sampleRateHertz": integer
}
字段
audioEncoding

enum (AudioEncoding)

必需。输出音频数据的编码。
sampleRateHertz

integer

必需。输出音频数据的采样率（以赫兹为单位）。

SessionConfig.RemoteDialogflowQueryParameters

当会话控制权转移到远程 Dialogflow 代理时，要发送给远程代理的 QueryParameters。

JSON 表示法 
{
  "webhookHeaders": {
    string: string,
    ...
  },
  "payload": {
    object
  },
  "endUserMetadata": {
    object
  }
}
字段
webhookHeaders

map (key: string, value: string)

可选。要作为 QueryParameters 中的 webhookHeaders 发送的 HTTP 标头。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
payload

object (Struct format)

可选。要在 QueryParameters 中发送的载荷。
endUserMetadata

object (Struct format)

可选。要在 QueryParameters 中发送的最终用户元数据。

SessionInput

会话的输入。

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.
}
字段
willContinue

boolean

可选。一个标志，用于指示当前消息是否是双向流式会话中较大输入的片段。

如果设置为 true，代理会延迟处理，直到收到 willContinue 为 false 的后续消息，或者直到系统检测到音频输入中的端点。

注意：此字段不适用于音频和 DTMF 输入，因为它们始终会根据端点信号自动处理。
联合字段 input_type。输入的类型。input_type 只能是下列其中一项：
text

string

可选。最终用户的文本数据。
dtmf

string

可选。来自最终用户的 DTMF 数字。
audio

string (bytes format)

可选。最终用户的音频数据。

使用 base64 编码的字符串。
toolResponses

object (ToolResponses)

可选。来自客户端的工具调用的执行结果。
image

object (Image)

可选。最终用户的图片数据。
blob

object (Blob)

可选。来自最终用户的 Blob 数据。
variables

object (Struct format)

可选。会话的上下文变量，按名称键控。CES 代理只会使用在应用中声明的变量。

无法识别的变量仍会作为额外的会话参数发送到 [Dialogflow 代理][Agent.RemoteDialogflowAgent]。
event

object (Event)

可选。活动输入。

ToolResponses

客户端请求的工具调用的执行结果。

JSON 表示法 
{
  "toolResponses": [
    {
      object (ToolResponse)
    }
  ]
}
字段
toolResponses[]

object (ToolResponse)

可选。工具执行结果列表。

事件

活动输入。

JSON 表示法 
{
  "event": string
}
字段
event

string

必需。事件的名称。

SessionOutput

会话的输出。

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.
}
字段
turnIndex

integer

表示相应输出所属对话轮次的顺序，从 1 开始。
turnCompleted

boolean

如果为 true，则表示 CES 代理已检测到当前对话轮次的结束，并且不会再为该轮次提供任何输出。
diagnosticInfo

object (SessionOutput.DiagnosticInfo)

可选。诊断信息包含输入处理期间的执行详细信息。仅在每个轮次的最后一个 SessionOutput（具有 turnCompleted=true）中填充。
联合字段 output_type。输出的类型。output_type 只能是下列其中一项：
text

string

来自 CES 代理的输出文本。
audio

string (bytes format)

CES 代理的输出音频。

使用 base64 编码的字符串。
toolCalls

object (ToolCalls)

请求客户端执行工具。
citations

object (Citations)

提供代理生成的文本的来源信息的引用。
googleSearchSuggestions

object (GoogleSearchSuggestions)

通过调用 GoogleSearchTool 从 Google 搜索返回的建议。
endSession

object (EndSession)

表示会话已结束。
payload

object (Struct format)

包含来自 CES 代理的结构化输出的自定义载荷。

ToolCalls

请求客户端执行工具并返回执行结果，然后再继续会话。

JSON 表示法 
{
  "toolCalls": [
    {
      object (ToolCall)
    }
  ]
}
字段
toolCalls[]

object (ToolCall)

可选。要执行的工具调用的列表。

引用

与代理回答关联的引用。

JSON 表示法 
{
  "citedChunks": [
    {
      object (Citations.CitedChunk)
    }
  ]
}
字段
citedChunks[]

object (Citations.CitedChunk)

引用信息列表。

Citations.CitedChunk

引用信息。

JSON 表示法 
{
  "uri": string,
  "title": string,
  "text": string
}
字段
uri

string

用于引用的 URI。
title

string

被引用文档的标题。
text

string

用于引用的文本。

GoogleSearchSuggestions

来自 Google Search Tool 的搜索建议。

JSON 表示法 
{
  "htmls": [
    string
  ],
  "webSearchQueries": [
    {
      object (WebSearchQuery)
    }
  ]
}
字段
htmls[]

string

搜索建议的合规 HTML 和 CSS 样式。提供的 HTML 和 CSS 会自动适应您的设备设置，根据 @media(prefers-color-scheme) 所指示的偏好设置以浅色或深色模式显示。
webSearchQueries[]

object (WebSearchQuery)

用于执行 Google 搜索的查询的列表，以及构成搜索建议的搜索结果 URI。

WebSearchQuery

表示单个网络搜索查询及其关联的搜索 URI。

JSON 表示法 
{
  "query": string,
  "uri": string
}
字段
query

string

搜索查询文本。
uri

string

相应查询的 Google 搜索结果页面的 URI。

EndSession

表示会话已终止，原因可能是成功完成（例如，用户说“再见！”）或代理升级。

会话终止后，代理将不再处理任何进一步的输入，并且客户端应在收到代理发送的所有剩余响应后半关闭并断开连接。

JSON 表示法 
{
  "metadata": {
    object
  }
}
字段
metadata

object (Struct format)

可选。提供有关结束会话信号的其他信息，例如结束会话的原因。

SessionOutput.DiagnosticInfo

包含处理期间的执行详情。

JSON 表示法 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "rootSpan": {
    object (Span)
  }
}
字段
messages[]

object (Message)

处理期间发生的消息的列表。
rootSpan

object (Span)

整个请求处理过程的轨迹，以根 span 表示。此 span 可以包含用于特定操作的嵌套子 span。