Providers · 03

Anthropic Provider

The Anthropic provider connects to Claude models via the Anthropic API.

Configuration

Configure your Anthropic API key:

Riffer.configure do |config|
  config.anthropic.api_key = ENV['ANTHROPIC_API_KEY']
end

When config.anthropic.api_key is unset, the provider reads ANTHROPIC_API_KEY; with neither set it raises Riffer::ArgumentError. Set config.anthropic.base_url (or ANTHROPIC_BASE_URL) to send requests somewhere other than https://api.anthropic.com, such as a gateway or proxy.

Riffer reads no other ANTHROPIC_* variables. The anthropic gem also read ANTHROPIC_AUTH_TOKEN and ANTHROPIC_CUSTOM_HEADERS; riffer does not. The key is already sent as Authorization: Bearer, and custom headers go in the client’s headers: (see HTTP Client).

HTTP Client

The provider needs no Anthropic gem. Riffer ships its own Messages API transport, Riffer::Providers::Anthropic::Client, built on Riffer::HTTP::Client. The provider builds one from the configured credentials by default. To change timeouts, add retries or go through a proxy, build your own and assign it to config.anthropic.client:

Riffer.configure do |config|
  config.anthropic.client = Riffer::Providers::Anthropic::Client.new(
    api_key: ENV['ANTHROPIC_API_KEY'],
    connection: Faraday.new(request: { open_timeout: 10, read_timeout: 120 })
  )
end
Option Default Description
api_key required Sent as Authorization: Bearer <api_key>
base_url https://api.anthropic.com API origin; requests go to <base_url>/v1/messages
headers {} Sent on every request; replaces riffer’s headers of the same name
connection Faraday defaults, 10s open / 600s read Your own Faraday::Connection; see Connections

Timeouts, retries, proxies, beta headers and errors are covered in Configuration → Connections. An API error becomes a Riffer::APIError whose message carries the Anthropic error type, e.g. Anthropic API error (401): authentication_error: Invalid bearer token. No requests are retried unless your connection adds retries.

The anthropic-version header is pinned to 2026-10-21. To send another version, pass it in headers::

Riffer::Providers::Anthropic::Client.new(
  api_key: ENV['ANTHROPIC_API_KEY'],
  headers: {'anthropic-version' => '2023-06-01'}
)

Version 2026-10-21 removed temperature, top_p and top_k; sending any of them returns a 400. Pin 2023-06-01 to keep using them. See Anthropic’s API versions for the other changes.

The setting accepts a client instance or a no-argument Proc, resolved on every LLM call — see Configuration → Provider Clients. An Anthropic::Client from the anthropic gem is not accepted and raises Riffer::ArgumentError.

Supported Models

Use Anthropic model IDs in the anthropic/model format:

model 'anthropic/claude-haiku-4-5-20251001'
model 'anthropic/claude-sonnet-4-5-20250929'
model 'anthropic/claude-opus-4-5-20251101'

Model Options

max_tokens

Maximum tokens in response:

model_options max_tokens: 4096

thinking

Enable extended thinking (reasoning) for supported models. Pass the thinking configuration hash directly as Anthropic expects:

# Enable with budget tokens
model_options thinking: {type: "enabled", budget_tokens: 10000}

Enable server-side web search using Anthropic’s web_search_20250305 tool. Pass true to use defaults or a hash to merge with the tool definition:

# Enable with defaults
model_options web_search: true

# With custom configuration
model_options web_search: {max_uses: 3}

Example

Riffer.configure do |config|
  config.anthropic.api_key = ENV['ANTHROPIC_API_KEY']
end

class AssistantAgent < Riffer::Agent
  model 'anthropic/claude-haiku-4-5-20251001'
  instructions 'You are a helpful assistant.'
  model_options temperature: 0.7, max_tokens: 4096
end

agent = AssistantAgent.new
puts agent.generate("Explain quantum computing")

Streaming

agent.stream("Tell me about Claude models").each do |event|
  case event
  when Riffer::StreamEvents::TextDelta
    print event.content
  when Riffer::StreamEvents::TextDone
    puts "\n[Complete]"
  when Riffer::StreamEvents::ReasoningDelta
    print "[Thinking] #{event.content}"
  when Riffer::StreamEvents::ReasoningDone
    puts "\n[Thinking Complete]"
  when Riffer::StreamEvents::ToolCallDone
    puts "[Tool: #{event.name}]"
  end
end

Tool Calling

Anthropic provider converts tools to the Anthropic tool format:

class WeatherTool < Riffer::Tool
  description "Gets the current weather for a location"

  params do
    required :city, :string, description: "The city name"
    optional :unit, :string, description: "Temperature unit (celsius or fahrenheit)"
  end

  def call(context:, city:, unit: "celsius")
    # Implementation
    text("It's 22 degrees #{unit} in #{city}")
  end
end

class WeatherAgent < Riffer::Agent
  model 'anthropic/claude-haiku-4-5-20251001'
  uses_tools [WeatherTool]
end

Extended Thinking

Extended thinking enables Claude to reason through complex problems before responding. This is available on supported models (Claude 3.7+).

class ReasoningAgent < Riffer::Agent
  model 'anthropic/claude-haiku-4-5-20251001'
  model_options thinking: {type: "enabled", budget_tokens: 10000}
end

The agent-level reasoning setting defaults to adaptive thinking at the level’s effort (thinking: {type: "adaptive"}, output_config: {effort: "low"}), and :off sends thinking: {type: "disabled"}. Claude 4.5 and earlier need a budget_tokens mapping in a catalog entry instead.

When streaming with extended thinking enabled, you’ll receive ReasoningDelta events containing the model’s thought process, followed by a ReasoningDone event when thinking completes:

agent.stream("Solve this complex math problem").each do |event|
  case event
  when Riffer::StreamEvents::ReasoningDelta
    # Model's internal reasoning
    print "[Thinking] #{event.content}"
  when Riffer::StreamEvents::ReasoningDone
    puts "\n[Thinking complete]"
  when Riffer::StreamEvents::TextDelta
    # Final response
    print event.content
  end
end

The reasoning is kept on the assistant message as reasoning parts, whether you call generate or stream. Read it with response.reasoning, or as plain text with reasoning_text on the message. Each thinking block becomes a :text part carrying its signature, and each redacted_thinking block becomes an :encrypted part whose data is the block’s opaque payload. reasoning_text leaves the redacted parts out, since they have no readable text. Every part is tagged format: "anthropic-messages-v1" (Riffer::Providers::Anthropic::REASONING_FORMAT).

Reasoning Replay

Riffer sends every earlier turn back to Anthropic as the API returned it: the thinking, redacted_thinking, text, web search and tool_use blocks, in their original order and unchanged (see Messages — Parts). Order matters because Claude signs each thinking block over everything before it, including earlier blocks of the same turn. A turn sent back in a different order loses that reasoning, or is rejected with a 400 on accounts that enforce the binding. For tool calls, sending the reasoning back is required: when thinking is enabled, Claude needs its earlier thinking blocks back to carry on after a tool result. You don’t have to do anything; it happens as long as the assistant messages stay in the history.

If you persist sessions, to_h keeps the web search results and the turn’s block order (see Messages — Parts). Dropping the reasoning loses the model’s earlier thinking, and a tool-calling turn with thinking enabled may be rejected.

If you change a turn’s text, drop that turn’s reasoning yourself; see Editing a turn.

Only reasoning that this provider produced is sent back to Anthropic. A conversation that switches providers midway still works: reasoning from other providers (including OpenRouter’s anthropic-claude-v1 parts) is kept on the messages but left out of Anthropic requests.

Web search allows Claude to search the web for up-to-date information. When enabled, the provider injects the web_search_20250305 server tool into the request.

class SearchAgent < Riffer::Agent
  model 'anthropic/claude-haiku-4-5-20251001'
  model_options web_search: true
end

agent = SearchAgent.new
agent.stream("What happened in tech news today?").each do |event|
  case event
  when Riffer::StreamEvents::WebSearchStatus
    puts "[search: #{event.status}]"
    puts "  query: #{event.query}" if event.query
  when Riffer::StreamEvents::WebSearchDone
    puts "[search complete: #{event.query}]"
    event.sources.each { |s| puts "  - #{s[:title]}: #{s[:url]}" }
  when Riffer::StreamEvents::TextDelta
    print event.content
  end
end

Anthropic emits sources with title and url on the WebSearchDone event.

Each server_tool_use block and its result block (web_search_tool_result, or code_execution_tool_result when a newer web search version runs the search from code execution) is kept on the assistant message as a ServerToolPart (see Messages — Parts), and a streamed one also arrives as a ServerToolDone event. With generate, text blocks with citations keep their block too; a streamed turn keeps the text without its citations. Later turns send them back in place, so Claude reuses the results instead of searching again.

Paused turns

When a server tool loop reaches its iteration limit, Anthropic stops with stop_reason: "pause_turn". Riffer sends the paused content back unchanged as the last message and continues the turn, up to 8 times per call, for generate_text and stream_text alike. If the response names a container, its id goes with the next request, so the turn keeps the same container and its files. You get one assistant message: every response’s parts in order, the summed token usage and the last response’s finish reason. A stream yields one TextDone, FinishReasonDone and TokenUsageDone for the whole turn.

A turn still paused after 8 continuations ends with finish reason :other (finish_reason_raw is "pause_turn"). Its last server tool call may have no result, and Anthropic rejects a request that adds a user message after it. Call generate or stream with no prompt to send the turn back and let Claude carry on.

A turn that stops on max_tokens is not continued.

Deferred Tools

The provider supports deferred tools through the Messages API’s own deferred loading, with no beta header and no tool search tool:

class Assistant < Riffer::Agent
  model 'anthropic/claude-haiku-5-5'
  instructions "If you need a tool you don't have, use find_tools."

  uses_tools [FindTools]
  deferred_tools [ListEvents, CreateEvent]
end
  • Every deferred tool is sent on every request with defer_loading: true, after the agent’s other tools, whether it has been loaded or not. The tools array stays the same for the whole conversation, so a load doesn’t break the prompt cache.
  • A tool result that loads tools is sent as tool_reference blocks only, one per loaded tool. From then on Claude sees those tools’ definitions and calls them by their own names. A load that names a tool the agent no longer defers, for example in a restored history, leaves that tool out, since the API rejects a reference to a tool that isn’t in the request.

Things to know:

  • At least one tool in the request must not be deferred, or the API returns a 400 (All tools cannot be deferred). An agent needs a tool in uses_tools to load its deferred tools anyway.
  • A deferred tool can’t carry cache_control (400). Riffer never sets it on a tool; the top-level model_options cache_control: {type: "ephemeral"} works with deferred tools.
  • Deferred loading needs Claude Haiku 4.5, Sonnet 4.5, Opus 4.5 or a later model. An older model gets the API’s own error.

With the gateway strategy, deferred_tools [...], strategy: :gateway, riffer sends the gateway instead of loading them natively.

Message Format

The provider converts Riffer messages to Anthropic format:

Riffer Message Anthropic Format
System Added to system array as {type: "text", text: ...}
User {role: "user", content: "..."}
Assistant {role: "assistant", content: [...]}, one block per part, in part order
Tool {role: "user", content: [{type: "tool_result", ...}]}

Direct Provider Usage

provider = Riffer::Providers::Anthropic.new

response = provider.generate_text(
  prompt: "Hello!",
  model: "claude-haiku-4-5-20251001",
  temperature: 0.7
)

puts response.content

With extended thinking:

response = provider.generate_text(
  prompt: "Explain step by step how to solve a Rubik's cube",
  model: "claude-haiku-4-5-20251001",
  thinking: { type: "enabled", budget_tokens: 10000 }
)

puts response.content