Method: projects.locations.apps.executeTool

使用给定的实参执行给定的工具。

HTTP 请求

POST https://ces.googleapis.com/v1/{parent=projects/*/locations/*/apps/*}:executeTool

网址采用 gRPC 转码语法。

路径参数

参数
parent

string

必需。工具/工具集所属应用的资源名称。格式：projects/{project}/locations/{location}/apps/{app}

请求正文

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

JSON 表示法 
{
  "args": {
    object
  },
  "mockConfig": {
    object (MockConfig)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "tool": string,
  "toolsetTool": {
    object (ToolsetTool)
  }
  // End of mutually exclusive fields.

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "variables": {
    object
  },
  "context": {
    object
  }
  // End of mutually exclusive fields.
}
字段
args

object (Struct format)

可选。以 JSON 对象格式表示的工具输入参数和值。
mockConfig

object (MockConfig)

可选。工具执行的模拟配置。如果设置了此字段，则调用其他工具的工具将根据提供的模式和响应进行模拟。
要执行的工具的标识符。它可以是持久化工具，也可以是工具集中的工具。以下是互斥字段的列表。在响应中，最多只能设置以下字段之一：
tool

string

可选。要执行的工具的名称。格式：projects/{project}/locations/{location}/apps/{app}/tools/{tool}
toolsetTool

object (ToolsetTool)

可选。要执行的工具集工具。工具集中只能有一个工具与谓词匹配。否则，系统将返回错误。
互斥字段的结束。
为工具执行提供的其他上下文。以下是互斥字段的列表。在响应中，最多只能设置以下字段之一：
variables

object (Struct format)

可选。可用于工具执行的变量。
context

object (Struct format)

可选。要传递给 Python 工具的 [ToolCallContext]（如需了解详情，请参阅 https://docs.cloud.google.com/customer-engagement-ai/conversational-agents/ps/tool/python#environment）。
互斥字段的结束。

响应正文

ToolService.ExecuteTool 的响应消息。

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

JSON 表示法 
{
  "response": {
    object
  },
  "variables": {
    object
  },
  "citations": {
    object (Citations)
  },
  "googleSearchSuggestions": {
    object (GoogleSearchSuggestions)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "tool": string,
  "toolsetTool": {
    object (ToolsetTool)
  }
  // End of mutually exclusive fields.
}
字段
response

object (Struct format)

以 JSON 对象格式表示的工具执行结果。使用“output”键指定工具响应，使用“error”键指定错误详情（如有）。如果未指定“output”和“error”键，则整个“response”将被视为工具执行结果。
variables

object (Struct format)

工具执行结束时的变量值。
citations

object (Citations)

提供工具执行来源信息的引用。
googleSearchSuggestions

object (GoogleSearchSuggestions)

在工具执行期间调用 Google 搜索工具后，Google 搜索返回的建议。
已执行的工具的标识符。以下是互斥字段的列表。在响应中，最多只能设置以下字段之一：
tool

string

已执行的工具的名称。格式：projects/{project}/locations/{location}/apps/{app}/tools/{tool}
toolsetTool

object (ToolsetTool)

已执行的工具集工具。
互斥字段的结束。

授权范围

需要以下 OAuth 范围之一：

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

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

IAM 权限

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

  • ces.tools.execute

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

MockConfig

会话的模拟工具调用配置。

JSON 表示法 
{
  "mockedToolCalls": [
    {
      object (MockedToolCall)
    }
  ],
  "unmatchedToolCallBehavior": enum (MockConfig.UnmatchedToolCallBehavior)
}
字段
mockedToolCalls[]

object (MockedToolCall)

可选。在整个会话期间要模拟的所有工具调用。
unmatchedToolCallBehavior

enum (MockConfig.UnmatchedToolCallBehavior)

必需。对于与 mockedToolCalls 中的任何实参模式都不匹配的工具调用的行为。

MockedToolCall

模拟工具调用。

表示目标工具以及要与该工具的实参 / 输入进行匹配的模式。如果模式匹配，则返回模拟响应。

JSON 表示法 
{
  "tool": string,
  "expectedArgsPattern": {
    object
  },
  "mockResponse": {
    object
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "toolId": string,
  "toolset": {
    object (ToolsetTool)
  }
  // End of mutually exclusive fields.
}
字段
tool
(deprecated)

string

可选。已弃用。请改用 tool_identifier。
expectedArgsPattern

object (Struct format)

必需。用于匹配所有已调度工具调用的实参 / 输入的模式。如果工具调用输入与此模式匹配，则返回模拟输出。
mockResponse

object (Struct format)

可选。如果工具调用实参 / 输入与模式匹配，则返回模拟响应 / 输出。
要模拟的工具的标识符。以下是互斥字段的列表。在响应中，最多只能设置以下字段之一：
toolId

string

可选。要模拟的工具的名称。格式：projects/{project}/locations/{location}/apps/{app}/tools/{tool}
toolset

object (ToolsetTool)

可选。要模拟的工具集。
互斥字段的结束。

MockConfig.UnmatchedToolCallBehavior

当工具调用与任何模拟工具调用都不匹配时，该怎么办。

枚举
UNMATCHED_TOOL_CALL_BEHAVIOR_UNSPECIFIED 默认值。此值未使用。
FAIL 针对任何与模拟预期输入模式不匹配的工具调用抛出错误。
PASS_THROUGH 对于不匹配的工具调用，将工具调用传递给实际工具。