MCP Tools Reference: ces.googleapis.com

工具：get_evaluation_run

获取指定评估运行的详细信息。

以下代码示例展示了如何使用 curl 调用 get_evaluation_run MCP 工具。

Curl 请求 
curl --location 'https://ces.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "get_evaluation_run",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

输入架构

EvaluationService.GetEvaluationRun 的请求消息。

GetEvaluationRunRequest

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

string

必需。要检索的评估运行的资源名称。

输出架构

评估运行是指评估执行中的所有评估结果。

EvaluationRun

JSON 表示法 
{
  "name": string,
  "displayName": string,
  "evaluationResults": [
    string
  ],
  "createTime": string,
  "initiatedBy": string,
  "appVersion": string,
  "appVersionDisplayName": string,
  "changelog": string,
  "changelogCreateTime": string,
  "evaluations": [
    string
  ],
  "evaluationDataset": string,
  "evaluationType": enum (EvaluationType),
  "state": enum (EvaluationRunState),
  "progress": {
    object (Progress)
  },
  "config": {
    object (EvaluationConfig)
  },
  "error": {
    object (Status)
  },
  "errorInfo": {
    object (EvaluationErrorInfo)
  },
  "evaluationRunSummaries": {
    string: {
      object (EvaluationRunSummary)
    },
    ...
  },
  "latencyReport": {
    object (LatencyReport)
  },
  "runCount": integer,
  "personaRunConfigs": [
    {
      object (PersonaRunConfig)
    }
  ],
  "optimizationConfig": {
    object (OptimizationConfig)
  },
  "scheduledEvaluationRun": string,
  "goldenRunMethod": enum (GoldenRunMethod),
  "operation": string
}
字段
name

string

标识符。评估运行的唯一标识符。格式：projects/{project}/locations/{location}/apps/{app}/evaluationRuns/{evaluationRun}
displayName

string

可选。评估运行的用户定义显示名称。默认值：“ run - ”。
evaluationResults[]

string

仅限输出。相应运行作业的评估结果。格式：projects/{project}/locations/{location}/apps/{app}/evaluations/{evaluation}/results/{result}
createTime

string (Timestamp format)

仅限输出。评估运行的创建时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
initiatedBy

string

仅限输出。发起评估运行的用户。
appVersion

string

仅限输出。要评估的应用版本。格式：projects/{project}/locations/{location}/apps/{app}/versions/{version}
appVersionDisplayName

string

仅限输出。评估所针对的 app_version 的显示名称。
changelog

string

仅限输出。评估所针对的应用版本的更改日志。如果用户对最新版本/草稿运行评估，则会填充此字段。
changelogCreateTime

string (Timestamp format)

仅限输出。评估所针对的应用版本对应的更改日志的创建时间。如果用户对最新版本/草稿运行评估，则会填充此字段。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
evaluations[]

string

仅限输出。相应运行中包含的评估。该列表可能包含任一类型的评估。此字段与 evaluation_dataset 互斥。格式：projects/{project}/locations/{location}/apps/{app}/evaluations/{evaluation}
evaluationDataset

string

仅限输出。相应运行所关联的评估数据集。此字段与 evaluations 互斥。格式：projects/{project}/locations/{location}/apps/{app}/evaluationDatasets/{evaluationDataset}
evaluationType

enum (EvaluationType)

仅限输出。相应运行中的评估类型。
state

enum (EvaluationRunState)

仅限输出。评估运行的状态。
progress

object (Progress)

仅限输出。评估运行的进度。
config

object (EvaluationConfig)

仅限输出。运行中使用的配置。
error
(deprecated)

object (Status)

仅限输出。已弃用：请改用 error_info。执行期间遇到错误。
errorInfo

object (EvaluationErrorInfo)

仅限输出。评估运行的错误信息。
evaluationRunSummaries

map (key: string, value: object (EvaluationRunSummary))

仅限输出。从评估名称到 EvaluationRunSummary 的映射。

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

object (LatencyReport)

仅限输出。评估运行的延迟报告。
runCount

integer

仅限输出。运行中评估的运行次数。
personaRunConfigs[]

object (PersonaRunConfig)

仅限输出。每次运行时使用的配置（按角色）。
optimizationConfig

object (OptimizationConfig)

可选。在评估运行后运行优化步骤的配置。如果未设置，则不会运行优化步骤。
scheduledEvaluationRun

string

仅限输出。创建相应评估运行的已安排的评估运行资源名称。仅当评估运行是由已安排的评估运行创建时，才设置此字段。格式：projects/{project}/locations/{location}/apps/{app}/scheduledEvaluationRuns/{scheduled_evaluation_run}
goldenRunMethod

enum (GoldenRunMethod)

仅限输出。用于运行评估的方法。
operation

string

仅限输出。创建相应评估运行的操作。格式：projects/{project}/locations/{location}/operations/{operation}

时间戳

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
字段
seconds

string (int64 format)

表示世界协调时间 (UTC) 的秒数（从 Unix 纪元 1970-01-01T00:00:00Z 开始算起）。必须介于 -62135596800 和 253402300799 之间（含边界值），对应于 0001-01-01T00:00:00Z 到 9999-12-31T23:59:59Z。
nanos

integer

秒数的非负小数部分（以纳秒为单位）。此字段是时长的纳秒部分，而不是秒的替代项。对于含小数部分的负秒数，仍必须包含按时间递升的非负纳秒值。必须在 0 到 999,999,999 之间（含边界值）。

进度

JSON 表示法 
{
  "totalCount": integer,
  "failedCount": integer,
  "errorCount": integer,
  "completedCount": integer,
  "passedCount": integer,
  "cancelledCount": integer
}
字段
totalCount

integer

仅限输出。相应运行中的评估结果总数。
failedCount

integer

仅限输出。结果为“失败”的已完成评估结果的数量。（EvaluationResult.execution_state 为 COMPLETED，且 EvaluationResult.evaluation_status 为 FAIL）。
errorCount

integer

仅限输出。未能执行的评估结果数量。（EvaluationResult.execution_state 为 ERROR）。
completedCount

integer

仅限输出。成功完成的评估结果数量。（EvaluationResult.execution_state 为 COMPLETED）。
passedCount

integer

仅限输出。结果为“通过”的已完成评估结果的数量。（EvaluationResult.execution_state 为 COMPLETED，且 EvaluationResult.evaluation_status 为 PASS）。
cancelledCount

integer

仅限输出。已取消的评估结果数量。（EvaluationResult.execution_state 为 CANCELLED）。

EvaluationConfig

JSON 表示法 
{
  "inputAudioConfig": {
    object (InputAudioConfig)
  },
  "outputAudioConfig": {
    object (OutputAudioConfig)
  },
  "evaluationChannel": enum (EvaluationChannel),
  "toolCallBehaviour": enum (EvaluationToolCallBehaviour)
}
字段
inputAudioConfig

object (InputAudioConfig)

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

object (OutputAudioConfig)

可选。用于生成输出音频的配置。
evaluationChannel

enum (EvaluationChannel)

可选。要评估的渠道。
toolCallBehaviour

enum (EvaluationToolCallBehaviour)

可选。指定评估应使用真实的工具调用还是虚假的工具。

InputAudioConfig

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

enum (AudioEncoding)

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

integer

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

string

可选。是否对输入音频启用噪音抑制 : 降噪。可用的值为“low”“moderate”“high”“very_high”。

OutputAudioConfig

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

enum (AudioEncoding)

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

integer

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

状态

JSON 表示法 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
字段
code

integer

状态代码，应为 google.rpc.Code 的枚举值。
message

string

面向开发者的错误消息（应采用英语）。任何向用户显示的错误消息都应进行本地化并通过 google.rpc.Status.details 字段发送，或者由客户端进行本地化。
details[]

object

包含错误详细信息的消息列表。有一组通用的消息类型可供 API 使用。

可以包含任意类型字段的对象。附加字段 "@type" 包含用于标示相应类型的 URI。示例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

不限

JSON 表示法 
{
  "typeUrl": string,
  "value": string
}
字段
typeUrl

string

通过 URI 引用（由以斜杠结尾的前缀和完全限定的类型名称组成）标识序列化 Protobuf 消息的类型。

示例：type.googleapis.com/google.protobuf.StringValue

此字符串必须包含至少一个 / 字符，并且最后一个 / 之后的内容必须是规范形式的完全限定名，且不含前导点。请勿在这些 URI 引用中写入方案，以免客户端尝试联系它们。

前缀是任意的，Protobuf 实现应仅剥离最后一个 / 之前（包括最后一个 /）的所有内容，以识别类型。type.googleapis.com/ 是某些旧版实现所需的常见默认前缀。此前缀并不表示类型的来源，包含该前缀的 URI 不会响应任何请求。

所有类型网址字符串都必须是合法的 URI 引用，并且（对于文本格式）还必须满足以下额外限制：引用的内容只能包含字母数字字符、百分号编码的转义字符以及以下集合中的字符（不包括外侧的反引号）：/-.~_!$&()*+,;=。尽管我们允许使用百分号编码，但实现不应对其进行转义，以免与现有解析器混淆。例如，应拒绝 type.googleapis.com%2FFoo。

在 Any 的原始设计中，曾考虑过在这些类型网址上启动类型解析服务的可能性，但 Protobuf 从未实现过此类服务，并且认为联系这些网址存在问题，可能会导致安全问题。请勿尝试联系人类型网址。
value

string (bytes format)

包含由 type_url 描述的类型的 Protobuf 序列化。

使用 base64 编码的字符串。

EvaluationErrorInfo

JSON 表示法 
{
  "errorType": enum (ErrorType),
  "errorMessage": string,
  "sessionId": string,
  "userFacingErrorMessage": string
}
字段
errorType

enum (ErrorType)

仅限输出。错误类型。
errorMessage

string

仅限输出。错误消息。
sessionId

string

仅限输出。导致错误的对话的会话 ID。
userFacingErrorMessage

string

仅限输出。面向用户的错误消息。

EvaluationRunSummariesEntry

JSON 表示法 
{
  "key": string,
  "value": {
    object (EvaluationRunSummary)
  }
}
字段
key

string
value

object (EvaluationRunSummary)

EvaluationRunSummary

JSON 表示法 
{
  "passedCount": integer,
  "failedCount": integer,
  "errorCount": integer
}
字段
passedCount

integer

仅限输出。相应评估在此运行中的通过结果数。
failedCount

integer

仅限输出。相应评估在此运行中的失败结果数。
errorCount

integer

仅限输出。相应评估在此运行中的错误结果数。

LatencyReport

JSON 表示法 
{
  "toolLatencies": [
    {
      object (ToolLatency)
    }
  ],
  "callbackLatencies": [
    {
      object (CallbackLatency)
    }
  ],
  "guardrailLatencies": [
    {
      object (GuardrailLatency)
    }
  ],
  "llmCallLatencies": [
    {
      object (LlmCallLatency)
    }
  ],
  "sessionCount": integer
}
字段
toolLatencies[]

object (ToolLatency)

仅限输出。无序列表。每种工具的延迟时间指标。
callbackLatencies[]

object (CallbackLatency)

仅限输出。无序列表。每个回调的延迟时间指标。
guardrailLatencies[]

object (GuardrailLatency)

仅限输出。无序列表。每个安全措施的延迟时间指标。
llmCallLatencies[]

object (LlmCallLatency)

仅限输出。无序列表。每次 LLM 调用的延迟时间指标。
sessionCount

integer

仅限输出。延迟时间报告中考虑的会话总数。

ToolLatency

JSON 表示法 
{
  "toolDisplayName": string,
  "latencyMetrics": {
    object (LatencyMetrics)
  },

  // Union field tool_identifier can be only one of the following:
  "tool": string,
  "toolsetTool": {
    object (ToolsetTool)
  }
  // End of list of possible types for union field tool_identifier.
}
字段
toolDisplayName

string

仅限输出。工具的显示名称。
latencyMetrics

object (LatencyMetrics)

仅限输出。工具的延迟时间指标。
联合字段 tool_identifier。工具的标识符。tool_identifier 只能是下列其中一项：
tool

string

仅限输出。格式：projects/{project}/locations/{location}/apps/{app}/tools/{tool}。
toolsetTool

object (ToolsetTool)

仅限输出。工具集工具标识符。

ToolsetTool

JSON 表示法 
{
  "toolset": string,
  "toolId": string
}
字段
toolset

string

必需。相应工具所源自的工具集的资源名称。格式：projects/{project}/locations/{location}/apps/{app}/toolsets/{toolset}
toolId

string

可选。用于过滤工具的工具 ID，以检索相应工具的架构。

LatencyMetrics

JSON 表示法 
{
  "p50Latency": string,
  "p90Latency": string,
  "p99Latency": string,
  "callCount": integer
}
字段
p50Latency

string (Duration format)

仅限输出。第 50 百分位的延迟时间。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
p90Latency

string (Duration format)

仅限输出。第 90 百分位的延迟时间。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
p99Latency

string (Duration format)

仅限输出。第 99 百分位的延迟时间。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
callCount

integer

仅限输出。资源被调用的次数。

时长

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
字段
seconds

string (int64 format)

时间段的带符号秒数。必须介于 -315,576,000,000 到 +315,576,000,000 之间（含边界值）。注意：这些界限是通过以下计算得出的：60 秒/分钟 * 60 分钟/小时 * 24 小时/天 * 365.25 天/年 * 10000 年
nanos

integer

时间跨度的有符号秒数小数部分（以纳秒为单位）。小于 1 秒的时长用 0 seconds 字段和正或负 nanos 字段表示。对于时长为 1 秒或更长时间的视频，nanos 字段的非零值必须与 seconds 字段的符号相同。必须介于 -999,999,999 到 +999,999,999 之间（含边界值）。

CallbackLatency

JSON 表示法 
{
  "stage": string,
  "latencyMetrics": {
    object (LatencyMetrics)
  }
}
字段
stage

string

仅限输出。回调的阶段。
latencyMetrics

object (LatencyMetrics)

仅限输出。回调的延迟时间指标。

GuardrailLatency

JSON 表示法 
{
  "guardrail": string,
  "guardrailDisplayName": string,
  "latencyMetrics": {
    object (LatencyMetrics)
  }
}
字段
guardrail

string

仅限输出。防护栏的名称。格式：projects/{project}/locations/{location}/apps/{app}/guardrails/{guardrail}。
guardrailDisplayName

string

仅限输出。安全防护措施的显示名称。
latencyMetrics

object (LatencyMetrics)

仅限输出。护栏的延迟时间指标。

LlmCallLatency

JSON 表示法 
{
  "model": string,
  "latencyMetrics": {
    object (LatencyMetrics)
  }
}
字段
model

string

仅限输出。模型的名称。
latencyMetrics

object (LatencyMetrics)

仅限输出。LLM 调用的延迟时间指标。

PersonaRunConfig

JSON 表示法 
{
  "persona": string,
  "taskCount": integer
}
字段
persona

string

可选。用于评估的角色。格式：projects/{project}/locations/{location}/apps/{app}/evaluationPersonas/{evaluationPersona}
taskCount

integer

可选。要为角色运行的任务数量。

OptimizationConfig

JSON 表示法 
{
  "generateLossReport": boolean,
  "assistantSession": string,
  "reportSummary": string,
  "shouldSuggestFix": boolean,
  "status": enum (OptimizationStatus),
  "errorMessage": string,
  "lossReport": {
    object
  }
}
字段
generateLossReport

boolean

可选。是否生成丢失报告。
assistantSession

string

仅限输出。用于根据此评估运行结果进行优化的助理会话。格式：projects/{project}/locations/{location}/apps/{app}/assistantSessions/{assistantSession}
reportSummary

string

仅限输出。丢失报告的摘要。
shouldSuggestFix

boolean

仅限输出。是否建议修复损失。
status

enum (OptimizationStatus)

仅限输出。优化运行的状态。
errorMessage

string

仅限输出。如果优化运行失败，则返回错误消息。
lossReport

object (Struct format)

仅限输出。生成的损失报告。

结构体

JSON 表示法 
{
  "fields": {
    string: value,
    ...
  }
}
字段
fields

map (key: string, value: value (Value format))

无序的动态类型值映射。

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

FieldsEntry

JSON 表示法 
{
  "key": string,
  "value": value
}
字段
key

string
value

value (Value format)

值

JSON 表示法 
{

  // Union field kind can be only one of the following:
  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
  // End of list of possible types for union field kind.
}
字段
联合字段 kind。值的类型。kind 只能是下列其中一项：
nullValue

null

表示 JSON null。
numberValue

number

表示 JSON 数字。不得为 NaN、Infinity 或 -Infinity，因为 JSON 不支持这些值。此外，由于 JSON 格式通常不支持在其数字类型中使用较大的 Int64 值，因此该格式也无法表示这些值。
stringValue

string

表示 JSON 字符串。
boolValue

boolean

表示 JSON 布尔值（JSON 中的 true 或 false 字面量）。
structValue

object (Struct format)

表示 JSON 对象。
listValue

array (ListValue format)

表示 JSON 数组。

ListValue

JSON 表示法 
{
  "values": [
    value
  ]
}
字段
values[]

value (Value format)

动态类型值的重复字段。

EvaluationType

相应运行中的评估类型。未来可能会添加其他值。

枚举
EVALUATION_TYPE_UNSPECIFIED 未指定评估类型。
GOLDEN 黄金评估。
SCENARIO 场景评估。
MIXED 表示运行包含黄金评估和场景评估。

EvaluationRunState

评估运行的状态。

枚举
EVALUATION_RUN_STATE_UNSPECIFIED 未指定评估运行状态。
QUEUED 表示评估运行已加入队列。
RUNNING 评估运行正在运行。
COMPLETED 评估运行已完成。
ERROR 评估运行出错。
CANCELLED 评估运行已取消。

AudioEncoding

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

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

EvaluationChannel

要评估的渠道。

枚举
EVALUATION_CHANNEL_UNSPECIFIED 未指定的评估渠道。
TEXT 纯文本评估渠道。
AUDIO 音频评估渠道。

EvaluationToolCallBehaviour

为评估运行配置工具调用行为。

枚举
EVALUATION_TOOL_CALL_BEHAVIOUR_UNSPECIFIED 未指定工具调用行为。默认设置为真实工具调用。
REAL 使用真实的工具调用。
FAKE 使用虚假工具调用。

ErrorType

错误类型

枚举
ERROR_TYPE_UNSPECIFIED 未指明的错误类型。
RUNTIME_FAILURE 运行时执行期间失败。
CONVERSATION_RETRIEVAL_FAILURE 未能从 CES 运行时检索对话。
METRIC_CALCULATION_FAILURE 未能计算指标 / 结果。
EVALUATION_UPDATE_FAILURE 未能更新评估。
QUOTA_EXHAUSTED 配额已用尽。
USER_SIMULATION_FAILURE 用户模拟期间出现故障。

OptimizationStatus

优化运行的状态。

枚举
OPTIMIZATION_STATUS_UNSPECIFIED 未指定优化状态。
RUNNING 优化正在运行。
COMPLETED 优化已完成。
ERROR 由于内部错误，优化失败。

NullValue

表示 JSON null。

NullValue 是一个标记，使用只有一个值的枚举来表示 Value 类型联合的 null 值。

如果类型为 NullValue 的字段的值不是 0，则视为无效。大多数 ProtoJSON 序列化程序都会发出一个 Value，并将 null_value 设置为 JSON null，无论整数值是多少，因此会往返于 0 值。

枚举
NULL_VALUE Null 值。

GoldenRunMethod

用于运行评估的方法。

枚举
GOLDEN_RUN_METHOD_UNSPECIFIED 未指定运行方法。
STABLE 以稳定重放模式运行评估，其中每个回合都是一个独特的会话，并注入了之前的预期回合作为上下文。
NAIVE 以简单重放方式运行评估，其中运行是单个会话，不注入任何上下文。

工具注释

工具注释会发送给 MCP 客户端，用于描述指定工具的基本风险。大多数客户端会将这些提示视为不受信任的，但它们可用于确定何时向用户发送确认提示。

除了标题字符串之外，还定义了以下布尔值提示：

  • readOnlyHint：如果为 true，则工具不会修改其环境。默认值：false。
  • destructiveHint：如果为 true，则工具可以执行破坏性操作。如果为 false，则该工具只能执行添加操作。默认值：true。
  • idempotentHint：如果为 true，则使用相同实参重复调用该工具不会对其环境产生任何额外影响。默认值：false。
  • openWorldHint：如果为 true，则工具可以与外部实体的“开放世界”进行交互。如果为 false，则该工具只能与内部实体互动。例如，网络搜索工具是开放世界，而内存工具不是开放世界。

破坏性提示：❌ | 等幂性提示：✅ | 只读提示：✅ | 开放世界提示：❌