MCP Tools Reference: ces.googleapis.com

工具：create_agent

在指定应用中创建新代理。

以下示例演示了如何使用 curl 调用 create_agent MCP 工具。

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

输入架构

AgentService.CreateAgent 的请求消息。

CreateAgentRequest

JSON 表示法 
{
  "parent": string,
  "agentId": string,
  "agent": {
    object (Agent)
  }
}
字段
parent

string

必需。要在其中创建代理的应用的资源名称。
agentId

string

可选。要用于代理的 ID，该 ID 将成为代理资源名称的最后一个组成部分。如果未提供，系统会自动为代理分配唯一 ID。
agent

object (Agent)

必需。要创建的代理。

代理

JSON 表示法 
{
  "name": string,
  "displayName": string,
  "description": string,
  "modelSettings": {
    object (ModelSettings)
  },
  "instruction": string,
  "tools": [
    string
  ],
  "childAgents": [
    string
  ],
  "beforeAgentCallbacks": [
    {
      object (Callback)
    }
  ],
  "afterAgentCallbacks": [
    {
      object (Callback)
    }
  ],
  "beforeModelCallbacks": [
    {
      object (Callback)
    }
  ],
  "afterModelCallbacks": [
    {
      object (Callback)
    }
  ],
  "beforeToolCallbacks": [
    {
      object (Callback)
    }
  ],
  "afterToolCallbacks": [
    {
      object (Callback)
    }
  ],
  "createTime": string,
  "updateTime": string,
  "guardrails": [
    string
  ],
  "etag": string,
  "toolsets": [
    {
      object (AgentToolset)
    }
  ],
  "generatedSummary": string,
  "transferRules": [
    {
      object (TransferRule)
    }
  ],

  // Union field agent_type can be only one of the following:
  "llmAgent": {
    object (LlmAgent)
  },
  "remoteDialogflowAgent": {
    object (RemoteDialogflowAgent)
  }
  // End of list of possible types for union field agent_type.
}
字段
name

string

标识符。代理的唯一标识符。格式：projects/{project}/locations/{location}/apps/{app}/agents/{agent}
displayName

string

必需。代理的显示名称。
description

string

可选。代理的人类可读说明。
modelSettings

object (ModelSettings)

可选。LLM 模型的配置。
instruction

string

可选。用于指导代理行为的 LLM 模型指令。
tools[]

string

可选。代理可用的工具列表。格式：projects/{project}/locations/{location}/apps/{app}/tools/{tool}
childAgents[]

string

可选。代理树中的子代理列表。格式：projects/{project}/locations/{location}/apps/{app}/agents/{agent}
beforeAgentCallbacks[]

object (Callback)

可选。在调用代理之前要执行的回调。所提供的回调会按列表中的顺序依次执行。如果回调返回了替换的响应，则执行会停止，并跳过所有剩余的回调。
afterAgentCallbacks[]

object (Callback)

可选。在调用代理后要执行的回调。所提供的回调会按列表中的顺序依次执行。如果回调返回了替换的响应，则执行会停止，并跳过所有剩余的回调。
beforeModelCallbacks[]

object (Callback)

可选。在调用模型之前要执行的回调。如果多次调用模型，则回调将执行多次。所提供的回调会按列表中的顺序依次执行。如果回调返回了替换的响应，则执行会停止，并跳过所有剩余的回调。
afterModelCallbacks[]

object (Callback)

可选。在调用模型后要执行的回调。如果多次调用模型，则回调将执行多次。所提供的回调会按列表中的顺序依次执行。如果回调返回了替换的响应，则执行会停止，并跳过所有剩余的回调。
beforeToolCallbacks[]

object (Callback)

可选。在调用工具之前要执行的回调。如果存在多次工具调用，则回调将执行多次。所提供的回调会按列表中的顺序依次执行。如果回调返回了替换的响应，则执行会停止，并跳过所有剩余的回调。
afterToolCallbacks[]

object (Callback)

可选。在调用工具后要执行的回调。如果存在多次工具调用，则回调将执行多次。所提供的回调会按列表中的顺序依次执行。如果回调返回了替换的响应，则执行会停止，并跳过所有剩余的回调。
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"。
updateTime

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"。
guardrails[]

string

可选。代理的护栏列表。格式：projects/{project}/locations/{location}/apps/{app}/guardrails/{guardrail}
etag

string

用于确保对象在读取-修改-写入操作期间未发生更改的 ETag。如果 etag 为空，则更新会覆盖任何并发更改。
toolsets[]

object (AgentToolset)

可选。代理的工具集列表。
generatedSummary

string

仅限输出。如果代理由 LLM 助理生成，此字段会包含生成内容的描述性摘要。
transferRules[]

object (TransferRule)

可选。客服人员转移规则。如果多个规则匹配，系统将使用列表中的第一个规则。
联合字段 agent_type。代理的类型。agent_type 只能是下列其中一项：
llmAgent

object (LlmAgent)

可选。默认代理类型。
remoteDialogflowAgent

object (RemoteDialogflowAgent)

可选。用于执行代理的远程 Dialogflow 代理。如果设置了此字段，系统将忽略所有其他代理级属性。

注意：如果 Dialogflow 代理与应用位于不同的项目中，您应向 CES 服务代理 service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com 授予 roles/dialogflow.client 权限。

RemoteDialogflowAgent

JSON 表示法 
{
  "agent": string,
  "flowId": string,
  "environmentId": string,
  "inputVariableMapping": {
    string: string,
    ...
  },
  "outputVariableMapping": {
    string: string,
    ...
  },
  "respectResponseInterruptionSettings": boolean
}
字段
agent

string

必需。Dialogflow 代理资源名称。格式：projects/{project}/locations/{location}/agents/{agent}
flowId

string

可选。Dialogflow 代理中相应流的流 ID。
environmentId

string

可选。要用于代理执行的 Dialogflow 代理的环境 ID。如果未指定，则使用草稿环境。
inputVariableMapping

map (key: string, value: string)

可选。应用变量名称与要作为输入发送给 Dialogflow 代理的 Dialogflow 会话参数名称之间的映射。

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

map (key: string, value: string)

可选。Dialogflow 会话参数名称与应用变量名称的映射，用于在 Dialogflow 代理执行结束后发送回 CES 代理。

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

boolean

可选。指示是否遵循在 Dialogflow 代理中配置的消息级中断设置。

  • 如果为 false：Dialogflow 代理的所有响应消息都遵循应用级抢占设置。
  • 如果为 true：只有将 allow_playback_interruption 设置为 true 的响应消息可以被中断，所有其他消息都遵循应用级抢占设置。

InputVariableMappingEntry

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

string
value

string

OutputVariableMappingEntry

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

string
value

string

ModelSettings

JSON 表示法 
{
  "model": string,

  // Union field _temperature can be only one of the following:
  "temperature": number
  // End of list of possible types for union field _temperature.
}
字段
model

string

可选。智能体应使用的 LLM 模型。如果未设置，代理将沿用其父代理的模型。

联合字段 _temperature。

_temperature 只能是下列其中一项：
temperature

number

可选。如果设置，系统将使用此温度值来运行 LLM 模型。温度可控制模型回答的随机性。温度越低，生成的回答就越可预测。温度越高，生成的回答就越有创意。

回调

JSON 表示法 
{
  "description": string,
  "disabled": boolean,
  "proactiveExecutionEnabled": boolean,

  // Union field callback can be only one of the following:
  "pythonCode": string
  // End of list of possible types for union field callback.
}
字段
description

string

可选。回调的人类可读说明。
disabled

boolean

可选。回调是否已停用。代理会忽略已停用的回调。
proactiveExecutionEnabled

boolean

可选。如果启用，回调也会在中间模型输出上执行。此设置仅在模型回调后生效。请谨慎启用。通常，after_model_callback 仅需在收到所有模型回答后执行。启用主动执行可能会对执行费用和延迟时间产生负面影响，因此仅应在极少数情况下启用。
联合字段 callback。要执行的回调。callback 只能是下列其中一项：
pythonCode

string

必需。要为回调执行的 Python 代码。

时间戳

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 之间（含边界值）。

AgentToolset

JSON 表示法 
{
  "toolset": string,
  "toolIds": [
    string
  ]
}
字段
toolset

string

必需。工具集的资源名称。格式：projects/{project}/locations/{location}/apps/{app}/toolsets/{toolset}
toolIds[]

string

可选。用于过滤工具集的工具 ID。

TransferRule

JSON 表示法 
{
  "childAgent": string,
  "direction": enum (Direction),

  // Union field rule_type can be only one of the following:
  "deterministicTransfer": {
    object (DeterministicTransfer)
  },
  "disablePlannerTransfer": {
    object (DisablePlannerTransfer)
  }
  // End of list of possible types for union field rule_type.
}
字段
childAgent

string

必需。规则所适用的子代理的资源名称。格式：projects/{project}/locations/{location}/apps/{app}/agents/{agent}
direction

enum (Direction)

必需。转移方向。
联合字段 rule_type。规则类型。rule_type 只能是下列其中一项：
deterministicTransfer

object (DeterministicTransfer)

可选。当条件满足时立即转接给目标客服人员的规则。
disablePlannerTransfer

object (DisablePlannerTransfer)

可选。阻止规划器转移到目标代理的规则。

DeterministicTransfer

JSON 表示法 
{

  // Union field condition_type can be only one of the following:
  "expressionCondition": {
    object (ExpressionCondition)
  },
  "pythonCodeCondition": {
    object (PythonCodeCondition)
  }
  // End of list of possible types for union field condition_type.
}
字段
联合字段 condition_type。要评估的条件。condition_type 只能是下列其中一项：
expressionCondition

object (ExpressionCondition)

可选。评估会话状态条件的规则。如果条件计算结果为 true，则会发生转移。
pythonCodeCondition

object (PythonCodeCondition)

可选。使用 Python 代码块评估条件的规则。如果条件计算结果为 true，则会发生转移。

ExpressionCondition

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

string

必需。cloud.api.Expression 条件的字符串表示形式。

PythonCodeCondition

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

string

必需。要执行的 Python 代码。

DisablePlannerTransfer

JSON 表示法 
{
  "expressionCondition": {
    object (ExpressionCondition)
  }
}
字段
expressionCondition

object (ExpressionCondition)

必需。如果条件评估结果为 true，则规划者将无法转移到目标代理。

输出架构

智能体充当基本构建块，为大语言模型 (LLM) 提供执行特定任务的指令。

代理

JSON 表示法 
{
  "name": string,
  "displayName": string,
  "description": string,
  "modelSettings": {
    object (ModelSettings)
  },
  "instruction": string,
  "tools": [
    string
  ],
  "childAgents": [
    string
  ],
  "beforeAgentCallbacks": [
    {
      object (Callback)
    }
  ],
  "afterAgentCallbacks": [
    {
      object (Callback)
    }
  ],
  "beforeModelCallbacks": [
    {
      object (Callback)
    }
  ],
  "afterModelCallbacks": [
    {
      object (Callback)
    }
  ],
  "beforeToolCallbacks": [
    {
      object (Callback)
    }
  ],
  "afterToolCallbacks": [
    {
      object (Callback)
    }
  ],
  "createTime": string,
  "updateTime": string,
  "guardrails": [
    string
  ],
  "etag": string,
  "toolsets": [
    {
      object (AgentToolset)
    }
  ],
  "generatedSummary": string,
  "transferRules": [
    {
      object (TransferRule)
    }
  ],

  // Union field agent_type can be only one of the following:
  "llmAgent": {
    object (LlmAgent)
  },
  "remoteDialogflowAgent": {
    object (RemoteDialogflowAgent)
  }
  // End of list of possible types for union field agent_type.
}
字段
name

string

标识符。代理的唯一标识符。格式：projects/{project}/locations/{location}/apps/{app}/agents/{agent}
displayName

string

必需。代理的显示名称。
description

string

可选。代理的人类可读说明。
modelSettings

object (ModelSettings)

可选。LLM 模型的配置。
instruction

string

可选。用于指导代理行为的 LLM 模型指令。
tools[]

string

可选。代理可用的工具列表。格式：projects/{project}/locations/{location}/apps/{app}/tools/{tool}
childAgents[]

string

可选。代理树中的子代理列表。格式：projects/{project}/locations/{location}/apps/{app}/agents/{agent}
beforeAgentCallbacks[]

object (Callback)

可选。在调用代理之前要执行的回调。所提供的回调会按列表中的顺序依次执行。如果回调返回了替换的响应，则执行会停止，并跳过所有剩余的回调。
afterAgentCallbacks[]

object (Callback)

可选。在调用代理后要执行的回调。所提供的回调会按列表中的顺序依次执行。如果回调返回了替换的响应，则执行会停止，并跳过所有剩余的回调。
beforeModelCallbacks[]

object (Callback)

可选。在调用模型之前要执行的回调。如果多次调用模型，则回调将执行多次。所提供的回调会按列表中的顺序依次执行。如果回调返回了替换的响应，则执行会停止，并跳过所有剩余的回调。
afterModelCallbacks[]

object (Callback)

可选。在调用模型后要执行的回调。如果多次调用模型，则回调将执行多次。所提供的回调会按列表中的顺序依次执行。如果回调返回了替换的响应，则执行会停止，并跳过所有剩余的回调。
beforeToolCallbacks[]

object (Callback)

可选。在调用工具之前要执行的回调。如果存在多次工具调用，则回调将执行多次。所提供的回调会按列表中的顺序依次执行。如果回调返回了替换的响应，则执行会停止，并跳过所有剩余的回调。
afterToolCallbacks[]

object (Callback)

可选。在调用工具后要执行的回调。如果存在多次工具调用，则回调将执行多次。所提供的回调会按列表中的顺序依次执行。如果回调返回了替换的响应，则执行会停止，并跳过所有剩余的回调。
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"。
updateTime

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"。
guardrails[]

string

可选。代理的护栏列表。格式：projects/{project}/locations/{location}/apps/{app}/guardrails/{guardrail}
etag

string

用于确保对象在读取-修改-写入操作期间未发生更改的 ETag。如果 etag 为空，则更新会覆盖任何并发更改。
toolsets[]

object (AgentToolset)

可选。代理的工具集列表。
generatedSummary

string

仅限输出。如果代理由 LLM 助理生成，此字段会包含生成内容的描述性摘要。
transferRules[]

object (TransferRule)

可选。客服人员转移规则。如果多个规则匹配，系统将使用列表中的第一个规则。
联合字段 agent_type。代理的类型。agent_type 只能是下列其中一项：
llmAgent

object (LlmAgent)

可选。默认代理类型。
remoteDialogflowAgent

object (RemoteDialogflowAgent)

可选。用于执行代理的远程 Dialogflow 代理。如果设置了此字段，系统将忽略所有其他代理级属性。

注意：如果 Dialogflow 代理与应用位于不同的项目中，您应向 CES 服务代理 service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com 授予 roles/dialogflow.client 权限。

RemoteDialogflowAgent

JSON 表示法 
{
  "agent": string,
  "flowId": string,
  "environmentId": string,
  "inputVariableMapping": {
    string: string,
    ...
  },
  "outputVariableMapping": {
    string: string,
    ...
  },
  "respectResponseInterruptionSettings": boolean
}
字段
agent

string

必需。Dialogflow 代理资源名称。格式：projects/{project}/locations/{location}/agents/{agent}
flowId

string

可选。Dialogflow 代理中相应流的流 ID。
environmentId

string

可选。要用于代理执行的 Dialogflow 代理的环境 ID。如果未指定，则使用草稿环境。
inputVariableMapping

map (key: string, value: string)

可选。应用变量名称与要作为输入发送给 Dialogflow 代理的 Dialogflow 会话参数名称之间的映射。

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

map (key: string, value: string)

可选。Dialogflow 会话参数名称与应用变量名称的映射，用于在 Dialogflow 代理执行结束后发送回 CES 代理。

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

boolean

可选。指示是否遵循在 Dialogflow 代理中配置的消息级中断设置。

  • 如果为 false：Dialogflow 代理的所有响应消息都遵循应用级抢占设置。
  • 如果为 true：只有将 allow_playback_interruption 设置为 true 的响应消息可以被中断，所有其他消息都遵循应用级抢占设置。

InputVariableMappingEntry

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

string
value

string

OutputVariableMappingEntry

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

string
value

string

ModelSettings

JSON 表示法 
{
  "model": string,

  // Union field _temperature can be only one of the following:
  "temperature": number
  // End of list of possible types for union field _temperature.
}
字段
model

string

可选。智能体应使用的 LLM 模型。如果未设置，代理将沿用其父代理的模型。

联合字段 _temperature。

_temperature 只能是下列其中一项：
temperature

number

可选。如果设置，系统将使用此温度值来运行 LLM 模型。温度可控制模型回答的随机性。温度越低，生成的回答就越可预测。温度越高，生成的回答就越有创意。

回调

JSON 表示法 
{
  "description": string,
  "disabled": boolean,
  "proactiveExecutionEnabled": boolean,

  // Union field callback can be only one of the following:
  "pythonCode": string
  // End of list of possible types for union field callback.
}
字段
description

string

可选。回调的人类可读说明。
disabled

boolean

可选。回调是否已停用。代理会忽略已停用的回调。
proactiveExecutionEnabled

boolean

可选。如果启用，回调也会在中间模型输出上执行。此设置仅在模型回调后生效。请谨慎启用。通常，after_model_callback 仅需在收到所有模型回答后执行。启用主动执行可能会对执行费用和延迟时间产生负面影响，因此仅应在极少数情况下启用。
联合字段 callback。要执行的回调。callback 只能是下列其中一项：
pythonCode

string

必需。要为回调执行的 Python 代码。

时间戳

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 之间（含边界值）。

AgentToolset

JSON 表示法 
{
  "toolset": string,
  "toolIds": [
    string
  ]
}
字段
toolset

string

必需。工具集的资源名称。格式：projects/{project}/locations/{location}/apps/{app}/toolsets/{toolset}
toolIds[]

string

可选。用于过滤工具集的工具 ID。

TransferRule

JSON 表示法 
{
  "childAgent": string,
  "direction": enum (Direction),

  // Union field rule_type can be only one of the following:
  "deterministicTransfer": {
    object (DeterministicTransfer)
  },
  "disablePlannerTransfer": {
    object (DisablePlannerTransfer)
  }
  // End of list of possible types for union field rule_type.
}
字段
childAgent

string

必需。规则所适用的子代理的资源名称。格式：projects/{project}/locations/{location}/apps/{app}/agents/{agent}
direction

enum (Direction)

必需。转移方向。
联合字段 rule_type。规则类型。rule_type 只能是下列其中一项：
deterministicTransfer

object (DeterministicTransfer)

可选。当条件满足时立即转接给目标客服人员的规则。
disablePlannerTransfer

object (DisablePlannerTransfer)

可选。阻止规划器转移到目标代理的规则。

DeterministicTransfer

JSON 表示法 
{

  // Union field condition_type can be only one of the following:
  "expressionCondition": {
    object (ExpressionCondition)
  },
  "pythonCodeCondition": {
    object (PythonCodeCondition)
  }
  // End of list of possible types for union field condition_type.
}
字段
联合字段 condition_type。要评估的条件。condition_type 只能是下列其中一项：
expressionCondition

object (ExpressionCondition)

可选。评估会话状态条件的规则。如果条件计算结果为 true，则会发生转移。
pythonCodeCondition

object (PythonCodeCondition)

可选。使用 Python 代码块评估条件的规则。如果条件计算结果为 true，则会发生转移。

ExpressionCondition

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

string

必需。cloud.api.Expression 条件的字符串表示形式。

PythonCodeCondition

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

string

必需。要执行的 Python 代码。

DisablePlannerTransfer

JSON 表示法 
{
  "expressionCondition": {
    object (ExpressionCondition)
  }
}
字段
expressionCondition

object (ExpressionCondition)

必需。如果条件评估结果为 true，则规划者将无法转移到目标代理。

工具注释

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