Method: projects.locations.apps.executeTool

Executes the given tool with the given arguments.

HTTP request

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

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
parent

string

Required. The resource name of the app which the tool/toolset belongs to. Format: projects/{project}/locations/{location}/apps/{app}

Request body

The request body contains data with the following structure:

JSON representation 
{
  "args": {
    object
  },
  "mockConfig": {
    object (MockConfig)
  },

  // 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.

  // Union field tool_execution_context can be only one of the following:
  "variables": {
    object
  },
  "context": {
    object
  }
  // End of list of possible types for union field tool_execution_context.
}
Fields
args

object (Struct format)

Optional. The input parameters and values for the tool in JSON object format.
mockConfig

object (MockConfig)

Optional. Mock configuration for the tool execution. If this field is set, tools that call other tools will be mocked based on the provided patterns and responses.
Union field tool_identifier. The identifier of the tool to execute. It could be either a persisted tool or a tool from a toolset. tool_identifier can be only one of the following:
tool

string

Optional. The name of the tool to execute. Format: projects/{project}/locations/{location}/apps/{app}/tools/{tool}
toolsetTool

object (ToolsetTool)

Optional. The toolset tool to execute. Only one tool should match the predicate from the toolset. Otherwise, an error will be returned.
Union field tool_execution_context. Additional context to be provided for the tool execution tool_execution_context can be only one of the following:
variables

object (Struct format)

Optional. The variables that are available for the tool execution.
context

object (Struct format)

Optional. The [ToolCallContext](https://docs.cloud.google.com/customer-engagement-ai/conversational-agents/ps/tool/python#environment for details) to be passed to the Python tool.

Response body

Response message for ToolService.ExecuteTool.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "response": {
    object
  },
  "variables": {
    object
  },

  // 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.
}
Fields
response

object (Struct format)

The tool execution result in JSON object format. Use "output" key to specify tool response and "error" key to specify error details (if any). If "output" and "error" keys are not specified, then whole "response" is treated as tool execution result.
variables

object (Struct format)

The variable values at the end of the tool execution.
Union field tool_identifier. The identifier of the tool that got executed. tool_identifier can be only one of the following:
tool

string

The name of the tool that got executed. Format: projects/{project}/locations/{location}/apps/{app}/tools/{tool}
toolsetTool

object (ToolsetTool)

The toolset tool that got executed.

Authorization scopes

Requires one of the following OAuth scopes:

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

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the parent resource:

  • ces.tools.execute

For more information, see the IAM documentation.

MockConfig

Mock tool calls configuration for the session.

JSON representation 
{
  "mockedToolCalls": [
    {
      object (MockedToolCall)
    }
  ],
  "unmatchedToolCallBehavior": enum (MockConfig.UnmatchedToolCallBehavior)
}
Fields
mockedToolCalls[]

object (MockedToolCall)

Optional. All tool calls to mock for the duration of the session.
unmatchedToolCallBehavior

enum (MockConfig.UnmatchedToolCallBehavior)

Required. Beavhior for tool calls that don't match any args patterns in mockedToolCalls.

MockedToolCall

A mocked tool call.

Expresses the target tool + a pattern to match against that tool's args / inputs. If the pattern matches, then the mock response will be returned.

JSON representation 
{
  "tool": string,
  "expectedArgsPattern": {
    object
  },
  "mockResponse": {
    object
  },

  // Union field tool_identifier can be only one of the following:
  "toolId": string,
  "toolset": {
    object (ToolsetTool)
  }
  // End of list of possible types for union field tool_identifier.
}
Fields
tool
(deprecated)

string

Required. Deprecated. Use tool_identifier instead.
expectedArgsPattern

object (Struct format)

Required. A pattern to match against the args / inputs of all dispatched tool calls. If the tool call inputs match this pattern, then mock output will be returned.
mockResponse

object (Struct format)

Optional. The mock response / output to return if the tool call args / inputs match the pattern.
Union field tool_identifier. The identifier of the tool to mock. tool_identifier can be only one of the following:
toolId

string

Optional. The name of the tool to mock. Format: projects/{project}/locations/{location}/apps/{app}/tools/{tool}
toolset

object (ToolsetTool)

Optional. The toolset to mock.

MockConfig.UnmatchedToolCallBehavior

What to do when a tool call doesn't match any mocked tool calls.

Enums
UNMATCHED_TOOL_CALL_BEHAVIOR_UNSPECIFIED Default value. This value is unused.
FAIL Throw an error for any tool calls that don't match a mock expected input pattern.
PASS_THROUGH For unmatched tool calls, pass the tool call through to real tool.