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}
web_search
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
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. Thetoolsarray 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_referenceblocks 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 inuses_toolsto load its deferred tools anyway. - A deferred tool can’t carry
cache_control(400). Riffer never sets it on a tool; the top-levelmodel_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