获取 ADK 工具的操作确认¶

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

布尔确认： 你可以使用 require_confirmation 参数配置 FunctionTool。此选项会暂停工具以等待是或否的确认响应。
高级确认： 对于需要结构化数据响应的场景，你可以使用文本提示配置 FunctionTool 来解释确认和期望的响应。

实验性

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

你可以配置如何向用户传达请求，系统也可以使用通过 ADK 服务器的 REST API 发送的远程响应。当在 ADK Web 用户界面中使用确认功能时，智能体工作流会向用户显示一个对话框来请求输入，如图 1 所示：

工具确认的默认用户界面截图

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

以下部分描述了如何在确认场景中使用此功能。有关完整的代码示例，请参阅 human_tool_confirmation 示例。还有其他方法可以将人类输入纳入你的智能体工作流，更多详细信息，请参阅人在回路智能体模式。

布尔确认¶

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

# From agent.py
root_agent = Agent(
   ...
   tools=[
        # Set require_confirmation to True to require user confirmation
        # for the tool call.
        FunctionTool(reimburse, require_confirmation=True),
    ],
...

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

需要确认函数¶

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

async def confirmation_threshold(
    amount: int, tool_context: ToolContext
) -> bool:
  """Returns true if the amount is greater than 1000."""
  return amount > 1000

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

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

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

高级确认¶

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

此确认流程有一个请求阶段，系统在此阶段组装并发送输入请求人类响应，以及一个响应阶段，系统在此阶段接收和处理返回的数据。

确认定义¶

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

hint：解释用户需要什么的描述性消息。
payload：你期望返回的数据结构。此数据类型为 Any，必须可序列化为 JSON 格式的字符串，如字典或 pydantic 模型。

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

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,
  }

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

使用 REST API 进行远程确认¶

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

你可以将请求发送到 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"
    }
}'

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

function_response 中的 id 应与 RequestConfirmation FunctionCall 事件中的 function_call_id 匹配。
name 应为 adk_request_confirmation。
response 对象包含确认状态和工具所需的任何额外负载数据。

已知限制¶

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

此功能不支持 DatabaseSessionService。
此功能不支持 VertexAiSessionService。

下一步¶

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