Anthropic Ruby SDK

Structured outputs are compatible with streaming. While you can stream the raw text chunks as they arrive, the fully parsed model instance is only available once the stream is complete. You can access the final parsed object via stream.accumulated_message.parsed_output.

stream = anthropic.messages.stream(
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{role: "user", content: "give me some famous numbers"}],
  output_config: {format: Output}
)

# Stream the raw text as it arrives
stream.text.each { |text| print(text) }

# Get the parsed output from the accumulated message after completion
stream.accumulated_message.parsed_output

You can define the expected structure of Claude's response by subclassing Anthropic::BaseModel. This allows you to specify required and optional fields with specific types, documentation strings, and constraints like min_length or max_length.

Use these models in the output_config parameter of the messages.create method.

class FamousNumber < Anthropic::BaseModel
  required :value, Float
  optional :reason, String, doc: "why is this number mathematically significant?"
end

class Output < Anthropic::BaseModel
  doc "some famous numbers"

  required :numbers, Anthropic::ArrayOf[FamousNumber], min_length: 3, max_length: 5
end

message = anthropic.messages.create(
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{role: "user", content: "give me some famous numbers"}],
  output_config: {format: Output}
)

To use the Claude SDK in your Ruby application, add the anthropic gem to your Gemfile. It is recommended to use the version constraint matching your current environment.

gem "anthropic", "~> 1.59.0"

To interact with Claude, initialize an Anthropic::Client and use the messages.create method. By default, the client looks for your API key in the ANTHROPIC_API_KEY environment variable, so you can omit the api_key argument if it is set.

require "bundler/setup"
require "anthropic"

anthropic = Anthropic::Client.new(
  api_key: ENV["ANTHROPIC_API_KEY"] # This is the default and can be omitted
)

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

puts(message.content)

The output_config parameter controls how Claude formats its response. It accepts two formats:

1. BaseModel Class: Pass a subclass of Anthropic::BaseModel directly to use the helper's validation and parsing.
2. Raw JSON Schema: Pass a hash specifying the schema type: {format: {type: :json_schema, schema: {...}}}.

When using OIDC_FEDERATION authentication, you must provide an identity token. The SDK supports two primary sources for this token via the identity_token configuration key:

1. File: Specify a path to a file containing the token.
   • Configuration shape: { identity_token: { source: 'file', path: '/path/to/token' } } or simply { identity_token: '/path/to/token' }.
2. Environment Variable: Specify the name of an environment variable that contains the token.
   • Configuration shape: { identity_token: { source: 'env', value: 'ENV_VAR_NAME' } }.

Required Fields for OIDC Federation:

• authentication.type: Must be OIDC_FEDERATION.
• authentication.federation_rule_id: The ID of the federation rule.
• organization_id: The top-level organization ID.
• identity_token: One of the sources described above.

The SDK resolves credentials using a tiered approach to allow for both local development (via env vars) and production environments (via federation/profiles).

Precedence Order (Highest to Lowest):

1. Explicit Constructor Arguments: api_key, auth_token, credentials, or config.
2. Environment Variables: ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN.
3. Profile Selection: ANTHROPIC_PROFILE.
4. Direct Env-var Federation: ANTHROPIC_IDENTITY_TOKEN[_FILE], ANTHROPIC_FEDERATION_RULE_ID, and ANTHROPIC_ORGANIZATION_ID.
5. Disk-based Profiles: The active profile from disk (e.g., default).

Important: If you provide a static credential in step 1 or 2, the SDK will skip steps 3-5 entirely. This is intended to prevent accidental credential leakage or unexpected behavior when a developer explicitly defines a key.

To use the Bedrock client, you must include the aws-sdk-bedrockruntime gem in your project.

If using Bundler, add this to your Gemfile:

gem "aws-sdk-bedrockruntime"

Then run:

bundle install

If not using Bundler, run:

gem install aws-sdk-bedrockruntime

The Anthropic::Helpers::Tools::Mcp module provides helpers to convert types returned by the mcp gem into the shapes required by the Anthropic Beta Messages API. This allows you to use MCP tools, messages, and resources directly with the Anthropic SDK without writing manual glue code.

Requirement: The mcp gem is an optional dependency. You must install it separately:

gem install mcp

require "mcp"
require "anthropic"

transport  = MCP::Client::HTTP.new(url: "https://example.com/mcp")
mcp_client = MCP::Client.new(transport: transport)
anthropic  = Anthropic::Client.new

runner = anthropic.beta.messages.tool_runner(
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  messages: [{role: "user", content: "Use the available tools"}],
  tools: Anthropic::Mcp.tools(mcp_client.tools, mcp_client)
)
runner.run_until_finished