The fundamentals · 03
Agents
Agents are the central orchestrator in Riffer. They manage the conversation flow, call LLM providers, and handle tool execution.
When to Use Agents
Use an agent when the task is open-ended and the LLM needs to reason, iterate, or call tools to produce a result. If your task follows a fixed sequence of steps with no LLM decision-making, consider a simpler pipeline instead.
Defining an Agent
Create an agent by subclassing Riffer::Agent:
class MyAgent < Riffer::Agent
model 'openai/gpt-5-mini'
instructions 'You are a helpful assistant.'
end
Configuration Methods
model
Sets the provider and model in provider/model format:
class MyAgent < Riffer::Agent
model 'openai/gpt-5-mini' # OpenAI
# or
model 'amazon_bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0' # Bedrock
# or
model 'mock/any' # Mock provider
end
Models can also be resolved dynamically with a lambda:
class MyAgent < Riffer::Agent
model -> { "anthropic/claude-haiku-4-5-20251001" }
end
When the lambda accepts a parameter, it receives the context:
class MyAgent < Riffer::Agent
model ->(context) {
context&.dig(:premium) ? "anthropic/claude-sonnet-4-5-20250929" : "anthropic/claude-haiku-4-5-20251001"
}
end
The lambda is re-evaluated on each generate or stream call, so the model can change between calls based on runtime context.
instructions
Sets system instructions for the agent:
class MyAgent < Riffer::Agent
model 'openai/gpt-5-mini'
instructions 'You are an expert Ruby programmer. Provide concise answers.'
end
Instructions can also be resolved dynamically with a lambda:
class MyAgent < Riffer::Agent
model 'openai/gpt-5-mini'
instructions -> { "Today is #{Date.today}. You are a helpful assistant." }
end
When the lambda accepts a parameter, it receives the context:
class MyAgent < Riffer::Agent
model 'openai/gpt-5-mini'
instructions ->(ctx) { "You are assisting #{ctx[:name]}" }
end
MyAgent.generate('Hello!', context: { name: 'Jane' })
The lambda is evaluated once at Agent.new time using the context passed to the constructor. To change instructions for a new context, construct a new agent.
identifier
Sets a custom identifier (defaults to snake_case class name):
class MyAgent < Riffer::Agent
model 'openai/gpt-5-mini'
identifier 'custom_agent_name'
end
MyAgent.identifier # => "custom_agent_name"
uses_tools
Registers tools the agent can use:
class MyAgent < Riffer::Agent
model 'openai/gpt-5-mini'
uses_tools [WeatherTool, TimeTool]
end
Tools can also be resolved dynamically with a lambda:
class MyAgent < Riffer::Agent
model 'openai/gpt-5-mini'
uses_tools ->(context) {
tools = [PublicTool]
tools << AdminTool if context&.dig(:user)&.admin?
tools
}
end
deferred_tools (experimental)
Holds tools back from the model until one of the agent’s own tools loads them. Every tool you pass to uses_tools costs tokens on every request, and models pick tools less reliably from a long list, so defer the ones most turns don’t need:
class Assistant < Riffer::Agent
model 'mock/riffer-1'
instructions "If you need a tool you don't have, use find_tools."
uses_tools [GetWeather, FindTools, ConnectCalendar]
deferred_tools [ListEvents, CreateEvent, SendInvoice]
end
Like uses_tools, deferred_tools takes an Array or a lambda that receives the context:
deferred_tools ->(context) { context[:billing] ? [ListEvents, SendInvoice] : [ListEvents] }
A tool can’t be both: one that’s in uses_tools (or comes from skills or MCP) and in deferred_tools raises Riffer::ArgumentError when the agent is built. The resolved list is agent.deferred_tools, and tools read it at call time as context.deferred_tools.
Any tool loads deferred tools by returning load_tools(...); see Tools → Loading deferred tools. Riffer records each load in the conversation, so a loaded tool stays loaded for the rest of it, including after the agent and its session are serialized and restored. A call to a deferred tool that hasn’t been loaded is refused.
By default deferred tools load natively, which needs provider support. anthropic and anthropic_vertex (see Anthropic → Deferred Tools), OpenAI and Azure OpenAI load them natively, and the Mock provider does too, for tests. Building an agent with deferred tools on any other provider raises Riffer::ArgumentError naming the provider, unless it uses the gateway strategy. Riffer doesn’t check which models support native loading, so an unsupported model on one of those providers gets the provider’s own error.
Nothing tells the model that more tools exist unless you do, in a tool’s description or the instructions. If no tool ever returns load_tools, the deferred tools can’t be reached, and riffer can’t detect that.
Deferring a tool hides it from the model; it doesn’t restrict it. Any tool can load any deferred tool, so leave a tool out of the agent entirely if the user mustn’t reach it.
The feature is experimental: it can change in any minor release (see Stability).
Deferred tools strategy (experimental)
By default the provider loads deferred tools itself. For a provider without native loading, or a model that rejects it, opt the agent into the experimental gateway strategy:
class Assistant < Riffer::Agent
model 'amazon_bedrock/my-model'
instructions "If you need a tool you don't have, use find_tools."
uses_tools [FindTools]
deferred_tools [ListEvents, CreateEvent], strategy: :gateway
end
With strategy: :gateway, the provider never loads deferred tools natively, even one that can. Every request carries one extra tool, the gateway, and the model calls a loaded tool through it, so the tool list never changes and a load keeps the prompt cache; see Tools → The gateway strategy. No other tool of the agent can share the gateway’s name.
| Strategy | Behavior |
|---|---|
:native (default) |
The provider loads deferred tools itself; raises on a provider without native loading |
:gateway |
Loaded tools are called through one extra tool, on every provider; experimental, may change |
Riffer does not pick a strategy per provider — the choice is always yours. The strategy is copied to subclasses and survives serialization. An unknown value raises Riffer::ArgumentError. strategy: can also be passed with a lambda: deferred_tools ->(context) { [ListEvents] }, strategy: :gateway.
use_mcp (deprecated)
Loads tools from registered MCP servers by tag. MCP client support is deprecated and will be removed in a future release; each use_mcp line reports a deprecation. See MCP → Moving off MCP.
model_options
Passes options to each LLM request:
class MyAgent < Riffer::Agent
model 'openai/gpt-5-mini'
model_options reasoning: 'medium', temperature: 0.7, web_search: true
end
reasoning
Sets how much the model thinks before it answers: :off, :low, :medium, :high, :xhigh, or :max (a String works too). Anything else raises Riffer::ArgumentError. Leave it unset to send nothing and keep the model’s default.
class MyAgent < Riffer::Agent
model 'anthropic/claude-sonnet-4-6'
reasoning :low
end
Riffer turns the level into the provider’s own params. It uses the model’s catalog entry when one defines the level, and otherwise the provider’s default, which sends the level name as the provider’s effort value (for example output_config: { effort: "low" } with adaptive thinking on Anthropic). Riffer doesn’t check whether the model supports the level; a model that rejects it returns the provider’s error.
model_options are deep-merged over those params, so they override single fields rather than whole blocks. For example, model_options max_tokens: 8000 keeps the catalog’s thinking budget and replaces only its max_tokens.
max_steps
Sets the maximum number of LLM call steps in the tool-use loop. When the limit is reached, the loop interrupts with reason :max_steps. Defaults to 16. Set to nil (max_steps nil) for unlimited steps:
class MyAgent < Riffer::Agent
model 'openai/gpt-5-mini'
max_steps 8
end
structured_output
Configures the agent to return structured JSON responses conforming to a schema. Accepts a Riffer::Params instance or a block DSL:
class SentimentAgent < Riffer::Agent
model 'openai/gpt-5-mini'
instructions 'Analyze the sentiment of the given text.'
structured_output do
required :sentiment, :string, description: "positive, negative, or neutral"
required :score, :number, description: "Confidence score between 0 and 1"
optional :explanation, :string, description: "Brief explanation"
end
end
The LLM response is automatically parsed and validated against the schema. Access the result via response.structured_output.
If the response is not valid JSON on its own, Riffer recovers a JSON object wrapped in a code fence (```json), surrounded by prose (Here is the data: {...}), or wrapped in formatting (**{...}**). It parses the span from the first { to the last }, so a reply whose surrounding text contains other braces, or that holds more than one object, is still rejected. When the recovered object validates, response.content holds only the extracted JSON text, without the fence or prose; the assistant message in response.messages keeps the raw reply. A reply that fails parsing or validation leaves the raw text in response.content.
When the response contains no well-formed JSON object or does not satisfy the schema, response.structured_output is nil, response.outcome.reason is :invalid_structured_output, and response.outcome.detail carries the parse or validation message:
response = SentimentAgent.generate('Analyze: "I love this!"')
if response.outcome.success?
response.structured_output # => {sentiment: "positive", score: 0.95}
else
response.outcome.reason # => :invalid_structured_output
response.outcome.detail # => "score is required"
end
Structured output strategy (experimental)
By default Riffer sends the schema through each provider’s native structured-output field. Some models reject that field, accept it without enforcing it, or behave differently with it enabled (for example, skipping tool calls). For those, opt the agent into the experimental prompted strategy:
class SentimentAgent < Riffer::Agent
model 'amazon_bedrock/my-model'
instructions 'Analyze the sentiment of the given text.'
structured_output strategy: :prompted do
required :sentiment, :string, description: "positive, negative, or neutral"
end
end
With strategy: :prompted, the provider never receives its native structured-output field. Instead, an instruction is appended to the end of every user message on every request of the run, after consecutive user messages are merged (it is not stored in session.messages, and the system instructions are left untouched). The instruction carries the JSON Schema, an example of the expected shape with placeholder values ("<string>", enum values as "a | b", an :any_of field as its first variant, or as "<integer> | <string>" when every variant is primitive), and a nudge to reply with the JSON right away unless the request needs a tool. The reply is parsed and validated exactly as above: response.content is the reply’s JSON text, response.structured_output holds the validated object, and a reply that fails parsing or validation ends with :invalid_structured_output. Because nothing forces the model to comply, expect more :invalid_structured_output outcomes than with the native strategy.
| Strategy | Behavior |
|---|---|
:native (default) |
Schema sent through the provider’s structured-output field |
:prompted |
Schema appended to each user message; experimental, may change |
Riffer does not pick a strategy per model — the choice is always yours. The strategy is copied to subclasses and survives serialization. An unknown value raises Riffer::ArgumentError. strategy: can also be passed with a Riffer::Params instance: structured_output params, strategy: :prompted.
Nested Objects
Use :object with a block to define nested object schemas:
structured_output do
required :name, :string, description: "Person name"
required :address, :object, description: "Mailing address" do
required :street, :string, description: "Street address"
required :city, :string, description: "City"
optional :postal_code, :string, description: "Postal or zip code"
end
end
Validation errors use dot-path notation: address.city is required.
Typed Arrays
Use :array with the of: keyword for arrays of primitive types:
structured_output do
required :tags, :array, of: :string, description: "Tags"
required :scores, :array, of: :number, description: "Scores"
end
of: takes a primitive type: :string, :integer, :number or :boolean.
Add enum: to limit each item to a list of values:
structured_output do
required :tags, :array, of: :string, enum: %w[urgent billing technical]
end
An item outside the list fails validation with its index: tags[1] must be one of: urgent, billing, technical.
For an array of arrays, put the type in brackets. Each pair of brackets adds a level, and enum: and format: apply to the innermost items:
structured_output do
required :rows, :array, of: [:integer], description: "Seat numbers, one array per row"
required :board, :array, of: [:string], enum: %w[x o]
end
A row that isn’t an array fails validation with its index: rows[1] must be an array.
Formats
Use format: on a :string, or on an :array whose innermost type is :string, to require a standard string format:
structured_output do
required :born_on, :string, format: "date"
optional :email, :string, format: "email"
required :visit_ids, :array, of: :string, format: "uuid"
end
Supported formats: date-time, time, date, duration, email, hostname, ipv4, ipv6, uuid. Dates and times use RFC 3339 syntax, and a time may leave out its UTC offset. email and hostname are checked loosely, rejecting only values that are clearly not an address or a host name.
A value that doesn’t match fails validation, with its index on an array: born_on must be a valid date, visit_ids[1] must be a valid uuid. Values stay strings.
A model that must match a format writes a matching value even when it has none, so it may invent an email. Make such a field optional so the model can return null.
Arrays of Objects
Use :array with a block to define arrays of objects:
structured_output do
required :items, :array, description: "Line items" do
required :name, :string, description: "Product name"
required :price, :number, description: "Price"
optional :quantity, :integer, description: "Quantity"
end
end
Validation errors include the array index: items[1].price is required.
Deep Nesting
Blocks can be nested arbitrarily deep:
structured_output do
required :orders, :array, description: "Orders" do
required :id, :string, description: "Order ID"
required :shipping, :object, description: "Shipping info" do
required :address, :object, description: "Address" do
required :street, :string
required :city, :string
end
end
end
end
Either/Or Shapes
Use :any_of when a field must be one of several object shapes. Each variant block defines one shape, the same way an :object block does:
structured_output do
required :result, :any_of, description: "The address, or why none was found" do
variant do
required :street, :string, description: "Street address"
required :city, :string, description: "City"
end
variant do
required :error_code, :string, enum: %w[no_address multiple_addresses]
required :error_message, :string
end
end
end
The schema sends the field as anyOf, with one object per variant. An answer must match one variant completely: every required field of that variant, and no field from outside it. Variants are tried in order and the first match is returned. When none match, the error lists each variant’s problems: result must match one of the variants: variant 1 (street is required, city is required), variant 2 (error_code is required, error_message is required).
An optional :any_of field can also be null.
A variant can be a primitive type instead of a block, with its own description:, enum: or format:, and one field can mix both kinds:
structured_output do
required :quantity, :any_of, description: "A count, or a word like 'several'" do
variant :integer
variant :string
end
optional :due, :any_of do
variant :string, format: "date"
variant :string, enum: ["none"]
end
end
Each primitive variant is sent as its own anyOf branch. A value whose type matches no variant fails validation: quantity must be a integer or string. A value of the right type that fails every variant gets each variant’s problems: due must match one of the variants: variant 1 (must be a valid date), variant 2 (must be one of: none).
Limitations
Anthropic and Bedrock reject a structured output schema with more than 16 union-type fields. Every :any_of field counts, and so does every optional field, since strict mode sends it as nullable.
An :object param requires a block, and an :array param requires a block or of:. Using both of: and a block raises Riffer::ArgumentError. Using of: with a non-primitive type (e.g. of: :object or of: [:object]), or with more than one type (of: [:integer, :string]), also raises Riffer::ArgumentError. An :any_of param requires a block with at least two variants, and can’t be used with of: or enum:. A variant takes either a primitive type, with optional description:, enum: or format:, or a block. Anything else raises Riffer::ArgumentError, and so does an :integer variant after a :number variant without enum:, since that :number variant accepts every number and the first match wins. Using enum: on an :object, or on an :array without of:, also raises Riffer::ArgumentError. So does format: with an unsupported format, on a type other than :string or an :array whose innermost type is :string, or together with enum:.
Structured output is not compatible with streaming — calling stream on an agent with structured output configured raises Riffer::ArgumentError.
tool_runtime
Configures how tool calls are executed. Defaults to sequential (inline) execution:
class MyAgent < Riffer::Agent
model 'openai/gpt-5-mini'
uses_tools [WeatherTool, SearchTool]
tool_runtime Riffer::Tools::Runtime::Threaded
end
Accepts a Riffer::Tools::Runtime subclass, a Riffer::Tools::Runtime instance, or a Proc. When unset, reads Riffer.config.tool_runtime at the point of use, so an agent that declares none follows a later change to the global. See Tools — Tool Runtime for details.
guardrail
Registers guardrails for pre/post processing of messages. Pass the guardrail class and any options:
class MyAgent < Riffer::Agent
model 'openai/gpt-5-mini'
# Input-only guardrail
guardrail :before, with: InputValidator
# Output-only guardrail
guardrail :after, with: ResponseFilter
# Both input and output, with options
guardrail :around, with: MaxLengthGuardrail, max: 1000
end
See Guardrails for detailed documentation.
Configuration Object
Every DSL setting above is stored on a Riffer::Agent::Config instance accessible via the class. Each subclass has its own:
class MyAgent < Riffer::Agent
model 'openai/gpt-5-mini'
max_steps 8
end
MyAgent.config # => #<Riffer::Agent::Config ...>
MyAgent.config.max_steps # => 8
The DSL methods read and mutate this Config in place.
Inheritance
A subclass starts from a copy of its parent’s Config, so it inherits every setting the parent declared and overrides only what its own body declares:
class BaseAgent < Riffer::Agent
model 'openai/gpt-5-mini'
max_steps 8
end
class TerseAgent < BaseAgent
max_steps 2
end
TerseAgent.config.model # => 'openai/gpt-5-mini'
TerseAgent.config.max_steps # => 2
BaseAgent.config.max_steps # => 8
identifier is not inherited. A subclass derives its own from its class name, since two classes claiming one identifier would raise Riffer::DuplicateIdentifierError at the first lookup.
For advanced composition or testing, build a Config directly and pass it via config: to bypass class-level DSL entirely:
config = Riffer::Agent::Config.new(
model: 'openai/gpt-5-mini',
instructions: 'You are a helpful assistant.',
max_steps: 4
)
agent = Riffer::Agent.new(config: config)
agent.generate('Hello')
When config: is supplied, the class-level configuration is ignored for that instance.
Looking Up Agents
Look up an agent by identifier with Riffer::Agent.find, or list every agent with Riffer::Agent.all:
class SupportAgent < Riffer::Agent
model 'openai/gpt-5-mini'
end
Riffer::Agent.find('support_agent') # => SupportAgent
Riffer::Agent.find(:support_agent) # symbols work too
Riffer::Agent.find('missing') # => nil
Riffer::Agent.all # => [SupportAgent, ...]
Only named direct subclasses are found implicitly:
- Grandchildren are not visible to a grandparent’s
findorall. If your app defines an intermediate base class (class ApplicationAgent < Riffer::Agent), callfind/allon the intermediate class to look up its subclasses. - Anonymous classes (
Class.new(Riffer::Agent)) are never findable implicitly, even when they set an explicitidentifier— see Registering an agent explicitly. - Two subclasses sharing an identifier raise
Riffer::DuplicateIdentifierErrorat the first lookup. - A subclass whose constant no longer points at it — after a Zeitwerk reload or an RSpec
stub_const— drops out offindandall. The check runs when the registry is rebuilt, which defining, registering, or unregistering a subclass triggers; removing or restoring a constant on its own does not, so lookups keep returning the old class until the next rebuild.
Registering an agent explicitly
Testing an agent that gets resolved by identifier? Use Riffer::Testing — stub_agent builds and registers a throwaway agent and cleans it up for you. The API below is the manual alternative, for production wiring and anything outside the stub lifecycle.
register adds an agent to its parent’s registry by hand and unregister removes it:
Riffer::Agent.register(agent) # findable until unregistered
Riffer::Agent.unregister(agent) # no-op if it was never registered
Explicit registration differs from implicit in a few ways:
- Anonymous classes are allowed, as long as they declare an
identifier. A blank identifier raisesRiffer::ArgumentError. - The class must be a direct subclass of the receiver, mirroring implicit registration.
Riffer::Agent.register(SomeAppAgent)raisesRiffer::ArgumentErrorwhenSomeAppAgentdescends from an intermediate base — callregisteron that base instead. - Taking an identifier already held by another agent, implicit or explicit, raises
Riffer::DuplicateIdentifierError. Re-registering the same class raises too; there is no idempotent path. - The registration survives until you remove it — it is never dropped for a stale constant.
Registration is not synchronized. Register during boot or from a single-threaded test, before concurrent lookups begin.
Per-Call Tags
#generate and #stream accept an optional tags: hash — a flat map of attribution labels scoped to that single call (for cost/usage attribution, filtering audit logs, slicing telemetry). It is per-call only.
agent.generate("Summarize this ticket.",
tags: {team: "growth", feature: "summarizer", user_id: "u_abc123"})
agent.stream("...", tags: {team: "growth", environment: "production"})
Keys and values may be String or Symbol; both are stringified, and entries with a nil value are dropped.
Tags propagate to two places:
- The provider’s native per-request metadata field (see the mapping below).
- Observability — stamped as
riffer.tag.<key>on every span the call emits (invoke_agent,chat,execute_tool,execute_guardrail). See Tracing.
Default tags
Every call also carries two tags riffer adds itself, so a provider can tell who the call is on behalf of:
| Tag | Value |
|---|---|
kind |
"agent" ("judge" for evaluator judge calls) |
agent |
The agent’s identifier (the evaluator’s identifier for judge calls) |
A tag you pass with the same key wins. The default tags count towards the provider limits below.
Reserved key: user_id
user_id is a reserved tag. Beyond appearing like any other tag, it maps to the provider’s native end-user identifier where one exists (see the table).
Provider mapping
| Provider | Native request field | user_id handling |
|---|---|---|
| Amazon Bedrock | request_metadata (all tags) |
Ordinary entry; no dedicated user field |
| OpenAI / Azure OpenAI | metadata (all tags) |
Also mapped to safety_identifier |
| OpenRouter | metadata (all tags) |
Also mapped to user |
| Anthropic | metadata.user_id only |
The only tag forwarded |
| Gemini | (none — observability only) | Tag only; no request field |
| Google Cloud (Gemini) | labels (all tags, rewritten) |
Ordinary entry; no dedicated user field |
| Google Cloud (Claude) | metadata.user_id only |
The only tag forwarded |
If model_options already sets the native field (metadata, request_metadata or labels), the tags are merged into it; a tag wins on a shared key.
Anthropic silently drops non-user_id tags. The Messages API has no free-form request-metadata field — only metadata.user_id. So for Anthropic, user_id is forwarded as metadata: {user_id: …} and every other tag is dropped from the request (it still appears on spans). This is intentional.
Gemini is observability-only. Riffer’s Gemini adapter targets the Gemini Developer API (generativelanguage.googleapis.com), whose generateContent request has no labels field — sending unknown fields is rejected. So tags are not added to the Gemini request; they propagate to spans only.
Google Cloud rewrites tags into valid labels. Agent Platform labels keys and values take at most 63 lowercase letters, digits, underscores and dashes, and keys start with a letter. Riffer downcases each tag, replaces any other character with _, cuts it to 63 characters, and drops tags whose key doesn’t start with a letter. agent: "support/triage_agent" goes out as agent: "support_triage_agent". Labels set in model_options are sent as is. Labels show up in Google Cloud billing reports, so high-cardinality tags such as user_id add one label value per user.
Claude on Google Cloud (anthropic_vertex) follows the Anthropic rule above.
Provider limits (not enforced)
Apart from the Google Cloud rewrite above, riffer does not validate tag count, key/value length, or charset — it forwards what you give it and lets the provider reject anything out of bounds. Known limits: Bedrock requestMetadata ≤16 entries, key/value ≤256 chars; OpenAI / OpenRouter metadata ≤16 pairs (OpenRouter: 64-char keys, 512-char values).
Expand Your Agent
| Goal | Feature | Guide |
|---|---|---|
| Call APIs or run functions | Tools | Tools |
| Return structured JSON | Structured Output | structured_output |
| Validate or filter content | Guardrails | Guardrails |
| Measure output quality | Evals | Evals |
| Add packaged capabilities | Skills | Skills |
| Control the tool-use loop | Agent Loop | Agent Loop |
| Human-in-the-loop approval | Interrupts | Agent Lifecycle |
| Run tools concurrently | Tool Runtime | Advanced Tools |
| Stream responses in real time | Streaming | Agent Lifecycle |