Get action confirmation for ADK Tools

获取 ADK 工具的操作确认

Supported in ADKPython v1.14.0Experimental

Some agent workflows require confirmation for decision making, verification, security, or general oversight. In these cases, you want to get a response from a human or supervising system before proceeding with a workflow. The Tool Confirmation feature in the Agent Development Kit (ADK) allows an ADK Tool to pause its execution and interact with a user or other system for confirmation or to gather structured data before proceeding. You can use Tool Confirmation with an ADK Tool in the following ways:

某些智能体工作流需要确认以进行决策、验证、安全性或一般监督。在这些情况下,您希望在继续工作流之前从人员或监督系统获得响应。智能体开发工具包 (ADK) 中的 工具确认 功能允许 ADK 工具暂停其执行,并与用户或其他系统进行交互以进行确认或在继续之前收集结构化数据。您可以通过以下方式将工具确认与 ADK 工具一起使用:

• Boolean Confirmation: You can configure a FunctionTool with a require_confirmation parameter. This option pauses the tool for a yes or no confirmation response.

  布尔确认: 您可以使用 require_confirmation 参数配置 FunctionTool。此选项暂停工具以等待是或否的确认响应。

• Advanced Confirmation: For scenarios requiring structured data responses, you can configure a FunctionTool with a text prompt to explain the confirmation and an expected response.

  高级确认: 对于需要结构化数据响应的场景,您可以使用文本提示配置 FunctionTool 以解释确认和预期的响应。

Experimental

示例:实验性

The Tool Confirmation feature is experimental and has some known limitations. We welcome your feedback!

工具确认功能是实验性的,具有一些 已知限制。 我们欢迎您的 反馈!

You can configure how a request is communicated to a user, and the system can also use remote responses sent via the ADK server's REST API. When using the confirmation feature with the ADK web user interface, the agent workflow displays a dialog box to the user to request input, as shown in Figure 1:

您可以配置如何将请求传达给用户,系统还可以使用通过 ADK 服务器的 REST API 发送的远程响应。当将确认功能与 ADK Web 用户界面一起使用时,智能体工作流向用户显示一个对话框以请求输入,如图 1 所示:

Figure 1. Example confirmation response request dialog box using an advanced, tool response implementation.

图 1. 使用高级工具响应实现的确认响应请求对话框示例。

The following sections describe how to use this feature for the confirmation scenarios. For a complete code sample, see the human_tool_confirmation example. There are additional ways to incorporate human input into your agent workflow, for more details, see the Human-in-the-loop agent pattern.

以下部分描述了如何将此功能用于确认场景。有关完整的代码示例,请参阅 human_tool_confirmation 示例。还有其他方法可以将人工输入合并到您的智能体工作流中,有关更多详细信息,请参阅 Human-in-the-loop 智能体模式。

Boolean confirmation

布尔确认

When your tool only requires a simple yes or no from the user, you can append a confirmation step using the FunctionTool class as a wrapper. For example, if you have a tool called reimburse, you can enable a confirmation step by wrapping it with the FunctionTool class and setting the require_confirmation parameter to True, as shown in the following example:

当您的工具只需要用户简单的 yes 或 no 时,您可以使用 FunctionTool 类作为包装器附加确认步骤。例如,如果您有一个名为 reimburse 的工具,可以通过使用 FunctionTool 类包装它并将 require_confirmation 参数设置为 True 来启用确认步骤,如以下示例所示:

# From agent.py
# 来自 agent.py
root_agent = Agent(
   ...
   tools=[
        # Set require_confirmation to True to require user confirmation
        # for the tool call.
        # 将 require_confirmation 设置为 True 以要求用户确认工具调用。
        FunctionTool(reimburse, require_confirmation=True),
    ],
...

This implementation method requires minimal code, but is limited to simple approvals from the user or confirming system. For a complete example of this approach, see the human_tool_confirmation code sample.

此实现方法需要最少的代码,但仅限于用户或确认系统的简单批准。有关此方法的完整示例,请参阅 human_tool_confirmation 代码示例。

Require confirmation function

确认函数

You can modify the behavior require_confirmation response by replacing its input value with a function that returns a boolean response. The following example shows a function for determining if a confirmation is required:

您可以通过将 require_confirmation 响应的输入值替换为返回布尔响应的函数来修改其行为。以下示例显示了一个用于确定是否需要确认的函数:

async def confirmation_threshold(
    amount: int, tool_context: ToolContext
) -> bool:
  """Returns true if the amount is greater than 1000."""
  """如果金额大于 1000,则返回 true。"""
  return amount > 1000

然后可以将此函数设置为 require_confirmation 参数的参数值:

root_agent = Agent(
   ...
   tools=[
        # Set require_confirmation to True to require user confirmation
        # 将 require_confirmation 设置为 True 以要求用户确认
        FunctionTool(reimburse, require_confirmation=confirmation_threshold),
    ],
...

For a complete example of this implementation, see the human_tool_confirmation code sample.

有关此实现的完整示例,请参阅 human_tool_confirmation 代码示例。

Advanced confirmation

高级确认

When a tool confirmation requires more details for the user or a more complex response, use a tool_confirmation implementation. This approach extends the ToolContext object to add a text description of the request for the user and allows for more complex response data. When implementing tool confirmation this way, you can pause a tool's execution, request specific information, and then resume the tool with the provided data.

当工具确认需要为用户提供更多详细信息或更复杂的响应时,请使用 tool_confirmation 实现。此方法扩展 ToolContext 对象以为用户添加请求的文本描述,并允许更复杂的响应数据。当以这种方式实现工具确认时,您可以暂停工具的执行,请求特定信息,然后使用提供的数据恢复工具。

This confirmation flow has a request stage where the system assembles and sends an input request human response, and a response stage where the system receives and processes the returned data.

此确认流程具有请求阶段,在此阶段系统组合并发送输入请求人工响应,以及响应阶段,在此阶段系统接收和处理返回的数据。

Confirmation definition

确认定义

When creating a Tool with an advanced confirmation, create a function that includes a ToolContext object. Then define the confirmation using a tool_confirmation object, the tool_context.request_confirmation() method with hint and payload parameters. These properties are used as follows:

在创建具有高级确认的工具时,创建一个包含 ToolContext 对象的函数。然后使用 tool_confirmation 对象、tool_context.request_confirmation() 方法和 hint 及 payload 参数定义确认。这些属性的使用方式如下:

• hint: Descriptive message that explains what is needed from the user.

  hint: 解释用户需要什么的描述性消息。

• payload: The structure of the data you expect in return. This data type is Any and must be serializable into a JSON-formatted string, such as a dictionary or pydantic model.

  payload: 您期望返回的数据结构。此数据类型为 Any,必须可序列化为 JSON 格式的字符串,例如字典或 pydantic 模型。

The following code shows an example implementation for a tool that processes time off requests for an employee:

以下代码显示了处理员工请假请求的工具的示例实现:

def request_time_off(days: int, tool_context: ToolContext):
  """Request day off for the employee."""
  """为员工请求请假。"""
  ...
  tool_confirmation = tool_context.tool_confirmation
  if not tool_confirmation:
    tool_context.request_confirmation(
        hint=(
            'Please approve or reject the tool call request_time_off() by'
            ' responding with a FunctionResponse with an expected'
            ' ToolConfirmation payload.'
        ),
        payload={
            'approved_days': 0,
        },
    )
    # Return intermediate status indicating that the tool is waiting for
    # a confirmation response:
    # 返回中间状态,指示工具正在等待确认响应:
    return {'status': 'Manager approval is required.'}

  approved_days = tool_confirmation.payload['approved_days']
  approved_days = min(approved_days, days)
  if approved_days == 0:
    return {'status': 'The time off request is rejected.', 'approved_days': 0}
  return {
      'status': 'ok',
      'approved_days': approved_days,
  }

For a complete example of this approach, see the human_tool_confirmation code sample. Keep in mind that the agent workflow tool execution pauses while a confirmation is obtained. After confirmation is received, you can access the confirmation response in the tool_confirmation.payload object and then proceed with the execution of the workflow.

有关此方法的完整示例,请参阅 human_tool_confirmation 代码示例。请记住,在获取确认时,智能体工作流工具执行会暂停。收到确认后,您可以在 tool_confirmation.payload 对象中访问确认响应,然后继续执行工作流。

Remote confirmation with REST API

使用 REST API 进行远程确认

If there is no active user interface for a human confirmation of an agent workflow, you can handle the confirmation through a command-line interface or by routing it through another channel like email or a chat application. To confirm the tool call, the user or calling application needs to send a FunctionResponse event with the tool confirmation data.

如果没有用于智能体工作流人工确认的活动用户界面,您可以通过命令行界面或通过电子邮件或聊天应用程序等其他渠道路由确认来处理确认。要确认工具调用,用户或调用应用程序需要发送包含工具确认数据的 FunctionResponse 事件。

You can send the request to the ADK API server's /run or /run_sse endpoint, or directly to the ADK runner. The following example uses a curl command to send the confirmation to the /run_sse endpoint:

您可以将请求发送到 ADK API 服务器的 /run 或 /run_sse 端点,或直接发送到 ADK 运行器。以下示例使用 curl 命令将确认发送到 /run_sse 端点:

 curl -X POST http://localhost:8000/run_sse \
 -H "Content-Type: application/json" \
 -d '{
    "app_name": "human_tool_confirmation",
    "user_id": "user",
    "session_id": "7828f575-2402-489f-8079-74ea95b6a300",
    "new_message": {
        "parts": [
            {
                "function_response": {
                    "id": "adk-13b84a8c-c95c-4d66-b006-d72b30447e35",
                    "name": "adk_request_confirmation",
                    "response": {
                        "confirmed": true
                    }
                }
            }
        ],
        "role": "user"
    }
}'

A REST-based response for a confirmation must meet the following requirements:

基于 REST 的确认响应必须满足以下要求:

• The id in the function_response should match the function_call_id from the RequestConfirmation FunctionCall event.

  function_response 中的 id 应与 RequestConfirmation FunctionCall 事件中的 function_call_id 匹配。

• The name should be adk_request_confirmation.

  name 应为 adk_request_confirmation。

• The response object contains the confirmation status and any additional payload data required by the tool.

  response 对象包含确认状态和工具所需的任何其他有效负载数据。

Note: Confirmation with Resume feature

注意:使用 Resume 功能的确认

If your ADK agent workflow is configured with the Resume feature, you also must include the Invocation ID (invocation_id) parameter with the confirmation response. The Invocation ID you provide must be the same invocation that generated the confirmation request, otherwise the system starts a new invocation with the confirmation response. If your agent uses the Resume feature, consider including the Invocation ID as a parameter with your confirmation request, so it can be included with the response. For more details on using the Resume feature, see Resume stopped agents.

如果您的 ADK 智能体工作流配置了 Resume 功能,您还必须在确认响应中包含 调用 ID (invocation_id) 参数。您提供的调用 ID 必须与生成 确认请求的调用相同,否则系统 将使用确认响应启动新调用。如果您的 智能体使用 Resume 功能,请考虑将调用 ID 作为参数包含在您的确认请求中,以便它可以包含 在响应中。有关使用 Resume 功能的更多详细信息,请参阅 Resume stopped agents。

Known limitations

已知限制

The tool confirmation feature has the following limitations:

工具确认功能具有以下限制:

• DatabaseSessionService is not supported by this feature.

  此功能不支持 DatabaseSessionService。

• VertexAiSessionService is not supported by this feature.

  此功能不支持 VertexAiSessionService。

Next steps

下一步

For more information on building ADK tools for agent workflows, see Function tools.

有关为智能体工作流构建 ADK 工具的更多信息,请参阅函数工具。