Configuration

Riffer uses a centralized configuration system for provider credentials and settings.

Global Configuration

Use Riffer.configure to set up provider credentials:

Riffer.configure do |config|
  config.openai.api_key = ENV['OPENAI_API_KEY']
  config.amazon_bedrock.region = 'us-east-1'
  config.amazon_bedrock.api_token = ENV['BEDROCK_API_TOKEN']
  config.anthropic.api_key = ENV['ANTHROPIC_API_KEY']
end

Accessing Configuration

Access the current configuration via Riffer.config:

Riffer.config.openai.api_key
# => "sk-..."

Riffer.config.amazon_bedrock.region
# => "us-east-1"

Riffer.config.anthropic.api_key
# => "sk-ant-..."

Provider-Specific Configuration

For provider credentials and setup, see the individual Provider guides.

MCP (Model Context Protocol)

Optional settings for MCP server integrations:

Riffer.configure do |config|
  config.mcp.credentials = lambda do |manifest:, matched_tags:, context:|
    {"Authorization" => "Bearer #{token_for(context)}"}
  end
end

See MCP for registration, tags, and agent use_mcp.

Tool Runtime (Experimental)

Warning: This feature is experimental and may be removed or changed without warning in a future release.

Configure the default tool runtime for all agents:

Riffer.configure do |config|
  config.tool_runtime = Riffer::Tools::Runtime::Threaded
end

Per-agent configuration overrides this global default. See Advanced Tool Configuration — Tool Runtime for details.

Skills

Skills-related global configuration lives under config.skills.

Default activation tool

Override the tool the LLM calls to activate a skill. Defaults to Riffer::Skills::ActivateTool:

Riffer.configure do |config|
  config.skills.default_activate_tool = MyCustomActivateTool
end

Per-agent override is available inside the skills block via activate_tool MyCustomActivateTool. See Skills — Custom Activation Tool.

Default backend

Set an app-wide default skills backend. Used by any agent that declares a skills block without specifying its own backend:

Riffer.configure do |config|
  config.skills.default_backend = Riffer::Skills::FilesystemBackend.new(".skills")
end

Accepts a Riffer::Skills::Backend instance or a Proc that receives context and returns a backend. Defaults to nil — agents that don’t set their own backend get no skills, matching pre-existing behavior. Per-agent backends override this default.

Tracing

Tracing-related global configuration lives under config.tracing. Riffer emits spans only through the backend you assign to config.tracing.backend — there is no auto-detection. OpenTelemetry is a built-in backend you opt into explicitly with Riffer::Tracing::Otel.build; with no backend set every span is a silent no-op, and riffer carries no OTEL gem dependency either way.

Riffer.configure do |config|
  config.tracing.enabled = ENV.fetch("RIFFER_TRACING_ENABLED", "true")
  # Opt into OpenTelemetry (uses the global tracer provider):
  config.tracing.backend = Riffer::Tracing::Otel.build
end

Pricing

Configure per-model token prices and riffer computes the cost of each LLM call onto its TokenUsage. Riffer ships no price table — so an unconfigured model simply carries no cost (token_usage.cost is nil).

Riffer.configure do |config|
  # Rates are per million tokens, keyed by the same "provider/model" id you give the agent.
  config.pricing.set("anthropic/claude-sonnet-4-6", input: 3.0, output: 15.0, cache_read: 0.30, cache_write: 3.75)
  config.pricing.set("openai/gpt-4", input: 30.0, output: 60.0)

  # Pass an array to share one set of rates across a model family:
  config.pricing.set(["openai/gpt-4", "openai/gpt-4-0613"], input: 30.0, output: 60.0)
end

Because the cache buckets are subsets of input_tokens, the cost formula subtracts them before applying the input rate:

cost = (input − cache_read − cache_write) × input_rate
     + cache_read  × cache_read_rate
     + cache_write × cache_write_rate
     + output      × output_rate

(all rates ÷ 1,000,000; an unset cache rate falls back to input_rate.) Cost is for observability, not billing — it’s a Float, and sub-cent rounding can accumulate over a long run. See Messages → Token Usage Semantics for how cost surfaces and aggregates.

Message ID Strategy

Opt in to stable identifiers on every message for logging, persistence, or replay:

Riffer.configure do |config|
  config.message_id_strategy = :uuidv7
end

When the strategy is not :none, every Riffer::Messages::Base instance — user prompts, system instructions, assistant responses, and tool results — gets an auto-generated id at construction time. IDs are included in message.to_h when present and omitted when nil. Provider API payloads are unaffected; the id stays on the Ruby side.

When constructing a Riffer::Agent::Session from persisted history with the strategy enabled, supply ids on every seeded message yourself — Riffer never fabricates identifiers for pre-existing history. Messages built via the Riffer::Messages::* constructors auto-generate ids per the strategy, so as long as those constructors are used at message-creation time, ids flow through.

See Messages — IDs for more details.

Experimental: History Healing

Warning: This feature is experimental and may change without notice.

Opts the agent into keeping the tool_use ↔ tool_result invariant intact on its own:

Riffer.configure do |config|
  config.experimental_history_healing = true
end

When enabled, two repairs run automatically:

1. Seeded session. Passing a pre-populated Riffer::Agent::Session to Agent.new(session: ...) silently drops orphaned tool_use exchanges (assistant tool_call with no matching Tool result) and parentless Tool messages before the next inference call. Pending tool calls on the resume boundary — the last assistant whose tail is purely Tool results (or none) — are preserved; execute_pending_tool_calls runs them on the next LLM call.

2. Interrupts. Any orphan tool_use left when the loop is interrupted (caller-issued interrupt! or the built-in INTERRUPT_MAX_STEPS ceiling) is filled with a placeholder Riffer::Messages::Tool carrying error_type: :interrupted and the content "Tool call interrupted before completion.". Filled call_ids are exposed on Riffer::Agent::Response#healed_tool_call_ids (and Riffer::StreamEvents::Interrupt#healed_tool_call_ids when streaming).

Defaults to false — pre-healing behavior. Seeded sessions pass through untouched, and orphan tool_use left by an interrupt remain in history for execute_pending_tool_calls to re-run on the next call.

There is no per-call override and no customizable placeholder. Callers needing finer control can call agent.session.update(tool_call_id:, ...) after the interrupt returns to upgrade a placeholder in place. See Agent Lifecycle — Healing pending tool results on interrupt.

Agent-Level Configuration

Override global configuration at the agent level:

provider_options

Pass options directly to the provider client:

class MyAgent < Riffer::Agent
  model 'openai/gpt-5-mini'

  # Override API key for this agent only
  provider_options api_key: ENV['CUSTOM_OPENAI_KEY']
end

model_options

Pass options to each LLM request:

class MyAgent < Riffer::Agent
  model 'openai/gpt-5-mini'

  # These options are sent with every generate/stream call
  model_options temperature: 0.7, reasoning: 'medium'
end

Common Model Options

OpenAI

class MyAgent < Riffer::Agent
  model 'openai/gpt-5-mini'
  model_options temperature: 0.7, reasoning: 'medium'
end

Amazon Bedrock

Options are passed through to the Bedrock Converse API.

class MyAgent < Riffer::Agent
  model 'amazon_bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0'
  model_options inference_config: {temperature: 0.7, max_tokens: 4096}
end

Anthropic

class MyAgent < Riffer::Agent
  model 'anthropic/claude-haiku-4-5-20251001'
  model_options temperature: 0.7, max_tokens: 4096
end

# With extended thinking (Claude 3.7+)
class ReasoningAgent < Riffer::Agent
  model 'anthropic/claude-haiku-4-5-20251001'
  model_options thinking: {type: "enabled", budget_tokens: 10000}
end

Environment Variables

Recommended pattern for managing credentials:

# config/initializers/riffer.rb (Rails)
# or at application startup

Riffer.configure do |config|
  config.openai.api_key = ENV.fetch('OPENAI_API_KEY') { raise 'OPENAI_API_KEY not set' }

  if ENV['BEDROCK_REGION']
    config.amazon_bedrock.region = ENV['BEDROCK_REGION']
    config.amazon_bedrock.api_token = ENV['BEDROCK_API_TOKEN']
  end
end

Multiple Configurations

For different environments or use cases, use agent-level overrides:

class ProductionAgent < Riffer::Agent
  model 'openai/gpt-5-mini'
  provider_options api_key: ENV['PRODUCTION_OPENAI_KEY']
end

class DevelopmentAgent < Riffer::Agent
  model 'openai/gpt-5-mini'
  provider_options api_key: ENV['DEV_OPENAI_KEY']
  model_options temperature: 0.0  # Deterministic for testing
end