Ruby SDK

安装和配置 Anthropic Ruby SDK，支持 Sorbet 类型、流式辅助函数和连接池

Anthropic Ruby 库为任何 Ruby 3.2.0+ 应用程序提供对 Anthropic REST API 的便捷访问。它附带了完整的 Yard、RBS 和 RBI 类型定义和文档字符串。标准库的 net/http 用作 HTTP 传输，通过 connection_pool gem 实现连接池。

安装

使用 Bundler 将 gem 添加到应用程序的 Gemfile 中：

bundle add anthropic

要求

Ruby 3.2.0 或更高版本。

用法

require "anthropic"

anthropic = Anthropic::Client.new(
  api_key: ENV["ANTHROPIC_API_KEY"] # 这是默认值，可以省略
)

message = anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-4-7"
)

puts(message.content)

有关认证选项（包括 Workload Identity Federation），请参阅认证。

流式传输

SDK 提供使用 Server-Sent Events (SSE) 的流式响应支持。

require "anthropic"
anthropic = Anthropic::Client.new
stream = anthropic.messages.stream(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-4-7"
)

stream.each do |message|
  puts(message.type)
end

流式辅助函数

此库为流式消息提供了多种便利功能，例如：

require "anthropic"
anthropic = Anthropic::Client.new
stream = anthropic.messages.stream(
  max_tokens: 1024,
  messages: [{role: :user, content: "Say hello there!"}],
  model: :"claude-opus-4-7"
)

stream.text.each do |text|
  print(text)
end

使用 anthropic.messages.stream(...) 进行流式传输会暴露各种辅助函数，包括累积和 SDK 特定事件。

输入模式和工具调用

SDK 提供了辅助机制来为工具定义结构化数据类，并让 Claude 自动执行它们。有关工具使用模式（包括工具运行器）的详细文档，请参阅工具运行器 (SDK)。

require "anthropic"
anthropic = Anthropic::Client.new
class CalculatorInput < Anthropic::BaseModel
  required :lhs, Float
  required :rhs, Float
  required :operator, Anthropic::InputSchema::EnumOf[:+, :-, :*, :/]
end

class Calculator < Anthropic::BaseTool
  input_schema CalculatorInput

  def call(expr)
    expr.lhs.public_send(expr.operator, expr.rhs)
  end
end

# 自动处理工具执行循环
anthropic.beta.messages.tool_runner(
  model: "claude-opus-4-7",
  max_tokens: 1024,
  messages: [{role: "user", content: "What's 15 * 7?"}],
  tools: [Calculator.new]
).each_message { |message| puts message.content }

结构化输出

有关包含 Ruby 示例的完整结构化输出文档，请参阅结构化输出。

错误处理

当库无法连接到 API，或 API 返回非成功状态码（即 4xx 或 5xx 响应）时，会抛出 Anthropic::Errors::APIError 的子类：

require "anthropic"
anthropic = Anthropic::Client.new
begin
  message = anthropic.messages.create(
    max_tokens: 1024,
    messages: [{role: "user", content: "Hello, Claude"}],
    model: :"claude-opus-4-7"
  )
rescue Anthropic::Errors::APIConnectionError => e
  puts("The server could not be reached")
  puts(e.cause)  # 底层异常，可能在 `net/http` 中抛出
rescue Anthropic::Errors::RateLimitError => e
  puts("A 429 status code was received; we should back off a bit.")
rescue Anthropic::Errors::APIStatusError => e
  puts("Another non-200-range status code was received")
  puts(e.status)
end

错误代码如下：

重试

某些错误默认会自动重试 2 次，带有短暂的指数退避。

连接错误（例如，由于网络连接问题）、408 请求超时、409 冲突、429 速率限制、>=500 内部错误和超时默认都会重试。

你可以使用 max_retries 选项来配置或禁用此功能：

# 为所有请求配置默认值：
anthropic = Anthropic::Client.new(
  max_retries: 0 # 默认为 2
)

# 或者按请求配置：
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-4-7",
  request_options: {max_retries: 5}
)

超时

请求默认在 10 分钟后超时。你可以使用 timeout 选项配置此值：

# 为所有请求配置默认值：
anthropic = Anthropic::Client.new(
  timeout: 20 # 20 秒（默认为 10 分钟）
)

# 或者按请求配置：
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-4-7",
  request_options: {timeout: 5}
)

超时时会抛出 Anthropic::Errors::APITimeoutError。

请注意，超时的请求默认会重试。

分页

Claude API 中的列表方法是分页的。

此库为每个列表响应提供自动分页的迭代器，因此你无需手动请求连续的页面：

require "anthropic"
anthropic = Anthropic::Client.new
page = anthropic.messages.batches.list(limit: 20)

# 从页面获取单个项目。
batch = page.data[0]
puts(batch.id)

# 根据需要自动获取更多页面。
page.auto_paging_each do |batch|
  puts(batch.id)
end

或者，你可以使用 #next_page? 和 #next_page 方法进行更精细的页面控制。

require "anthropic"
anthropic = Anthropic::Client.new
page = anthropic.messages.batches.list(limit: 20)
loop do
  page.data&.each { |batch| puts(batch.id) }
  break unless page.next_page?
  page = page.next_page
end

文件上传

对应文件上传的请求参数可以作为原始内容、Pathname 实例、StringIO 等传递。

require "anthropic"
anthropic = Anthropic::Client.new
require "pathname"

# 使用 `Pathname` 发送文件名和/或将大文件分页到内存中：
file_metadata = anthropic.beta.files.upload(file: Pathname("/path/to/file"))

# 或者直接传递文件内容或 `StringIO`：
file_metadata = anthropic.beta.files.upload(file: File.read("/path/to/file"))

# 或者控制文件名和/或内容类型：
file = Anthropic::FilePart.new(File.read("/path/to/file"), filename: "/path/to/file", content_type: "...")
file_metadata = anthropic.beta.files.upload(file: file)

puts(file_metadata.id)

请注意，你也可以传递原始的 IO 描述符，但这会禁用重试，因为库无法确定描述符是文件还是管道（管道无法回退）。

Sorbet

此库提供了完整的 RBI 定义，不依赖 sorbet-runtime。

你可以这样提供类型安全的请求参数：

require "anthropic"
anthropic = Anthropic::Client.new
anthropic.messages.create(
  max_tokens: 1024,
  messages: [Anthropic::MessageParam.new(role: "user", content: "Hello, Claude")],
  model: :"claude-opus-4-7"
)

或者等效地：

require "anthropic"
anthropic = Anthropic::Client.new
# 哈希也可以用，但不是类型安全的：
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-4-7"
)

# 你也可以展开完整的 Params 类：
params = Anthropic::MessageCreateParams.new(
  max_tokens: 1024,
  messages: [Anthropic::MessageParam.new(role: "user", content: "Hello, Claude")],
  model: :"claude-opus-4-7"
)
anthropic.messages.create(**params)

枚举

由于此库不依赖 sorbet-runtime，它无法提供 T::Enum 实例。相反，SDK 提供"标记符号"，在运行时始终是原始值：

# :auto
puts(Anthropic::MessageCreateParams::ServiceTier::AUTO)

# 显示类型：`T.all(Anthropic::MessageCreateParams::ServiceTier, Symbol)`
T.reveal_type(Anthropic::MessageCreateParams::ServiceTier::AUTO)

枚举参数具有"宽松"类型，因此你可以传入枚举常量或其字面量值：

# 使用枚举常量保留标记类型信息：
anthropic.messages.create(
  service_tier: Anthropic::MessageCreateParams::ServiceTier::AUTO,
  # ...
)

# 字面量值也是允许的：
anthropic.messages.create(
  service_tier: :auto,
  # ...
)

BaseModel

所有参数和响应对象都继承自 Anthropic::Internal::Type::BaseModel，它提供了多种便利功能，包括：

1. 所有字段（包括未知字段）都可以使用 obj[:prop] 语法访问，并可以使用 obj => {prop: prop} 或模式匹配语法进行解构。

2. 结构等价性用于相等性比较；如果两个 API 调用返回相同的值，使用 == 比较响应将返回 true。

3. 实例和类本身都可以格式化打印。

4. 辅助方法如 #to_h、#deep_to_h、#to_json 和 #to_yaml。

并发和连接池

Anthropic::Client 实例是线程安全的，但只有在没有进行中的 HTTP 请求时才是 fork 安全的。

每个 Anthropic::Client 实例都有自己的 HTTP 连接池，默认大小为 99。因此，建议在大多数设置中每个应用程序只创建一次客户端。

当连接池中的所有可用连接都被签出时，请求会等待新连接变为可用，排队时间计入请求超时。

除非另有说明，SDK 中的其他类没有保护其底层数据结构的锁。

发送自定义或未文档化的请求

未文档化的属性

你可以向任何端点发送未文档化的参数，并读取未文档化的响应属性，如下所示：

require "anthropic"
anthropic = Anthropic::Client.new
value = "example"
message =
  anthropic.messages.create(
    max_tokens: 1024,
    messages: [{role: "user", content: "Hello, Claude"}],
    model: :"claude-opus-4-7",
    request_options: {
      extra_query: {my_query_parameter: value},
      extra_body: {my_body_parameter: value},
      extra_headers: {"my-header": value}
    }
  )

puts(message[:my_undocumented_property])

未文档化的请求参数

如果你想显式发送额外参数，可以在发出请求时使用 request_options: 参数下的 extra_query、extra_body 和 extra_headers，如上面的示例所示。

未文档化的端点

要在保留认证、重试等好处的同时向未文档化的端点发送请求，你可以使用 anthropic.request 发送请求，如下所示：

response = anthropic.request(
  method: :post,
  path: '/undocumented/endpoint',
  query: {"dog": "woof"},
  headers: {"useful-header": "interesting-value"},
  body: {"hello": "world"}
)

平台集成

Ruby SDK 支持以下平台：

• Bedrock： Anthropic::BedrockMantleClient，或 Anthropic::BedrockClient 用于 bedrock-runtime 路径。Anthropic::BedrockMantleClient 需要 aws-sdk-core gem；Anthropic::BedrockClient 需要 aws-sdk-bedrockruntime gem。
• Vertex AI： Anthropic::VertexClient。需要 googleauth gem。
• Foundry： Ruby SDK 目前不支持。有关支持的 SDK，请参阅 Claude in Microsoft Foundry。
• Claude Platform on AWS： 主 anthropic gem 的一部分（需要 aws-sdk-core gem）。提供 Anthropic::AWSClient。向构造函数传递 workspace_id: 或设置 ANTHROPIC_AWS_WORKSPACE_ID 环境变量（参见工作区）。目前处于测试阶段。

新项目请使用 Anthropic::BedrockMantleClient；Anthropic::BedrockClient 保留给使用 Bedrock InvokeModel API 的现有应用程序。

语义化版本控制

此包遵循 SemVer 约定。由于库处于初始开发阶段且主版本号为 0，API 可能随时发生变化。

此包将（非运行时）*.rbi 和 *.rbs 类型定义的改进视为非破坏性变更。

附加资源

• GitHub 仓库
• YARD 文档
• API 参考
• 流式传输 Messages