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

ID。評估執行的專屬 ID。格式：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 正規化，並使用 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 正規化，並使用 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)

代表自 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。工具的 ID。tool_identifier 只能是下列其中一個設定：
tool

string

僅供輸出。格式：projects/{project}/locations/{location}/apps/{app}/tools/{tool}。
toolsetTool

object (ToolsetTool)

僅供輸出。工具集工具 ID。

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 個百分位數的延遲時間。

以秒為單位的時間長度，最多 9 個小數位數，結尾為「s」。示例："3.5s"。
p90Latency

string (Duration format)

僅供輸出。第 90 個百分位數的延遲時間。

以秒為單位的時間長度，最多 9 個小數位數，結尾為「s」。示例："3.5s"。
p99Latency

string (Duration format)

僅供輸出。第 99 個百分位數的延遲時間。

以秒為單位的時間長度，最多 9 個小數位數，結尾為「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

時間跨度 (以奈秒為單位) 的正負秒數。如果時間長度不到一秒，系統會以 0 seconds 欄位和正數或負數 nanos 欄位表示。如果時間長度為一秒以上，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 使用 G.711 PCMU/mu-law 來壓縮 14 位元音訊樣本，並在傳輸後將其擴展的 8 位元樣本。
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 Runtime 擷取對話。
METRIC_CALCULATION_FAILURE 無法計算指標 / 結果。
EVALUATION_UPDATE_FAILURE 無法更新評估作業。
QUOTA_EXHAUSTED 配額已用完。
USER_SIMULATION_FAILURE 使用者模擬失敗。

OptimizationStatus

最佳化執行的狀態。

列舉
OPTIMIZATION_STATUS_UNSPECIFIED 未指定最佳化狀態。
RUNNING 最佳化正在執行。
COMPLETED 最佳化作業已完成。
ERROR 發生內部錯誤，因此最佳化失敗。

NullValue

代表 JSON null。

NullValue 是信號，使用只有一個值的列舉，代表 Value 型別聯集的空值。

如果 NullValue 類型的欄位值不是 0，則視為無效。大多數 ProtoJSON 序列化程式都會發出 Value，並將 null_value 設為 JSON null (不論整數值為何)，因此會來回傳輸至 0 值。

列舉
NULL_VALUE 空值。

GoldenRunMethod

用於執行評估的方法。

列舉
GOLDEN_RUN_METHOD_UNSPECIFIED 未指定執行方法。
STABLE 以穩定重播的方式執行評估，其中每個回合都是獨立的工作階段，並會將先前預期的回合插入為情境。
NAIVE 以單純重播方式執行評估，也就是在單一工作階段中執行，且不注入任何內容。

工具註解

工具註解會傳送至 MCP 用戶端，說明特定工具的基本風險。大多數用戶端會將這些提示視為不受信任，但可用於決定何時可能向使用者傳送確認提示。

除了標題字串，以下布林值提示的定義如下：

  • readOnlyHint：如果為 true，工具不會修改環境。預設值為 false。
  • destructiveHint：如果為 true，工具可以執行破壞性動作。如果為 false，工具只能執行加法動作。預設值：true。
  • idempotentHint：如果為 true，以相同引數重複呼叫工具時，不會對環境產生額外影響。預設值為 false。
  • openWorldHint：設為 true 時，工具可與外部實體的「開放世界」互動。如果為 false，工具只能與內部實體互動。舉例來說，網路搜尋工具屬於開放世界，記憶體工具則不屬於開放世界。

破壞性提示：❌ | 等冪提示：✅ | 唯讀提示：✅ | 開放世界提示：❌