企业官网建设流程全解析

• 文档
• 提示工程
• 人工智能

本篇技术指南以开源仓库 claude-code-system-prompts 中提取的 Ruby 工具使用参考文档 为骨架，讲解在 Ruby 语言中使用 Claude API 工具（Tool Use）的两种方式：通过 beta 阶段的 Tool Runner 自动执行工具循环，以及手动实现 Agentic 循环。读完本文，你将掌握如何用Anthropic::BaseTool声明可运行工具、如何调用client.beta.messages.tool_runner让 SDK 自动完成「模型调用 → 工具执行 → 结果回传」的闭环，并理解手动循环中内容块（Content Block）的多态处理与消息序列回传规则。

一、参考文档的背景与定位

在 Claude Code 的 System Prompts 提取仓库中，data-前缀的文档对应 Claude Code 内嵌的各种模板文件，其中data-tool-use-reference-ruby.md是面向 Ruby 开发者的工具使用速查卡。它的 frontmatter 记录了以下元信息（见 原文档 开头）：

• name: "Data: Tool use reference — Ruby"
• description: "Ruby tool use reference including the beta tool runner and manual agentic-loop guidance"
• ccVersion: "2.1.246"（即该模板对应的 Claude Code 版本）

根据 README.md 的说明，这些文件是从 Claude Code npm 包的编译后 JS 源码中通过脚本提取出来的，保证与 Claude Code 实际运行时使用的字符串完全一致。模板中的{{OPUS_ID}}属于运行时插值变量，由 Claude Code 在注入时替换为实际的模型 ID，因此文中示例不可直接复制运行，需替换为真实模型标识。

该文档的核心结论是一句话：Ruby SDK 既支持通过原始 JSON Schema 定义工具，也提供了 beta 阶段的 Tool Runner 用于自动执行工具。同时它还强调：关于工具定义格式与 Agentic 循环模式的通用概念，请参阅 Claude Code 内部共享的shared/tool-use-concepts.md文档（该共享文档属于 Claude Code 内嵌模板体系，在 system-prompts 提取目录中未单独收录，本仓库可确认存在的 Ruby 相关材料为 Ruby API 参考 与 Ruby 流式参考）。

二、快速上手：安装 SDK 与初始化客户端

在进入工具使用之前，先确保 Ruby SDK 已安装并完成客户端初始化。这一步的完整说明位于仓库中的>gem install anthropic

require "anthropic" # 默认（使用 ANTHROPIC_API_KEY 环境变量） client = Anthropic::Client.new # 显式传入 API key client = Anthropic::Client.new(api_key: "your-api-key")

需要特别注意的是，该 Ruby API 参考文档在开头即声明：Ruby SDK 目前只提供 beta 版的工具运行器（client.beta.messages.tool_runner()），Agent SDK 在 Ruby 上尚不可用。这意味着在 Ruby 生态中，工具调用的自动化执行主要依赖本文介绍的 Tool Runner 或手动循环。

三、使用 Beta Tool Runner 自动执行工具

这是关联文档的核心章节。Tool Runner 的价值在于：你只需声明「工具长什么样、工具怎么跑」，SDK 会自动处理 API 调用、识别模型发起的tool_use、执行对应的 Ruby 方法、再把结果作为tool_result回传，反复迭代直到模型给出最终文本答案。

3.1 定义工具的输入模型

每个工具的第一步是声明它的 JSON Schema 输入，通过继承Anthropic::BaseModel并使用required宏完成（代码原文见>class GetWeatherInput < Anthropic::BaseModel required :location, String, doc: "City and state, e.g. San Francisco, CA" end

这里required :location, String, doc: "..."声明了一个必填字符串参数location，doc:提供该参数的语义描述，帮助模型理解应如何填充。required表明该字段将进入 schema 的required列表。

3.2 定义可运行的工具

随后定义工具本体，继承Anthropic::BaseTool，通过input_schema挂载输入模型，并在call(input)方法中实现真正的业务逻辑：

class GetWeather < Anthropic::BaseTool doc "Get the current weather for a location" input_schema GetWeatherInput def call(input) "The weather in #{input.location} is sunny and 72°F." end end

从源码结构可以推断，Anthropic::BaseTool承担了三件事：把doc描述的字符串作为工具的description上报给模型；把input_schema声明的GetWeatherInput转换为工具的参数 JSON Schema；在模型请求使用该工具时调用call(input)并返回结果字符串。input是解析后的输入对象，可直接以input.location的形式访问参数。

3.3 发起一次带工具的对话

将工具实例放入tools:数组，调用 beta 命名空间下的tool_runner方法，并传入模型、max_tokens与消息列表：

client.beta.messages.tool_runner( model: :"{{OPUS_ID}}", max_tokens: 16000, tools: [GetWeather.new], messages: [{ role: "user", content: "What's the weather in San Francisco?" }] ).each_message do |message| puts message.content end

要点拆解：

• model: :"{{OPUS_ID}}"：使用 Symbol 形式指定模型，{{OPUS_ID}}为运行时插值占位符；
• tools: [GetWeather.new]：传入已实例化的工具对象，而非类本身；
• max_tokens: 16000：与 Ruby API 参考 中普通请求的max_tokens一致，表示生成上限；
• each_message迭代器：Tool Runner 会持续驱动整个循环，把每一轮产出的消息交给 block。最终消息的content中通常包含:text类型的文本块，即为模型基于工具结果给出的最终回答。

3.4 一个可运行的天气查询闭环

将上述片段组合起来，就是一个完整的「查天气」Agentic 应用。模型看到get_weather工具的 schema 后会生成tool_use请求，Tool Runner 自动执行GetWeather#call，把「sunny and 72°F」作为工具结果反馈给模型，模型最终生成自然语言回复。这一体验与仓库中其他语言的 Tool Runner 形态一致：例如 C# 参考 提供BetaToolRunner，PHP 参考 提供$client->beta->messages->toolRunner()，三个 SDK 都把「API 调用 → 工具执行 → 结果反馈」的循环封装为单一入口。

四、手动 Agentic 循环（Manual Loop）

当需要完全掌控每一步（例如需要审计工具参数、自定义重试策略、或工具执行有外部副作用需要人工确认）时，可以选择手动实现循环。关联文档明确指出：工具定义格式与 Agentic 循环模式请参阅共享概念文档，本文基于仓库中 Ruby API 参考 中关于内容块多态性的说明与 PHP 工具使用参考 的手动循环示例，给出 Ruby 语义下的对应实现模式。

4.1 理解响应内容块的多态性（手动循环的关键前提）

手动循环要求开发者自己遍历响应content。Ruby SDK 的message.content是一个多态块对象数组（TextBlock、ThinkingBlock、ToolUseBlock等），其.type是Symbol 而非字符串，这一点在 Ruby API 参考 中被特别强调：

• 比较类型时必须用block.type == :text而不是block.type == "text"；
• .text方法在非TextBlock条目上会抛出NoMethodError，因此必须先按类型分支再访问属性。

这直接决定了手动循环中识别tool_use块、提取工具名与输入参数的写法。

4.2 用原始 Hash 定义工具

与 Tool Runner 的面向对象方式不同，手动循环中工具可直接以 Hash 形式声明（Ruby SDK 全链路使用 snake_case 键名，这一点可从 Ruby API 参考 中output_config、task_budget、cache_control等参数名推断，并与 PHP 文档 明确记载的「camelCase 键自动映射到 API snake_case」形成对照）：

tools = [ { name: "get_weather", description: "Get the current weather in a given location", input_schema: { type: "object", properties: { location: { type: "string", description: "City and state" } }, required: ["location"] } } ]

4.3 循环主体：请求 → 执行 → 回传

messages = [{ role: "user", content: "What is the weather in SF?" }] message = client.messages.create( model: :"{{OPUS_ID}}", max_tokens: 16000, tools: tools, messages: messages ) while message.stop_reason == :tool_use tool_results = [] message.content.each do |block| next unless block.type == :tool_use result = execute_your_tool(block.name, block.input) tool_results << { type: "tool_result", tool_use_id: block.id, # 必须与 tool_use 块的 id 一一对应 content: result } end # 追加 assistant 回合（原样回传 content）与携带工具结果的 user 回合 messages << { role: "assistant", content: message.content } messages << { role: "user", content: tool_results } message = client.messages.create( model: :"{{OPUS_ID}}", max_tokens: 16000, tools: tools, messages: messages ) end # 循环结束后，输出最终文本 message.content.each do |block| puts block.text if block.type == :text end

该模式的关键约束：

1. tool_use_id必须一一对应：每个tool_result通过tool_use_id关联到对应的tool_use块，API 会拒绝缺少匹配结果的后续请求（这一约束在 C# 参考 中也有明确记载）；
2. assistant 回合必须原样回传：将模型的message.content直接放回消息序列，避免服务端因内容被篡改而报错；
3. 终止条件是stop_reason：当message.stop_reason不再是:tool_use时循环结束，此时content中通常包含最终文本块。

五、与工具使用相关的扩展能力

虽然关联文档本身只聚焦工具调用，但结合仓库中其他 Ruby 文档，可以在手动循环场景中进一步利用以下能力：

• 流式输出：需要流式呈现工具循环中间结果时，可参考 Ruby 流式参考，使用client.messages.stream(...)后通过stream.text.each { |text| print(text) }逐段消费文本；
• Beta 特性头：betas:参数仅在client.beta.messages.create上有效（非 beta 路径不可用），例如 Ruby API 参考 中的task-budgets-2026-03-13任务预算特性；
• 错误分类：工具调用失败时可通过rescue Anthropic::Errors::APIStatusError => e并读取e.type（如:rate_limit_error、:overloaded_error）进行程序化处理，见 Ruby API 参考。

六、版本与适用前提说明

• 本文示例中的{{OPUS_ID}}是 Claude Code 运行时插值模板变量，需替换为实际模型标识后才能运行；
• 关联文档对应ccVersion: "2.1.246"，仓库整体对应 Claude Code v2.1.288（见 README.md 的版本声明）；不同 Claude Code 版本可能调整模板细节，CHANGELOG.md 持续追踪各版本的系统提示词变化；
• client.beta.messages.tool_runner属于beta 能力，接口形态可能在正式发布时调整；手动循环则基于稳定的 Messages API，适合对稳定性要求更高的生产环境。

七、延伸阅读（仓库内参考文件）

• Ruby 工具使用参考（关联文档） —— Tool Runner Beta 与手动循环指引的原始出处
• Ruby Claude API 参考 —— 安装、客户端初始化、扩展思考、提示缓存、停止详情与 Beta 特性
• Ruby 流式参考 —— 流式文本处理
• C# 工具使用参考 —— 跨语言对照：BetaToolRunner与内容块重建规则
• PHP 工具使用参考 —— 跨语言对照：toolRunner()与完整手动循环实现
• README.md —— 仓库说明与系统提示词清单总览

• 文档
• 提示工程
• 人工智能