我的日记

Appearance

Claude 外部工具使用：从原理到实战开发 ​

课程说明：本课程将深度解析 Claude 的“外部工具使用”（Tool Use/Function Calling）机制。通过本课程，您将学习如何打破 AI 的知识边界，让 Claude 能够实时获取天气、操作数据库、甚至像程序员一样编辑文件。

第一课：工具使用机制全解析 ​

1.1 为什么需要工具？ ​

默认情况下，Claude 仅拥有训练数据中的知识，无法获知实时信息（如“今天的天气”）。外部工具为 Claude 创建了一个结构化的通道，允许它根据需求向外部系统请求并接收最新数据。

1.2 工具调用的闭环流程 ​

工具调用遵循一个清晰的往返模式：

  1. 基础请求：您向 Claude 发送问题，并提供可调用的工具说明（模式）。
  2. 工具请求：Claude 分析问题发现需要额外信息，返回一个包含具体参数的“工具调用请求”。
  3. 数据检索：您的服务器解析该请求，执行相应的代码（访问 API 或数据库）。
  4. 最终响应：您将获取的数据返回给 Claude，Claude 结合原始问题与新数据生成最终答案。

1.3 核心优势 ​

  • 实时性：获取训练日期之后的最新资讯。
  • 系统集成：连接数据库、第三方仓库或内部服务。
  • 动态交互：基于最新可用信息提供精准回答。

第二课：实战项目：智能提醒系统 ​

核心逻辑：我们将构建一个提醒系统，通过工具解决 AI 的三个弱点：

  1. 时间感模糊：模型知道日期但不一定知道精确的时间。
  2. 日期计算困难：对于“下周四”这种计算，AI 容易出错。
  3. 缺乏执行力：AI 无法自行执行“设置提醒”的操作。

规划所需工具 ​

  • get_current_datetime：获取当前精确时间。
  • add_duration_to_datetime：精确计算未来时间戳。
  • set_reminder：在系统中正式录入提醒。

第三课：编写工具函数与定义模式 (Schema) ​

3.1 编写工具函数 (Tool Functions) ​

工具函数是普通的 Python 函数。 最佳实践：

  • 描述性命名：函数名和参数名应明确表达意图。
  • 输入校验：在函数内部检查参数合法性。
  • 异常处理：返回清晰的错误信息，Claude 看到错误后可能会尝试修正参数重新调用。
python
def get_current_datetime(date_format="%Y-%m-%d %H:%M:%S"):
    if not date_format:
        raise ValueError("日期格式不能为空")
    return datetime.now().strftime(date_format)

3.2 定义 JSON 模式 (JSON Schema) ​

模式是交给 Claude 阅读的“说明书”，包含三个部分：

  • name：工具名称。
  • description：详细描述工具用途（建议 3-4 句）。
  • input_schema：参数的类型、描述及是否必填。

💡 小技巧：您可以将函数代码发给 Claude，让它基于 Anthropic 规范自动为您生成标准的 JSON 模式。

第四课：API 交互与多块消息处理 ​

4.1 开启工具支持 ​

在 API 调用中，通过 tools 参数传入您的模式列表：

python
response = client.messages.create(
    model="claude-3-5-sonnet",
    tools=[get_current_datetime_schema],
    messages=messages
)

4.2 解析多块消息 (Multi-block Messages) ​

当 Claude 决定使用工具时，返回的消息包含多个块：

  • 文本块 (Text Block)：解释它要做什么。
  • 工具调用块 (ToolUse Block)：包含唯一的 id、函数名及经过格式化的 input 参数。

历史记录管理：必须完整保存这些块（包括 tool_use 块）到对话历史中，否则 Claude 会丢失上下文。

第五课：多轮对话与自动化循环 (Conversation Loop) ​

核心逻辑：复杂任务（如计算后提醒）需要多轮对话。我们需要建立一个循环，持续运行直到 Claude 不再请求工具。

5.1 检测终止原因 (Stop Reason) ​

通过检查响应中的 stop_reason 来决定循环是否继续：

  • 如果 stop_reason == "tool_use"：代表需要执行工具并返回结果。
  • 如果 stop_reason != "tool_use"：代表对话已完成。

5.2 自动化循环结构 ​

python
def run_conversation(messages):
    while True:
        response = chat(messages, tools=all_tools)
        add_assistant_message(messages, response)
        
        if response.stop_reason != "tool_use":
            break # 最终回复已生成
            
        tool_results = run_tools(response) # 执行工具并封装为 tool_result 块
        add_user_message(messages, tool_results)
    return messages

第六课：进阶技巧：批量工具与结构化数据提取 ​

6.1 批量工具 (Batch Tool) ​

有时 Claude 会依次请求多个工具，产生多次往返。您可以定义一个 batch_tool，引导 Claude 在一个请求中打包所有需要的操作，从而大幅降低 API 延迟。

6.2 强制工具调用 (Tool Choice) ​

如果您只需要 Claude 提取结构化数据（如 JSON），可以使用 tool_choice 参数：

  • {"type": "auto"}：模型自动决定（默认）。
  • {"type": "any"}：强制使用任意工具。
  • {"type": "tool", "name": "my_tool"}：强制且仅使用指定的工具。

第七课：流式传输中的工具调用 (Streaming) ​

开启流式传输时，工具相关的事件有所不同：

  • 输入 JSON 事件 (InputJsonEvent)：实时推送生成的参数碎片。
    • partial_json：当前的片段。
    • snapshot：当前已构建完成的完整 JSON 镜像。
  • 精细化调用 (Fine-grained)：默认情况下，API 会缓冲并校验 JSON。如果您需要极速响应，可以开启 fine_grained=True 以获取原始碎片（需自行处理不完整的 JSON 语法）。

第八课：内置工具：文本编辑器与网页搜索 ​

8.1 文本编辑器工具 (Text Editor Tool) ​

可以让 Claude 查看目录、读取文件范围、甚至是执行 str_replace。您无需定义模式，但需要根据 Claude 提供的操作指令在服务器端编写具体的执行代码。

8.2 网页搜索工具 (Web Search Tool) ​

  • 配置：设置 max_uses 限制搜索次数。
  • 域限制：使用 allowed_domains 将搜索范围锁定在权威站点（如 nih.gov）。
  • 引用与透明度：响应会包含引用块（Citations），详细展示信息来源。

结语：能力扩展的阶梯 ​

  1. 从简单到复杂：先实现单一工具，再构建自动化循环。
  2. 安全性首位：工具意味着赋予 AI 行动力，务必在本地代码中做好权限校验。
  3. 模式驱动：高质量的描述（Description）是工具调用成功率的关键。

© 内容基于技术文档整理 | 外部工具集成实战手册

测验题 (Quiz) ​

  1. 如何判断对话中 Claude 是否想要发起另一次工具调用？
  • [ ] A. 检查回复中是否包含 "tool" 单词
  • [ ] B. 检查回复是否比平时更长
  • [ ] C. 检查 stop_reason 字段是否为 "tool_use"
  • [ ] D. 计算消息块的数量
  1. 当 Claude 使用工具时，它返回什么类型的消息结构？
  • [ ] A. 包含文本块 (Text Block) 和工具调用块 (Tool Use Block) 的多块消息
  • [ ] B. 简单的纯文本回复
  • [ ] C. 不含文本的纯 JSON 数据
  • [ ] D. 仅返回错误信息
  1. JSON 模式 (JSON Schema) 在 Claude 工具中的主要作用是什么？
  • [ ] A. 为用户格式化最终回复
  • [ ] B. 告知 Claude 预期的参数以及如何使用该工具
  • [ ] C. 存储工具函数调用的结果
  • [ ] D. 加密 Claude 与服务器之间的数据
  1. 批量工具 (Batch Tool) 解决了什么问题？
  • [ ] A. 让工具运行得更快
  • [ ] B. 将工具结果翻译成不同语言
  • [ ] C. 减少需要多个工具时产生的往返通信次数
  • [ ] D. 自动修复工具回复中的错误
  1. 工具使用流程的正确顺序是？
  • [ ] A. 基础请求 → 工具请求 → 数据检索 → 最终响应
  • [ ] B. 工具请求 → 基础请求 → 最终响应 → 数据检索
  • [ ] C. 最终响应 → 基础请求 → 工具请求 → 数据检索
  • [ ] D. 数据检索 → 工具请求 → 基础请求 → 最终响应
  1. Claude 默认只能访问训练数据。什么能让它获取实时的最新信息？
  • [ ] A. 基于模式进行合理的猜测
  • [ ] B. 更仔细地搜索训练数据
  • [ ] C. 要求用户提供更多细节
  • [ ] D. 使用工具访问外部信息
  1. Claude 内置的文本编辑器和网页搜索工具与自定义工具有何不同？
  • [ ] A. Claude 已提供模式定义，但你仍需在服务器端实现具体功能
  • [ ] B. 它们需要特殊的 API 密钥
  • [ ] C. 它们仅支持特定的文件类型
  • [ ] D. 使用成本更高

测验题参考答案 ​

  1. C (检查 stop_reason 字段是否为 "tool_use")
  2. A (多块消息，且包含唯一的工具调用 ID)
  3. B (模式充当了 Claude 阅读的“工具说明书”)
  4. C (通过一次请求打包多个操作以降低延迟)
  5. A (经典的闭环往返流程)
  6. D (通过定义结构化的外部通道让 AI 具备“行动力”)
  7. A (内置工具仅内置了协议约定，服务端实现仍需手动完成)

© 内容基于技术文档整理 | 外部工具集成实战手册

基于 VitePress 构建

Copyright © 2024-present