anthropic-academy：工具使用（一）

工具使用介绍

没有工具的问题

当用户向 Claude 询问当前信息时，它会遇到障碍。例如，如果有人问"加利福尼亚州旧金山的天气怎么样？"Claude 只能回复类似"抱歉，我无法获取最新的天气信息。"这样的内容。

当用户需要实时数据时，这会造成令人沮丧的体验------如果 Claude 能够访问当前信息，理论上是可以提供帮助的。

工具使用的工作原理

工具使用遵循应用程序与 Claude 之间特定的往返模式。以下是完整的流程：

1. 初始请求： 您向 Claude 发送问题，并附上如何从外部来源获取额外数据的说明

工具请求： Claude 分析问题后判断需要更多信息，然后明确说明它需要哪些具体数据
数据检索： 您的服务器运行代码，从外部 API 或数据库获取所请求的信息
最终响应： 您将检索到的数据发送回 Claude，Claude 随后结合原始问题和最新数据生成完整的回复

天气示例实践

让我们看看这在天气问题中是如何运作的。这个过程会变得更加具体：

当用户询问当前天气时，你在提示词中包含了如何获取天气数据的说明。Claude 识别出它需要当前信息，并请求获取特定位置的天气数据。然后你的服务器调用天气 API 获取实时状况，并将该数据发送回 Claude。最后，Claude 将最新的天气数据与用户的问题结合起来，提供准确、及时的回复。

主要优势

实时信息： 访问 Claude 训练期间不可用的当前数据
外部系统集成： 将 Claude 连接到数据库、API 和其他服务
动态响应： 根据最新可用信息提供答案
结构化交互： Claude 清楚地知道自己需要什么信息以及如何询问

工具使用将 Claude 从静态知识库转变为能够处理实时数据的动态助手。这为构建需要当前信息的应用程序开辟了可能性，无论是天气数据、股票价格、数据库查询，还是用户可能需要的任何其他实时信息。

项目概述

我们将构建一个实用项目，教会 Claude 如何设置未来日期的提醒。这听起来可能很简单，但它揭示了几个有趣的挑战，我们将使用自定义工具来解决这些问题。

目标很直接：我们希望能够告诉 Claude"为我的医生预约设置一个提醒，时间是下周四"，然后 Claude 回复"好的，我会提醒你。"但要实现这一点，我们需要解决 Claude 在处理时间和提醒方面的一些局限性。

为何这具有挑战性

虽然 Claude 知道当前日期，但我们需要解决三个具体问题：

时间感知有限： Claude 可能知道当前日期，但不知道确切时间
日期计算问题： Claude 并不总能很好地处理基于时间的加法运算，尤其是在计算未来很多天的日期时
没有提醒功能： Claude 不知道如何设置提醒------它没有内置的提醒机制

这些限制中的每一个都代表着 Claude 的自然能力与我们提醒系统所需功能之间的差距。工具正是我们弥合这些差距的方式。

我们需要的工具

我们将创建三个独立的工具来处理每个挑战：

获取当前日期时间： Claude 需要精确知道当前的日期和时间
为日期时间添加时长： Claude 在日期时间加法运算上并不完美，因此我们将为其提供一个可靠的工具来完成此任务
设置提醒： 我们需要一种方法来在系统中实际设置提醒

我们将逐一实现这些工具，从最简单的开始。这种方法让我们在构建更复杂的功能之前，先理解工具调用的工作原理。最终，Claude 将能够处理诸如"一周后提醒我"这样的自然语言请求，通过组合这些工具来计算确切时间并设置提醒。

这个项目展示了与 AI 协作的一个关键原则：当模型存在局限性时，我们通过工具来扩展其能力，而不是试图在提示词中绕过这些局限性。

工具函数

在使用 Claude 构建 AI 应用时，你通常需要让它能够访问实时信息或执行操作。这就是工具函数的用武之地------它们是 Python 函数，Claude 可以在需要额外数据来帮助用户时调用这些函数。

上图展示了我们将要实现的三个基本工具：获取当前日期/时间、为日期添加时间间隔，以及设置提醒。让我们从第一个开始。

什么是工具函数？

工具函数是一个普通的 Python 函数，当 Claude 判断需要额外信息来帮助用户时，它会自动执行该函数。例如，如果有人问"现在几点了？"，Claude 就会调用你的日期/时间工具来获取当前时间。

以下是一个天气工具函数的示例。请注意它如何验证输入并提供清晰的错误消息------这些都是重要的最佳实践。

工具函数的最佳实践

编写工具函数时，请遵循以下准则：

使用描述性名称： 函数名和参数名都应清晰地表明其用途
验证输入： 检查必需参数是否为空或无效，如果是则抛出错误
提供有意义的错误信息： Claude 能够看到错误信息，并可能使用修正后的参数重新尝试函数调用

验证尤为重要，因为 Claude 会从错误中学习。如果你抛出一个明确的错误，如"Location cannot be empty"，Claude 可能会尝试使用正确的位置值再次调用该函数。

构建你的第一个工具函数

让我们创建一个获取当前日期和时间的函数。该函数将接受一个日期格式参数，以便 Claude 可以请求不同格式的时间：

perl 复制代码

def get_current_datetime(date_format="%Y-%m-%d %H:%M:%S"):
    if not date_format:
        raise ValueError("date_format cannot be empty")
    return datetime.now().strftime(date_format)

该函数使用 Python 的 datetime 模块获取当前时间，并根据提供的格式字符串进行格式化。默认格式输出为：年-月-日时:分:秒。

你可以用不同的格式来测试它：

perl 复制代码

# Default format: "2024-01-15 14:30:25"
get_current_datetime()

# Just hour and minute: "14:30"
get_current_datetime("%H:%M")

验证检查确保 Claude 不能为日期格式传递空字符串。虽然这种特定错误不太可能发生，但它展示了验证输入并提供有用错误消息的模式，Claude 可以从中学习。

下一步

创建函数只是第一步。接下来，你需要编写一个 JSON schema 来向 Claude 描述该函数，然后将其集成到你的聊天系统中。这种工具函数方法既能赋予 Claude 强大的能力，又能保持代码的组织性和可维护性。

工具模式

编写完工具函数后，下一步是创建一个 JSON schema，告诉 Claude 你的函数需要哪些参数以及如何使用它。这个 schema 相当于一份文档，Claude 通过阅读它来了解何时以及如何调用你的工具。

理解 JSON Schema

JSON Schema 并非专为 AI 或工具调用而设计------它是一种广泛使用的数据验证规范，已经存在多年。AI 社区之所以采用它，是因为它能够方便地描述函数参数并验证数据。

完整的工具规范包含三个主要部分：

name - 为工具起一个清晰、描述性的名称（如"get_weather"）
description - 工具的功能、使用场景以及返回内容
input_schema - 描述函数参数的实际 JSON schema

编写有效的描述

你的工具描述对于帮助 Claude 理解何时使用你的函数至关重要。最佳实践包括：

用 3-4 句话说明该工具的功能
描述 Claude 应在何时使用它
解释它会返回什么类型的数据
为每个参数提供详细描述

生成模式的简便方法

你可以使用 Claude 本身来生成 JSON schema，而无需从头编写。具体流程如下：

复制你的工具函数代码
前往 Claude，让它编写一个用于工具调用的 JSON schema
将 Anthropic 关于工具使用的文档作为上下文一并提供
让 Claude 按照最佳实践生成格式规范的 schema

提示词可以这样写："为这个函数编写一个有效的 JSON schema 规范，用于工具调用。请遵循附件文档中列出的最佳实践。"

在代码中实现 Schema

一旦 Claude 生成了你的 schema，将其复制到你的代码文件中。以下是一个推荐的命名模式：

perl 复制代码

def get_current_datetime(date_format="%Y-%m-%d %H:%M:%S"):
    if not date_format:
        raise ValueError("date_format cannot be empty")
    return datetime.now().strftime(date_format)

get_current_datetime_schema = {
    "name": "get_current_datetime",
    "description": "根据指定格式返回当前的日期和时间",
    "input_schema": {
        "type": "object",
        "properties": {
            "date_format": {
                "type": "string",
                "description": "指定返回日期时间格式的字符串。使用 Python 的 strftime 格式代码。",
                "default": "%Y-%m-%d %H:%M:%S"
            }
        },
        "required": []
    }
}

使用 function_name 后跟 function_name_schema 的模式来保持架构的组织性，便于与对应的函数进行匹配。

添加类型安全

为了更好地进行类型检查，请从 Anthropic 库中导入并使用 ToolParam 类型：

python 复制代码

from anthropic.types import ToolParam

get_current_datetime_schema = ToolParam({
    "name": "get_current_datetime",
    "description": "返回按照指定格式格式化的当前日期和时间",
    # ... rest of schema
})

虽然这对于功能实现并非严格必要，但当你将该模式与 Claude 的 API 配合使用时，它可以防止类型错误，并使你的代码更加健壮。

处理消息块

在使用 Claude 的工具功能时，你会遇到一种与之前简单文本响应不同的新响应结构。Claude 现在不再只返回单个文本块，而是可以返回包含文本和工具使用信息的多块消息。

进行启用工具的 API 调用

要让 Claude 能够使用工具，你需要在 API 调用中包含 tools 参数。以下是请求的结构方式：

ini 复制代码

messages = []
messages.append({
    "role": "user",
    "content": "当前的确切时间是什么，格式为 HH:MM:SS？"
})

response = client.messages.create(
    model=model,
    max_tokens=1000,
    messages=messages,
    tools=[get_current_datetime_schema],
)

tools 参数接收一个 JSON 模式列表，用于描述 Claude 可以调用的可用函数。

理解多块消息

当 Claude 决定使用工具时，它会返回一条包含多个内容块的助手消息。这与你之前处理的简单纯文本响应有很大不同。

多块消息通常包含：

文本块 - 人类可读的文本，解释 Claude 正在做什么（例如"我可以帮你查询当前时间。让我为你查找这个信息"）
工具使用块 - 关于调用哪个工具以及使用哪些参数的代码指令

ToolUse 块包含：

用于追踪工具调用的 ID
要调用的函数名称（如 "get_current_datetime"）
以字典格式传入的输入参数
类型标识 "tool_use"

使用多块消息管理对话历史

请记住，Claude 不会存储对话历史------你需要手动管理它。在处理工具响应时，你必须保留完整的内容结构，包括所有块。

以下是如何正确将多块助手消息追加到对话历史记录中的方法：

go 复制代码

messages.append({
    "role": "assistant",
    "content": response.content
})

这样可以同时保留文本块和工具使用块，这对于在后续 API 调用中维护对话上下文至关重要。

完整的工具使用流程

工具使用流程遵循以下模式：

将用户消息连同工具模式发送给 Claude
接收包含文本块和工具使用块的助手消息
提取工具信息并执行实际函数
将工具结果连同完整对话历史发送回 Claude
接收 Claude 的最终响应

每个步骤都需要仔细处理消息结构，以确保 Claude 拥有提供准确响应所需的完整上下文。

更新辅助函数

如果你一直在使用 add_user_message() 和 add_assistant_message() 等辅助函数，你需要更新它们以处理多块内容。当前版本可能只支持单个文本块，但现在它们需要适应包含工具使用块的更复杂内容结构。

这种多块消息处理对于构建健壮的应用程序至关重要，它能够无缝集成 Claude 的工具功能，同时保持正确的对话流程。

发送工具结果

在 Claude 请求工具调用后，你需要执行函数并将结果返回。这样就完成了工具使用的工作流程，为 Claude 提供了它所请求的信息。

运行工具函数

当 Claude 返回一个工具使用块时，你需要提取输入参数并调用你的函数。以下是访问工具参数的方法：

css 复制代码

response.content[1].input

这会返回一个包含 Claude 想要传递给函数的参数的字典。由于你的函数需要关键字参数而不是字典，因此需要使用 Python 的解包语法：

scss 复制代码

get_current_datetime(**response.content[1].input)

## 工具结果块

运行工具函数后，你需要使用工具结果块将结果发送回 Claude。该块放置在用户消息内部，用于告知 Claude 执行工具时发生了什么。

工具结果块具有几个重要属性：

tool_use_id - 必须与此 ToolResult 对应的 ToolUse 块的 id 相匹配
content - 运行工具后的输出，序列化为字符串
is_error - 如果发生错误则为 True

处理多个工具调用

Claude 可以在单次响应中请求多个工具调用。例如，如果用户问"10 + 10 等于多少，30 + 30 等于多少？"，Claude 可能会返回两个独立的 ToolUse 块。

每个工具调用都有一个唯一的 ID，在返回结果时必须匹配这些 ID。这确保了 Claude 能够知道哪个结果对应哪个请求，即使结果的返回顺序不同。

## 构建后续请求

您对 Claude 的后续请求必须包含完整的对话历史以及新的工具结果。以下是结构：

python 复制代码

messages.append({
    "role": "user",
    "content": [{
        "type": "tool_result",
        "tool_use_id": response.content[1].id,
        "content": "15:04:22",
        "is_error": False
    }]
})

完整的消息历史现在包含：

原始用户消息
包含工具使用块的助手消息
包含工具结果块的用户消息

发起最终请求

发送后续请求时，即使你不期望 Claude 再次调用工具，仍然必须包含工具 schema。Claude 需要该 schema 来理解对话历史中的工具引用。

ini 复制代码

client.messages.create(
    model=model,
    max_tokens=1000,
    messages=messages,
    tools=[get_current_datetime_schema]
)

Claude 随后会返回一条最终消息，将工具结果整合为面向用户的自然回复。至此，工具使用工作流已全部完成------您已成功让 Claude 通过自定义函数访问实时信息。

多轮工具对话

在构建包含多个工具的应用程序时，你需要处理 Claude 可能需要按顺序调用多个工具来回答单个用户问题的场景。例如，如果用户问"从今天起 103 天后是哪一天？"，Claude 需要先获取当前日期，然后在此基础上加上 103 天。

这会创建一个多轮对话模式，Claude 在提供最终答案之前会发出多个工具请求。您的应用程序需要自动处理这种情况。

多轮工具模式

以下是 Claude 需要使用多个工具时的幕后工作流程：

用户问："从今天起103天后是哪一天？"
Claude 使用工具调用块进行响应，请求 get_current_datetime
你的服务器调用该函数并返回结果
Claude 意识到需要更多信息，于是请求调用 add_duration_to_datetime
你的服务器调用该函数并返回结果
Claude 现在有了足够的信息来提供最终答案

构建对话循环

要处理这种模式，你需要一个对话循环，持续运行直到 Claude 停止请求工具：

vbscript 复制代码

def run_conversation(messages):
    while True:
        response = chat(messages)
  
        add_user_message(messages, response)
  
        # Pseudo code
        if response isn't asking for a tool:
            break
  
        tool_result_blocks = run_tools(response)
        add_user_message(tool_result_blocks)
  
    return messages

重构辅助函数

在实现对话循环之前，你需要更新辅助函数以正确处理多个消息块。

更新消息处理器

你的 add_user_message 和 add_assistant_message 函数目前假设处理的始终是纯文本。请更新它们以处理完整的消息对象：

python 复制代码

from anthropic.types import Message

def add_user_message(messages, message):
    user_message = {
        "role": "user",
        "content": message.content if isinstance(message, Message) else message
    }
    messages.append(user_message)

这样你就可以传入字符串、块列表或完整的消息对象。

更新聊天函数

修改你的聊天函数，使其接受工具列表并返回完整消息，而不仅仅是文本：

csharp 复制代码

def chat(messages, system=None, temperature=1.0, stop_sequences=[], tools=None):
    params = {
        "model": model,
        "max_tokens": 1000,
        "messages": messages,
        "temperature": temperature,
        "stop_sequences": stop_sequences,
    }
  
    if tools:
        params["tools"] = tools
  
    if system:
        params["system"] = system
  
    message = client.messages.create(**params)
    return message

从消息中提取文本

由于你现在返回的是完整的消息对象，需要创建一个辅助函数来在需要时提取文本：

python 复制代码

def text_from_message(message):
    return "\n".join(
        [block.text for block in message.content if block.type == "text"]
    )

这个函数会查找消息中的所有文本块并将它们拼接在一起，当你需要向用户展示最终响应时非常有用。

关键改进

这些重构步骤为你的代码实现健壮的工具处理做好了准备：

灵活的消息处理 - 你的辅助函数现在可以处理不同的消息格式
聊天中的工具支持 - 聊天函数可以接收并传递工具模式
完整消息返回 - 您将获得完整的消息对象而非仅文本，保留所有内容块
文本提取工具 - 从复杂消息中轻松获取可读文本

有了这些基础，你就可以实现自动处理多次工具调用的对话循环，创造无缝体验，让 Claude 能够根据需要使用任意数量的工具来回答用户问题。

实现多轮对话

构建带有工具的对话系统需要实现一个循环，持续调用 Claude 直到它停止请求使用工具。当 Claude 不再请求工具时，这表明它已准备好向用户提供最终响应。

检测工具请求

判断 Claude 是否想要使用工具的关键在于响应消息中的 stop_reason 字段。当 Claude 决定需要调用工具时，该字段会被设置为 "tool_use"。这为我们提供了一种简洁的方式来检查是否需要继续对话循环：

kotlin 复制代码

if response.stop_reason != "tool_use":
    break  # Claude is done, no more tools needed

对话循环

主对话函数遵循一个简单的模式：

scss 复制代码

def run_conversation(messages):
    while True:
        response = chat(messages, tools=[get_current_datetime_schema])
        add_assistant_message(messages, response)
        print(text_from_message(response))
  
        if response.stop_reason != "tool_use":
            break
  
        tool_results = run_tools(response)
        add_user_message(messages, tool_results)
  
    return messages

这个循环会持续进行，直到 Claude 给出最终答案而不再请求任何工具。

处理多个工具调用

Claude 可以在单次响应中请求多个工具。消息内容包含一个块列表，我们需要分别处理每个工具使用块：

run_tools 函数通过筛选工具使用块并逐一处理来实现这一功能：

ini 复制代码

def run_tools(message):
    tool_requests = [
        block for block in message.content if block.type == "tool_use"
    ]
    tool_result_blocks = []
  
    for tool_request in tool_requests:
        # Process each tool request...

工具结果块

每个工具使用块必须有对应的工具结果块来回应。它们之间的关联通过匹配的 ID 来维护：

工具结果块结构包括：

python 复制代码

tool_result_block = {
    "type": "tool_result",
    "tool_use_id": tool_request.id,
    "content": json.dumps(tool_output),
    "is_error": False
}

错误处理

稳健的工具执行需要处理潜在的错误。当工具失败时，我们仍然需要向 Claude 提供一个结果块：

python 复制代码

try:
    tool_output = run_tool(tool_request.name, tool_request.input)
    tool_result_block = {
        "type": "tool_result",
        "tool_use_id": tool_request.id,
        "content": json.dumps(tool_output),
        "is_error": False
    }
except Exception as e:
    tool_result_block = {
        "type": "tool_result", 
        "tool_use_id": tool_request.id,
        "content": f"Error: {e}",
        "is_error": True
    }

可扩展的工具路由

为了支持多个工具，需创建一个路由函数，将工具名称映射到其对应的实现：

python 复制代码

def run_tool(tool_name, tool_input):
    if tool_name == "get_current_datetime":
        return get_current_datetime(**tool_input)
    elif tool_name == "another_tool":
        return another_tool(**tool_input)
    # Add more tools as needed

这种方法使得添加新工具变得简单，无需修改核心对话逻辑。

完整工作流程

完整的多轮对话工作流程如下：

将用户消息连同可用工具发送给 Claude
Claude 以文本和/或工具请求进行响应
执行所有请求的工具并创建结果块
将工具结果作为用户消息发送回去
重复上述步骤，直到 Claude 提供最终答案

这创造了一种无缝体验，Claude 可以在多轮对话中使用多个工具来完整回答复杂的用户请求。对话历史记录保留了完整的上下文，使 Claude 能够基于之前的工具结果提供全面的回复。

使用多个工具

一旦你建立了核心的工具处理基础架构，向 Claude 实现中添加多个工具就变得非常简单。本教程将展示如何通过遵循一个简单的模式来集成额外的工具。

我们正在添加的工具

我们的提醒系统需要三个主要功能：

获取当前日期时间 - Claude 需要知道当前的日期和时间
将时长添加到日期时间 - Claude 在日期时间加法方面并不完美
设置提醒 - 需要一种设置提醒的方式

好消息是，大部分实现工作已经完成。add_duration_to_datetime 函数和 set_reminder 函数已经提供，同时还有它们对应的 schema。

将工具添加到对话中

首先，更新 run_conversation 函数，将新的工具模式添加到 tools 列表中：

ini 复制代码

response = chat(messages, tools=[
    get_current_datetime_schema,
    add_duration_to_datetime_schema,
    set_reminder_schema
])

这告诉 Claude 在对话过程中可以使用的所有三个可用工具。

更新工具路由器

接下来，修改 run_tool 函数以处理新的工具调用。为每个新工具添加 elif 分支：

python 复制代码

def run_tool(tool_name, tool_input):
    if tool_name == "get_current_datetime":
        return get_current_datetime(**tool_input)
    elif tool_name == "add_duration_to_datetime":
        return add_duration_to_datetime(**tool_input)
    elif tool_name == "set_reminder":
        return set_reminder(**tool_input)

模式很简单：检查工具名称，使用提供的输入调用相应的函数，然后返回结果。

测试多工具使用

要测试该系统，请尝试一个需要多个工具的请求："为我的医生预约设置一个提醒。时间是2050年1月1日之后的第177天。"

这个请求会迫使 Claude：

计算日期（使用 add_duration_to_datetime）
设置提醒（使用 set_reminder）

Claude 通过首先解释需要做什么，然后按顺序进行适当的工具调用来处理这个问题。对话显示 Claude 计算出 2050 年 6 月 27 日为目标日期，然后为该日期设置提醒。

理解消息流程

当你查看对话历史时，你会看到完整的消息结构：

用户消息及请求
包含文本和工具使用块的助手消息
工具结果消息
后续助手消息

这展示了 Claude 如何在单条消息中包含多个内容块------将解释性文本与工具使用请求相结合。

添加工具的简单模式

一旦你有了核心工具基础设施，添加新工具就遵循这个模式：

创建工具函数实现
定义工具模式
将模式添加到 run_conversation 中的工具列表
在 run_tool 中为该工具添加一个分支

这种模块化方法使您可以轻松扩展 AI 助手的功能，而无需重构现有代码。每个新工具都能与现有的对话流程和工具处理逻辑无缝集成。

请求和响应报文

工具调用日志

css 复制代码

run_tool: get_current_datetime, {}

run_tool: add_duration_to_datetime, {'datetime_str': '2026-02-13 10:55:04', 'input_format': '%Y-%m-%d %H:%M:%S', 'duration': 2000, 'unit': 'days'}

run_tool: set_reminder, {'content': '医生预约', 'timestamp': '2031-08-06T10:55:04'}
----
 设置提醒 2031-08-06T10:55:04:
医生预约
----
已经为您设置好了医生预约提醒。

提醒时间定在 **2031年8月6日（星期三）上午 10:55:04**，即当前时间之后的第 2000 天。

第一次请求

json 复制代码

{
  "max_tokens": 4000,
  "messages": [
    {
      "role": "user",
      "content": "请为我的医生预约设置一个提醒，当前时间之后的第2000天"
    }
  ],
  "model": "gemini-3-flash",
  "stop_sequences": [],
  "temperature": 1,
  "tools": [
    {
      "name": "get_current_datetime",
      "description": "根据指定格式返回当前日期和时间。\n                此工具提供格式化的系统时间字符串，适用于时间戳记录、时间差计算或向用户显示当前时间。\n                默认格式为 YYYY-MM-DD HH:MM:SS。",
      "input_schema": {
        "type": "object",
        "properties": {
          "date_format": {
            "type": "string",
            "description": "指定返回日期时间格式的字符串，使用 Python 的 strftime 格式代码。\n                    例如：'%Y-%m-%d' 返回日期（YYYY-MM-DD），'%H:%M:%S' 返回时间（HH:MM:SS），'%B %d, %Y' 返回如 'May 07, 2025' 的日期。\n                    默认为 '%Y-%m-%d %H:%M:%S'，返回完整时间戳如 '2025-05-07 14:32:15'。.",
            "default": "%Y-%m-%d %H:%M:%S"
          }
        },
        "required": []
      }
    },
    {
      "name": "add_duration_to_datetime",
      "description": "\n              将指定的时间长度添加到日期时间字符串，并以详细格式返回结果日期时间。\n              此工具将输入的日期时间字符串转换为 Python datetime 对象，\n              在请求的时间单位中添加指定的时间长度，并返回格式化后的结果日期时间字符串。\n              它处理各种时间单位，包括秒、分钟、小时、天、周、月和年，对月份和年份的计算进行特殊处理，以考虑不同月份长度和闰年。\n              输出始终以详细格式返回，包括星期几、月份名称、日期、年份和带 AM/PM 指示符的时间（\n              例如，'Thursday, April 03, 2025 10:30:00 AM'）。\n            ",
      "input_schema": {
        "type": "object",
        "properties": {
          "datetime_str": {
            "type": "string",
            "description": "要添加时间长度的输入日期时间字符串。应根据 input_format 参数进行格式化。"
          },
          "duration": {
            "type": "number",
            "description": "要添加到日期时间的时间量。可以是正数（用于未来日期）或负数（用于过去日期）。默认为 0。"
          },
          "unit": {
            "type": "string",
            "description": "时间长度的单位。必须是以下之一：'seconds'、'minutes'、'hours'、'days'、'weeks'、'months' 或 'years'。默认为 'days'。"
          },
          "input_format": {
            "type": "string",
            "description": "用于解析输入 datetime_str 的格式字符串，使用 Python 的 strptime 格式代码。例如，'%Y-%m-%d' 用于 ISO 格式日期，如 '2025-04-03'。默认为 '%Y-%m-%d'。"
          }
        },
        "required": [
          "datetime_str"
        ]
      }
    },
    {
      "name": "set_reminder",
      "description": "创建一个定时提醒，将在指定时间使用提供的内容通知用户。\n    此工具安排在提供的精确时间戳向用户发送通知。\n    当用户希望在未来的某个时间点被提醒某事时，应使用此工具。\n    提醒系统将存储内容和时间戳，然后在指定时间到达时通过用户首选的通知渠道（移动设备提醒、电子邮件等）触发通知。\n    即使应用程序关闭或设备重启，提醒也会持久保存。\n    用户可以依赖此功能来处理重要的时间敏感通知，如会议、任务、药物时间表或任何其他有时间限制的活动。\n    ",
      "input_schema": {
        "type": "object",
        "properties": {
          "content": {
            "type": "string",
            "description": "将在提醒通知中显示的消息文本。应包含用户希望被提醒的具体信息，例如'服药'、'加入团队视频通话'或'支付水电费'。"
          },
          "timestamp": {
            "type": "string",
            "description": "应触发提醒的确切日期和时间，格式为 ISO 8601 时间戳（YYYY-MM-DDTHH:MM:SS）或 Unix 时间戳。\n                系统在内部处理所有时区处理，确保无论用户位于何处，提醒都会在正确的时间触发。\n                用户可以简单地指定所需时间，而无需担心时区配置。"
          }
        },
        "required": [
          "content",
          "timestamp"
        ]
      }
    }
  ]
}

第一次响应

json 复制代码

{
  "id": "jIeOabORHtmB0-kP3KnVgA4",
  "type": "message",
  "role": "assistant",
  "model": "gemini-3-flash",
  "content": [
    {
      "type": "tool_use",
      "id": "get_current_datetime-fJFTEdLc",
      "name": "get_current_datetime",
      "input": {}
    }
  ],
  "stop_reason": "tool_use",
  "usage": {
    "input_tokens": 1025,
    "output_tokens": 12,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  }
}

第二次请求

json 复制代码

{
  "max_tokens": 4000,
  "messages": [
    {
      "role": "user",
      "content": "请为我的医生预约设置一个提醒，当前时间之后的第2000天"
    },
    {
      "role": "assistant",
      "content": [
        {
          "id": "get_current_datetime-fJFTEdLc",
          "input": {},
          "name": "get_current_datetime",
          "type": "tool_use"
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "get_current_datetime-fJFTEdLc",
          "content": "\"2026-02-13 10:08:12\"",
          "is_error": false
        }
      ]
    }
  ],
  "model": "gemini-3-flash",
  "stop_sequences": [],
  "temperature": 1,
  "tools": [
    {
      "name": "get_current_datetime",
      "description": "根据指定格式返回当前日期和时间。\n                此工具提供格式化的系统时间字符串，适用于时间戳记录、时间差计算或向用户显示当前时间。\n                默认格式为 YYYY-MM-DD HH:MM:SS。",
      "input_schema": {
        "type": "object",
        "properties": {
          "date_format": {
            "type": "string",
            "description": "指定返回日期时间格式的字符串，使用 Python 的 strftime 格式代码。\n                    例如：'%Y-%m-%d' 返回日期（YYYY-MM-DD），'%H:%M:%S' 返回时间（HH:MM:SS），'%B %d, %Y' 返回如 'May 07, 2025' 的日期。\n                    默认为 '%Y-%m-%d %H:%M:%S'，返回完整时间戳如 '2025-05-07 14:32:15'。.",
            "default": "%Y-%m-%d %H:%M:%S"
          }
        },
        "required": []
      }
    },
    {
      "name": "add_duration_to_datetime",
      "description": "\n              将指定的时间长度添加到日期时间字符串，并以详细格式返回结果日期时间。\n              此工具将输入的日期时间字符串转换为 Python datetime 对象，\n              在请求的时间单位中添加指定的时间长度，并返回格式化后的结果日期时间字符串。\n              它处理各种时间单位，包括秒、分钟、小时、天、周、月和年，对月份和年份的计算进行特殊处理，以考虑不同月份长度和闰年。\n              输出始终以详细格式返回，包括星期几、月份名称、日期、年份和带 AM/PM 指示符的时间（\n              例如，'Thursday, April 03, 2025 10:30:00 AM'）。\n            ",
      "input_schema": {
        "type": "object",
        "properties": {
          "datetime_str": {
            "type": "string",
            "description": "要添加时间长度的输入日期时间字符串。应根据 input_format 参数进行格式化。"
          },
          "duration": {
            "type": "number",
            "description": "要添加到日期时间的时间量。可以是正数（用于未来日期）或负数（用于过去日期）。默认为 0。"
          },
          "unit": {
            "type": "string",
            "description": "时间长度的单位。必须是以下之一：'seconds'、'minutes'、'hours'、'days'、'weeks'、'months' 或 'years'。默认为 'days'。"
          },
          "input_format": {
            "type": "string",
            "description": "用于解析输入 datetime_str 的格式字符串，使用 Python 的 strptime 格式代码。例如，'%Y-%m-%d' 用于 ISO 格式日期，如 '2025-04-03'。默认为 '%Y-%m-%d'。"
          }
        },
        "required": [
          "datetime_str"
        ]
      }
    },
    {
      "name": "set_reminder",
      "description": "创建一个定时提醒，将在指定时间使用提供的内容通知用户。\n    此工具安排在提供的精确时间戳向用户发送通知。\n    当用户希望在未来的某个时间点被提醒某事时，应使用此工具。\n    提醒系统将存储内容和时间戳，然后在指定时间到达时通过用户首选的通知渠道（移动设备提醒、电子邮件等）触发通知。\n    即使应用程序关闭或设备重启，提醒也会持久保存。\n    用户可以依赖此功能来处理重要的时间敏感通知，如会议、任务、药物时间表或任何其他有时间限制的活动。\n    ",
      "input_schema": {
        "type": "object",
        "properties": {
          "content": {
            "type": "string",
            "description": "将在提醒通知中显示的消息文本。应包含用户希望被提醒的具体信息，例如'服药'、'加入团队视频通话'或'支付水电费'。"
          },
          "timestamp": {
            "type": "string",
            "description": "应触发提醒的确切日期和时间，格式为 ISO 8601 时间戳（YYYY-MM-DDTHH:MM:SS）或 Unix 时间戳。\n                系统在内部处理所有时区处理，确保无论用户位于何处，提醒都会在正确的时间触发。\n                用户可以简单地指定所需时间，而无需担心时区配置。"
          }
        },
        "required": [
          "content",
          "timestamp"
        ]
      }
    }
  ]
}

第二次响应

json 复制代码

{
  "id": "kYeOad3LC62j2roPgaaeoAE",
  "type": "message",
  "role": "assistant",
  "model": "gemini-3-flash",
  "content": [
    {
      "type": "tool_use",
      "id": "add_duration_to_datetime-gxN7PUmS",
      "name": "add_duration_to_datetime",
      "input": {
        "datetime_str": "2026-02-13 10:08:12",
        "duration": 2000,
        "unit": "days",
        "input_format": "%Y-%m-%d %H:%M:%S"
      }
    }
  ],
  "stop_reason": "tool_use",
  "usage": {
    "input_tokens": 1100,
    "output_tokens": 72,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  }
}

第三次请求

json 复制代码

{
  "max_tokens": 4000,
  "messages": [
    {
      "role": "user",
      "content": "请为我的医生预约设置一个提醒，当前时间之后的第2000天"
    },
    {
      "role": "assistant",
      "content": [
        {
          "id": "get_current_datetime-fJFTEdLc",
          "input": {},
          "name": "get_current_datetime",
          "type": "tool_use"
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "get_current_datetime-fJFTEdLc",
          "content": "\"2026-02-13 10:08:12\"",
          "is_error": false
        }
      ]
    },
    {
      "role": "assistant",
      "content": [
        {
          "id": "add_duration_to_datetime-gxN7PUmS",
          "input": {
            "datetime_str": "2026-02-13 10:08:12",
            "duration": 2000,
            "unit": "days",
            "input_format": "%Y-%m-%d %H:%M:%S"
          },
          "name": "add_duration_to_datetime",
          "type": "tool_use"
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "add_duration_to_datetime-gxN7PUmS",
          "content": "\"Wednesday, August 06, 2031 10:08:12 AM\"",
          "is_error": false
        }
      ]
    }
  ],
  "model": "gemini-3-flash",
  "stop_sequences": [],
  "temperature": 1,
  "tools": [
    {
      "name": "get_current_datetime",
      "description": "根据指定格式返回当前日期和时间。\n                此工具提供格式化的系统时间字符串，适用于时间戳记录、时间差计算或向用户显示当前时间。\n                默认格式为 YYYY-MM-DD HH:MM:SS。",
      "input_schema": {
        "type": "object",
        "properties": {
          "date_format": {
            "type": "string",
            "description": "指定返回日期时间格式的字符串，使用 Python 的 strftime 格式代码。\n                    例如：'%Y-%m-%d' 返回日期（YYYY-MM-DD），'%H:%M:%S' 返回时间（HH:MM:SS），'%B %d, %Y' 返回如 'May 07, 2025' 的日期。\n                    默认为 '%Y-%m-%d %H:%M:%S'，返回完整时间戳如 '2025-05-07 14:32:15'。.",
            "default": "%Y-%m-%d %H:%M:%S"
          }
        },
        "required": []
      }
    },
    {
      "name": "add_duration_to_datetime",
      "description": "\n              将指定的时间长度添加到日期时间字符串，并以详细格式返回结果日期时间。\n              此工具将输入的日期时间字符串转换为 Python datetime 对象，\n              在请求的时间单位中添加指定的时间长度，并返回格式化后的结果日期时间字符串。\n              它处理各种时间单位，包括秒、分钟、小时、天、周、月和年，对月份和年份的计算进行特殊处理，以考虑不同月份长度和闰年。\n              输出始终以详细格式返回，包括星期几、月份名称、日期、年份和带 AM/PM 指示符的时间（\n              例如，'Thursday, April 03, 2025 10:30:00 AM'）。\n            ",
      "input_schema": {
        "type": "object",
        "properties": {
          "datetime_str": {
            "type": "string",
            "description": "要添加时间长度的输入日期时间字符串。应根据 input_format 参数进行格式化。"
          },
          "duration": {
            "type": "number",
            "description": "要添加到日期时间的时间量。可以是正数（用于未来日期）或负数（用于过去日期）。默认为 0。"
          },
          "unit": {
            "type": "string",
            "description": "时间长度的单位。必须是以下之一：'seconds'、'minutes'、'hours'、'days'、'weeks'、'months' 或 'years'。默认为 'days'。"
          },
          "input_format": {
            "type": "string",
            "description": "用于解析输入 datetime_str 的格式字符串，使用 Python 的 strptime 格式代码。例如，'%Y-%m-%d' 用于 ISO 格式日期，如 '2025-04-03'。默认为 '%Y-%m-%d'。"
          }
        },
        "required": [
          "datetime_str"
        ]
      }
    },
    {
      "name": "set_reminder",
      "description": "创建一个定时提醒，将在指定时间使用提供的内容通知用户。\n    此工具安排在提供的精确时间戳向用户发送通知。\n    当用户希望在未来的某个时间点被提醒某事时，应使用此工具。\n    提醒系统将存储内容和时间戳，然后在指定时间到达时通过用户首选的通知渠道（移动设备提醒、电子邮件等）触发通知。\n    即使应用程序关闭或设备重启，提醒也会持久保存。\n    用户可以依赖此功能来处理重要的时间敏感通知，如会议、任务、药物时间表或任何其他有时间限制的活动。\n    ",
      "input_schema": {
        "type": "object",
        "properties": {
          "content": {
            "type": "string",
            "description": "将在提醒通知中显示的消息文本。应包含用户希望被提醒的具体信息，例如'服药'、'加入团队视频通话'或'支付水电费'。"
          },
          "timestamp": {
            "type": "string",
            "description": "应触发提醒的确切日期和时间，格式为 ISO 8601 时间戳（YYYY-MM-DDTHH:MM:SS）或 Unix 时间戳。\n                系统在内部处理所有时区处理，确保无论用户位于何处，提醒都会在正确的时间触发。\n                用户可以简单地指定所需时间，而无需担心时区配置。"
          }
        },
        "required": [
          "content",
          "timestamp"
        ]
      }
    }
  ]
}

第三次响应

json 复制代码

{
  "id": "lYeOacL2F9_LrfcPyO65kQE",
  "type": "message",
  "role": "assistant",
  "model": "gemini-3-flash",
  "content": [
    {
      "type": "tool_use",
      "id": "set_reminder-0Hk1mR5T",
      "name": "set_reminder",
      "input": {
        "content": "医生预约 (Doctor's appointment)",
        "timestamp": "2031-08-06T10:08:12"
      }
    }
  ],
  "stop_reason": "tool_use",
  "usage": {
    "input_tokens": 1213,
    "output_tokens": 47,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  }
}

第四次请求

json 复制代码

{
  "max_tokens": 4000,
  "messages": [
    {
      "role": "user",
      "content": "请为我的医生预约设置一个提醒，当前时间之后的第2000天"
    },
    {
      "role": "assistant",
      "content": [
        {
          "id": "get_current_datetime-fJFTEdLc",
          "input": {},
          "name": "get_current_datetime",
          "type": "tool_use"
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "get_current_datetime-fJFTEdLc",
          "content": "\"2026-02-13 10:08:12\"",
          "is_error": false
        }
      ]
    },
    {
      "role": "assistant",
      "content": [
        {
          "id": "add_duration_to_datetime-gxN7PUmS",
          "input": {
            "datetime_str": "2026-02-13 10:08:12",
            "duration": 2000,
            "unit": "days",
            "input_format": "%Y-%m-%d %H:%M:%S"
          },
          "name": "add_duration_to_datetime",
          "type": "tool_use"
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "add_duration_to_datetime-gxN7PUmS",
          "content": "\"Wednesday, August 06, 2031 10:08:12 AM\"",
          "is_error": false
        }
      ]
    },
    {
      "role": "assistant",
      "content": [
        {
          "id": "set_reminder-0Hk1mR5T",
          "input": {
            "content": "医生预约 (Doctor's appointment)",
            "timestamp": "2031-08-06T10:08:12"
          },
          "name": "set_reminder",
          "type": "tool_use"
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "set_reminder-0Hk1mR5T",
          "content": "null",
          "is_error": false
        }
      ]
    }
  ],
  "model": "gemini-3-flash",
  "stop_sequences": [],
  "temperature": 1,
  "tools": [
    {
      "name": "get_current_datetime",
      "description": "根据指定格式返回当前日期和时间。\n                此工具提供格式化的系统时间字符串，适用于时间戳记录、时间差计算或向用户显示当前时间。\n                默认格式为 YYYY-MM-DD HH:MM:SS。",
      "input_schema": {
        "type": "object",
        "properties": {
          "date_format": {
            "type": "string",
            "description": "指定返回日期时间格式的字符串，使用 Python 的 strftime 格式代码。\n                    例如：'%Y-%m-%d' 返回日期（YYYY-MM-DD），'%H:%M:%S' 返回时间（HH:MM:SS），'%B %d, %Y' 返回如 'May 07, 2025' 的日期。\n                    默认为 '%Y-%m-%d %H:%M:%S'，返回完整时间戳如 '2025-05-07 14:32:15'。.",
            "default": "%Y-%m-%d %H:%M:%S"
          }
        },
        "required": []
      }
    },
    {
      "name": "add_duration_to_datetime",
      "description": "\n              将指定的时间长度添加到日期时间字符串，并以详细格式返回结果日期时间。\n              此工具将输入的日期时间字符串转换为 Python datetime 对象，\n              在请求的时间单位中添加指定的时间长度，并返回格式化后的结果日期时间字符串。\n              它处理各种时间单位，包括秒、分钟、小时、天、周、月和年，对月份和年份的计算进行特殊处理，以考虑不同月份长度和闰年。\n              输出始终以详细格式返回，包括星期几、月份名称、日期、年份和带 AM/PM 指示符的时间（\n              例如，'Thursday, April 03, 2025 10:30:00 AM'）。\n            ",
      "input_schema": {
        "type": "object",
        "properties": {
          "datetime_str": {
            "type": "string",
            "description": "要添加时间长度的输入日期时间字符串。应根据 input_format 参数进行格式化。"
          },
          "duration": {
            "type": "number",
            "description": "要添加到日期时间的时间量。可以是正数（用于未来日期）或负数（用于过去日期）。默认为 0。"
          },
          "unit": {
            "type": "string",
            "description": "时间长度的单位。必须是以下之一：'seconds'、'minutes'、'hours'、'days'、'weeks'、'months' 或 'years'。默认为 'days'。"
          },
          "input_format": {
            "type": "string",
            "description": "用于解析输入 datetime_str 的格式字符串，使用 Python 的 strptime 格式代码。例如，'%Y-%m-%d' 用于 ISO 格式日期，如 '2025-04-03'。默认为 '%Y-%m-%d'。"
          }
        },
        "required": [
          "datetime_str"
        ]
      }
    },
    {
      "name": "set_reminder",
      "description": "创建一个定时提醒，将在指定时间使用提供的内容通知用户。\n    此工具安排在提供的精确时间戳向用户发送通知。\n    当用户希望在未来的某个时间点被提醒某事时，应使用此工具。\n    提醒系统将存储内容和时间戳，然后在指定时间到达时通过用户首选的通知渠道（移动设备提醒、电子邮件等）触发通知。\n    即使应用程序关闭或设备重启，提醒也会持久保存。\n    用户可以依赖此功能来处理重要的时间敏感通知，如会议、任务、药物时间表或任何其他有时间限制的活动。\n    ",
      "input_schema": {
        "type": "object",
        "properties": {
          "content": {
            "type": "string",
            "description": "将在提醒通知中显示的消息文本。应包含用户希望被提醒的具体信息，例如'服药'、'加入团队视频通话'或'支付水电费'。"
          },
          "timestamp": {
            "type": "string",
            "description": "应触发提醒的确切日期和时间，格式为 ISO 8601 时间戳（YYYY-MM-DDTHH:MM:SS）或 Unix 时间戳。\n                系统在内部处理所有时区处理，确保无论用户位于何处，提醒都会在正确的时间触发。\n                用户可以简单地指定所需时间，而无需担心时区配置。"
          }
        },
        "required": [
          "content",
          "timestamp"
        ]
      }
    }
  ]
}

第四次响应

json 复制代码

{
  "id": "mYeOadm0Nc6yvr0PxoWGoQ0",
  "type": "message",
  "role": "assistant",
  "model": "gemini-3-flash",
  "content": [
    {
      "type": "text",
      "text": "好的，我已经为您设置好了提醒。\n\n**提醒详情：**\n*   **内容：** 医生预约 (Doctor's appointment)\n*   **时间：** 2031年8月6日（星期三）10:08:12 AM\n\n这是从当前时间（2026年2月13日）起计的第2000天。"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 1274,
    "output_tokens": 87,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  }
}