使用 Anthropic Ruby SDK 构建 Claude API 应用：安装、流式响应与 Tool Runner 实战指南

AI 技能AI 插件【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,445 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址https://gitcode.com/gh_mirrors/an/agentic-awesome-skills点击查看免费下载本指南围绕 agentic-awesome-skills 仓库中 claude-api Ruby 语言指南 展开系统讲解如何用 Ruby 官方 SDKanthropicgem接入 Claude Messages API从 gem 安装、客户端初始化、基础消息请求与流式输出到基于BaseTool/BaseModel的 Tool RunnerBeta自动工具循环与手动 Agentic Loop。读完你可以在自己的 Ruby 项目中完整落地「模型调用 工具调用 流式响应」的 Claude 应用骨架并掌握模型 ID 选择、错误处理与结构化输出等配套能力。背景Ruby 在 Claude API 生态中的定位在继续之前先明确 Ruby SDK 的能力边界。根据本仓库 SKILL.md 中的「Language-Specific Feature Support」表格语言Tool RunnerAgent SDKPythonYes (beta)YesTypeScriptYes (beta)YesJavaYes (beta)NoGoYes (beta)NoRubyYes (beta)NocURLN/AN/AC#NoNoPHPNoNo也就是说Ruby 官方 SDK 完整支持 Claude API 与 beta 阶段的工具运行器client.beta.messages.tool_runner()但Agent SDK面向文件/Web/终端内置工具的开箱即用型 Agent尚未对 Ruby 开放。如果你需要 Agent SDK 的能力本仓库提供了 Python Agent SDK 文档 与 TypeScript Agent SDK 文档 作为参考。若你的应用只需要单次 LLM 调用或由代码编排的多步流程Ruby Claude API 完全够用。安装 gem安装 Anthropic 官方 Ruby SDKgem install anthropic安装完成后在代码中引入require anthropic客户端初始化SDK 支持两种初始化方式默认读取环境变量或显式传入 API Key。# 默认读取 ANTHROPIC_API_KEY 环境变量 client Anthropic::Client.new # 显式传入 API Key client Anthropic::Client.new(api_key: your-api-key)安全提示参考 shared/error-codes.md 中的常见错误对照表把 API Key 硬编码进源码是 401 类问题泄露 Key的头号诱因。生产环境请始终使用ANTHROPIC_API_KEY环境变量。基础消息请求Messages API 是 Claude 的唯一入口POST /v1/messages工具与输出约束都是该端点的能力而非独立 API。最小可用的 Ruby 请求如下message client.messages.create( model: :claude-opus-4-6, max_tokens: 1024, messages: [ { role: user, content: What is the capital of France? } ] ) puts message.content.first.text模型 ID 的选择上例使用符号:claude-opus-4-6。根据本仓库 shared/models.md 的模型目录当前推荐模型及别名如下别名可直接使用无需拼日期后缀模型别名直接使用上下文窗口最大输出Claude Opus 4.6claude-opus-4-6200K1M beta128KClaude Sonnet 4.6claude-sonnet-4-6200K1M beta64KClaude Haiku 4.5claude-haiku-4-5200K64KSKILL.md 明确要求除非用户点名其他模型一律默认使用claude-opus-4-6且必须使用表格中的精确 ID 字符串不要自行拼装日期后缀例如不要写claude-sonnet-4-5-20250514。若用户要求旧型号请到 shared/models.md 查询完整 ID。流式响应Streaming流式输出让 Token 边生成边到达适合 Chat UI 与长响应场景。SKILL.md 特别提示任何可能涉及长输入、长输出或高max_tokens的请求都应默认走流式以避免请求超时。Ruby 中通过client.messages.stream开启stream client.messages.stream( model: :claude-opus-4-6, max_tokens: 1024, messages: [{ role: user, content: Write a haiku }] ) stream.text.each { |text| print(text) }流式事件模型Ruby SDK 的.stream与 Python/TypeScript SDK 遵循相同的流式事件协议。参考 python/claude-api/streaming.md 的事件类型表可帮助你理解底层数据流事件类型说明触发时机message_start消息元数据开始时一次content_block_start新内容块开始text/tool_use 块开始时content_block_delta增量内容更新每个 token/块content_block_stop内容块完成块结束时message_delta消息级更新含stop_reason、usagemessage_stop消息完成结束时一次流式 思考块ThinkingOpus 4.6 / Sonnet 4.6 推荐使用自适应思考thinking: {type: adaptive}旧模型的budget_tokens在这两个模型上已废弃。流式响应中可能交错出现text与thinking两种内容块需要分别处理stream client.messages.stream( model: :claude-opus-4-6, max_tokens: 16000, thinking: { type: adaptive }, messages: [{ role: user, content: Analyze this problem }] ) # 根据事件类型区分 thinking / text 内容 stream.each do |event| case event.type when content_block_start puts event.content_block.type thinking ? \n[Thinking...] : \n[Response:] when content_block_delta case event.delta.type when thinking_delta then print(event.delta.thinking) when text_delta then print(event.delta.text) end end end流式最佳实践同样适用于 Ruby默认流式即使不关心逐 token 展示也建议用流式 聚合最终消息的方式拿到完整响应可规避大max_tokens下的 HTTP 超时SKILL.md主动 flush逐 token 打印时记得flush保证即时可见记录用量message_delta事件中的 usage 可统计输出 Token处理中断流被截断时可能出现不完整内容需有兜底逻辑。工具使用Tool UseRuby SDK 支持两种工具调用方式raw JSON Schema 定义手动循环用与Beta Tool Runner自动执行工具。理解工具调用的通用概念前建议通读 shared/tool-use-concepts.md —— 它定义了工具数据结构、tool_choice选项与 Agentic Loop 模式是各语言共用的理论基础。工具定义结构概念基础无论用哪种方式工具在 API 层面都对应一个包含name、description、input_schemaJSON Schema的结构shared/tool-use-concepts.md{ name: get_weather, description: Get current weather for a location, input_schema: { type: object, properties: { location: { type: string, description: City and state, e.g., San Francisco, CA }, unit: { type: string, enum: [celsius, fahrenheit], description: Temperature unit } }, required: [location] } }工具定义最佳实践shared/tool-use-concepts.md使用清晰、描述性的名称如get_weather、search_database、send_email撰写详细描述——Claude 依赖描述来决定何时使用工具为每个属性补充描述固定取值集合用enum只在真正必填时加入required其余参数给默认值。Tool RunnerBeta—— 自动工具循环Ruby SDK 通过BaseModel定义输入结构、BaseTool定义工具行为然后交给client.beta.messages.tool_runner()自动完成「调用 API → 检测工具请求 → 执行函数 → 回传结果 → 循环直到结束」的整个 Agentic Loopclass GetWeatherInput Anthropic::BaseModel required :location, String, doc: City and state, e.g. San Francisco, CA end 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 client.beta.messages.tool_runner( model: :claude-opus-4-6, max_tokens: 1024, tools: [GetWeather.new], messages: [{ role: user, content: Whats the weather in San Francisco? }] ).each_message do |message| puts message.content end要点拆解BaseModel用required :field, Type, doc: ...声明工具输入字段及其类型、文档字符串SDK 自动生成 JSON SchemaBaseTooldoc描述工具用途input_schema绑定输入模型call(input)是工具的实际执行体返回值会作为tool_result回传给 Claude.each_message逐条消费循环产出的消息当 Claude 不再请求工具时循环自动终止。与其它语言 Tool Runner 的对照Ruby 的BaseTool/BaseModel模式与其它语言 SDK 的自动 schema 生成思路一致shared/tool-use-concepts.mdPython 用beta_tool装饰器、TypeScript 用betaZodTool Zod、Java 用注解类、Go 用jsonschemastruct tag BetaToolRunner。Go 的参考实现在 go/claude-api.md可以看到RunToCompletion()/All()/NextMessage()等更细粒度的迭代控制Ruby 的each_message与其All()迭代器语义类似。Tool Runner 的安全注意事项shared/tool-use-concepts.md 明确警告Tool Runner 会在 Claude 请求时自动执行你的工具函数。对于有副作用的工具发邮件、改数据库、金融交易必须在工具函数内部校验输入并考虑对破坏性操作增加确认环节如果需要「人在环」human-in-the-loop审批应改用下面的手动循环。手动 Agentic LoopManual Loop当需要细粒度控制自定义日志、条件执行、人工审批闸门时使用client.messages.create手动编排循环。通用模式shared/tool-use-concepts.md调用 API 拿到响应若stop_reason end_turn循环结束否则提取响应中的tool_use块执行对应工具必须把完整的response.content含tool_use块追加回消息历史每个tool_result必须携带与tool_use块匹配的tool_use_id循环。处理工具结果时的关键规则shared/tool-use-concepts.md工具失败在tool_result中设置is_error: true并给出有信息量的错误信息Claude 会据此换策略或追问多工具并行Claude 可能在一个响应中请求多个工具需全部执行完后在单条 user 消息里一次性回传所有结果。Tool Choice控制 Claude 何时使用工具tool_choice参数控制工具调用策略shared/tool-use-concepts.md| 值 | 行为 | | -- | ---- | |{type: auto}| Claude 自行决定是否用工具默认 | |{type: any}| Claude 必须至少调用一个工具 | |{type: tool, name: ...}| Claude 必须使用指定工具 | |{type: none}| Claude 禁止使用工具 |任意tool_choice值还可附带disable_parallel_tool_use: true强制每个响应最多一个工具调用默认允许并行多工具。配套能力与排错错误处理Claude API 的 HTTP 错误码、可重试性与成因对照见 shared/error-codes.md状态码错误类型可重试常见原因400invalid_request_error否请求格式/参数非法401authentication_error否API Key 缺失或无效403permission_error否Key 缺少权限404not_found_error否端点或模型 ID 错误413request_too_large否请求超限429rate_limit_error是请求过多500api_error是Anthropic 服务故障529overloaded_error是API 临时过载几个高频踩坑点shared/error-codes.md模型 ID 写错如claude-sonnet-4.6写成点号→ 404务必用别名claude-sonnet-4-6首条消息必须是user且 user/assistant 必须交替 → 否则 400budget_tokens必须小于max_tokens→ 否则 400该参数在 Opus 4.6 / Sonnet 4.6 上已废弃改用自适应思考429/5xx 由 SDK 自动指数退避重试默认max_retries2。思考与 Effort 参数速查SKILL.md 给出的当前约定Opus 4.6 / Sonnet 4.6使用thinking: {type: adaptive}无需budget_tokens已废弃且自动启用交错思考无需 beta 头Effort 参数GAoutput_config: {effort: low|medium|high|max}控制思考深度与 Token 开销默认highmax仅 Opus 4.6适用于 Sonnet 4.6 / Opus 4.5可与自适应思考组合以优化成本质量比旧模型仅当用户明确要求thinking: {type: enabled, budget_tokens: N}且budget_tokens max_tokens。结构化输出Structured Outputs若需要保证输出可解析可用output_config: {format: {...}}约束 JSON SchemaSKILL.md。支持模型为 Opus 4.6 / Sonnet 4.6 / Haiku 4.5。注意 JSON Schema 限制所有对象必须additionalProperties: false不支持递归 schema、数值/字符串约束minimum、maxLength 等与复杂数组约束shared/tool-use-concepts.md。服务器端工具与更多能力除用户自定义工具外Claude API 还提供服务器端工具代码执行code_execution_20260120、Web 搜索/抓取web_search_20260209/web_fetch_20260209、记忆工具memory_20250818等。它们运行在 Anthropic 基础设施上只需在tools数组中声明即可shared/tool-use-concepts.md。当服务器端工具的内部采样循环达到默认 10 次迭代上限时响应会带stop_reason: pause_turn此时应把用户消息与 assistant 的完整 content 原样重发以恢复执行不要额外添加 Continue. 之类的用户消息shared/tool-use-concepts.md。在 Ruby 手动循环中同样需要处理pause_turn分支。常见陷阱速查结合 SKILL.md 与 Ruby 场景整理不要截断输入内容超长时与用户讨论分块/摘要方案而不是静默截断Opus 4.6 移除预填充assistant 消息预填充返回 400改用output_config.format或 system prompt 控制输出格式128K 输出Opus 4.6 支持最高 128Kmax_tokens但大输出必须走流式避免 HTTP 超时工具输入 JSON 解析Opus 4.6 的工具input序列化转义可能不同Unicode、斜杠等务必用JSON.parse解析不要对原始串做字符串匹配不要重造 SDK 轮子优先使用 SDK 的高层帮助方法与类型化异常类而非自行封装 Promise/字符串匹配错误信息语言识别在 Ruby 项目*.rb、Gemfile中自动匹配到本文档多语言项目需确认当前文件归属SKILL.md。延伸阅读仓库内SKILL.md — 能力总览、默认模型与思考约定、阅读路线图shared/tool-use-concepts.md — 工具定义、tool_choice、服务器端工具、结构化输出的完整概念shared/models.md — 当前/旧版/退役模型 ID 目录shared/error-codes.md — HTTP 错误码、成因与修复python/claude-api/tool-use.md 与 python/claude-api/streaming.md — Python 视角的 Tool Runner/手动循环与流式事件处理可与 Ruby 对照理解go/claude-api.md — Go SDK 的BetaToolRunner迭代控制参考shared/live-sources.md — 官方最新文档的 WebFetch 地址清单当需要「最新」信息时使用赞分享AI 技能AI 插件【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,445 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址https://gitcode.com/gh_mirrors/an/agentic-awesome-skills点击查看免费下载相关推荐小爱音箱接入 ChatGPTMiGPT 部署完整新手指南10 分钟跑通小爱音箱接入 ChatGPTMiGPT 部署完整新手指南10 分钟跑通 MiGPT 把普通小爱音箱接上 ChatGPT 和豆包让你开口提问、它开口回答。这AI 技能AI 插件Agent Zero 外部消息 API 全解析api_message 端点的调用契约、实现原理与实战指南Agent Zero 外部消息 API 全解析api_message 端点的调用契约、实现原理与实战指南 Agent Zero 框架为外部应用提供了一套 HTAI 技能AI 插件Vision Agents 中的 Anthropic Claude 插件流式响应、函数调用与对话记忆实战指南Vision Agents 中的 Anthropic Claude 插件流式响应、函数调用与对话记忆实战指南 导读 本文聚焦 Vision Agents 框架Agent 框架音视频计算机视觉上一篇MLflow Agent 自动埋点全解析instrument.md 任务提示模板与 mlflow agent setup 工作流下一篇PostHog 查询性能优化实战PostgreSQL 与 ClickHouse 双引擎的规模化调优指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考