class RubyLLM::Agent

An Agent is a reusable chat configuration defined as a class. Subclasses declare a model, instructions, tools, and other settings once, then build configured chats wherever they are needed.

class SupportAgent < RubyLLM::Agent
  model "gpt-5-nano"
  instructions "You are a concise support assistant."
  tools SearchDocs, LookupAccount
end

SupportAgent.new.ask "How do I reset my API key?"

::chat returns a configured Chat. When ::chat_model names an ActiveRecord chat class, ::create, ::create!, and ::find return configured records of that class instead.

Configuration that depends on runtime state goes in blocks or lambdas. They are evaluated when a chat is built, with chat and any declared ::inputs available as methods:

class WorkAssistant < RubyLLM::Agent
  inputs :workspace

  instructions { "You are helping #{workspace.name}" }
end

WorkAssistant.chat(workspace: workspace)

Agent instances delegate the Chat API (ask, complete, with_tools, and so on) to the wrapped chat, which is available via chat. Agents are enumerable over their messages.

Attributes

chat [R]

The wrapped Chat, or the chat record in Rails mode.

Public Class Methods

caching (**options, &block)

Source

# File lib/ruby_llm/agent.rb, line 190
def caching(**options, &block)
  return @caching if options.empty? && !block_given?

  @caching = block_given? ? block : options
end

Sets prompt caching options for chats this agent builds, applied via Chat#with_caching. A block defers evaluation until the chat is built. Called with no arguments, returns the configured value.

caching ttl: "1h"

chat (**kwargs)

Source

# File lib/ruby_llm/agent.rb, line 304
def chat(**kwargs)
  input_values, chat_options = partition_inputs(kwargs)
  chat = RubyLLM.chat(**chat_kwargs, **chat_options)
  apply_configuration(chat, input_values:, persist_instructions: true)
  chat
end

Builds a Chat configured with this agent’s declarations and returns it. Keywords matching declared ::inputs become runtime inputs; the rest are forwarded to RubyLLM.chat.

chat = WorkAssistant.chat
chat.ask "Hello"

chat_model (value = nil)

Source

# File lib/ruby_llm/agent.rb, line 273
def chat_model(value = nil)
  return @chat_model if value.nil?

  @chat_model = value
  remove_instance_variable(:@resolved_chat_model) if instance_variable_defined?(:@resolved_chat_model)
end

Sets the ActiveRecord chat class this agent creates and finds, activating Rails mode (::create, ::create!, ::find, and ::sync_instructions!). Accepts the class or its name as a string. Called with no argument, returns the configured value.

chat_model Chat

citations (value = nil)

Source

# File lib/ruby_llm/agent.rb, line 178
def citations(value = nil)
  return @citations if value.nil?

  @citations = value
end

Enables or disables citations for chats this agent builds, applied via Chat#with_citations or Chat#without_citations. Called with no argument, returns the configured value.

citations true

context (value = nil)

Source

# File lib/ruby_llm/agent.rb, line 260
def context(value = nil)
  return @context if value.nil?

  @context = value
end

Sets a Context whose configuration chats this agent builds should use, applied via Chat#with_context. Called with no argument, returns the configured context.

create (**kwargs)

Source

# File lib/ruby_llm/agent.rb, line 318
def create(**kwargs)
  with_rails_chat_record(:create, **kwargs)
end

Creates a ::chat_model record, applies this agent’s configuration to it, and returns it. Keywords matching declared ::inputs become runtime inputs; the rest are forwarded to the model’s create.

chat = WorkAssistant.create(user: current_user)

Raises ArgumentError if ::chat_model is not configured.

create! (**kwargs)

Source

# File lib/ruby_llm/agent.rb, line 327
def create!(**kwargs)
  with_rails_chat_record(:create!, **kwargs)
end

Like ::create, but calls the model’s create!, raising if the record is invalid.

chat = WorkAssistant.create!(user: current_user)

fallbacks (*models, **options)

Source

# File lib/ruby_llm/agent.rb, line 243
def fallbacks(*models, **options)
  return @fallbacks || [] if models.empty? && options.empty?
  raise ArgumentError, 'To set fallback options, provide at least one fallback model' if models.empty?

  @fallbacks = models.flatten.compact
  @fallback_options = options
end

Sets fallback models for chats this agent builds, applied via Chat#with_fallbacks. Called with no arguments, returns the configured models.

fallbacks "gpt-4.1-mini", "claude-haiku-4-5"
fallbacks "gpt-4.1-mini", on: [RubyLLM::RateLimitError]

find (id, **kwargs)

Source

# File lib/ruby_llm/agent.rb, line 338
def find(id, **kwargs)
  raise ArgumentError, 'chat_model must be configured to use find' unless resolved_chat_model

  input_values, = partition_inputs(kwargs)
  record = resolved_chat_model.find(id)
  apply_configuration(record, input_values:, persist_instructions: false)

  record
end

Finds the ::chat_model record with id and applies this agent’s configuration at runtime, without persisting instructions. Returns the record.

chat = WorkAssistant.find(params[:id])

Raises ArgumentError if ::chat_model is not configured.

headers (**headers, &block)

Source

# File lib/ruby_llm/agent.rb, line 212
def headers(**headers, &block)
  return @headers || {} if headers.empty? && !block_given?

  @headers = block_given? ? block : headers
end

Sets custom HTTP headers for chats this agent builds, applied via Chat#with_headers. A block defers evaluation until the chat is built. Called with no arguments, returns the configured value.

inputs (*names)

Source

# File lib/ruby_llm/agent.rb, line 287
def inputs(*names)
  return @input_names || [] if names.empty?

  @input_names = names.flatten.map(&:to_sym)
end

Declares named runtime inputs. Matching keyword arguments passed to ::chat, ::create, ::create!, ::find, or ::new become methods inside lazy configuration blocks. Called with no arguments, returns the declared names.

inputs :workspace

instructions (text = nil, **prompt_locals, &block)

Source

# File lib/ruby_llm/agent.rb, line 127
def instructions(text = nil, **prompt_locals, &block)
  return @instructions if text.nil? && prompt_locals.empty? && !block_given?

  @instructions = block || text || { prompt: 'instructions', locals: prompt_locals }
end

Sets system instructions for chats this agent builds. Accepts a string, a block evaluated when the chat is built, or keyword locals for the agent’s conventional prompt template (for a WorkAssistant agent, app/prompts/work_assistant/instructions.txt.erb).

instructions "You are a helpful assistant."
instructions { "You are helping #{workspace.name}" }
instructions display_name: -> { chat.user.display_name_or_email }

A named agent uses its conventional template automatically when it exists, even without calling this method. Called with no arguments, returns the configured value.

max_output_tokens(value = nil)

Source

# File lib/ruby_llm/agent.rb, line 151
PASSTHROUGH_OPTIONS.each do |option|
  define_method(option) do |value = nil|
    return instance_variable_get(:"@#{option}") if value.nil?

    instance_variable_set(:"@#{option}", value)
  end
end

Caps the number of tokens chats this agent builds may generate. Called with no argument, returns the configured value.

max_output_tokens 1000

model (model_id = nil, **options)

Source

# File lib/ruby_llm/agent.rb, line 81
def model(model_id = nil, **options)
  return @chat_kwargs || {} if model_id.nil? && options.empty?

  options[:model] = model_id unless model_id.nil?
  @chat_kwargs = options
end

Sets the model used by chats this agent builds. Extra options are forwarded to RubyLLM.chat, including provider: to disambiguate the model and protocol: to override its wire protocol. Called with no arguments, returns the configured chat keywords.

model "gpt-5-nano"
model "gpt-5.4", provider: :openai, protocol: :responses

new (chat: nil, inputs: nil, persist_instructions: true, **kwargs)

Source

# File lib/ruby_llm/agent.rb, line 622
def initialize(chat: nil, inputs: nil, persist_instructions: true, **kwargs)
  input_values, chat_options = self.class.partition_inputs(kwargs)
  @chat = chat || RubyLLM.chat(**self.class.chat_kwargs, **chat_options)
  self.class.apply_configuration(@chat, input_values: input_values.merge(inputs || {}),
                                        persist_instructions:)
end

Returns a new agent wrapping chat:, or wrapping a newly built chat when chat: is nil. Applies the agent’s configuration either way. Keywords matching declared inputs (and the inputs: hash) become runtime inputs; the rest are forwarded to RubyLLM.chat when the agent builds its own chat. Pass persist_instructions: false to apply instructions at runtime only, without persisting them on a Rails-backed record.

agent = WorkAssistant.new
agent.ask "Hello"

record = Chat.find(params[:id])
WorkAssistant.new(chat: record)

provider_options (**provider_options, &block)

Source

# File lib/ruby_llm/agent.rb, line 203
def provider_options(**provider_options, &block)
  return @provider_options || {} if provider_options.empty? && !block_given?

  @provider_options = block_given? ? block : provider_options
end

Sets options in the provider’s request vocabulary for chats this agent builds, applied via Chat#with_provider_options. A block defers evaluation until the chat is built. Called with no arguments, returns the configured value.

provider_options max_output_tokens: 256

schema (value = nil, &block)

Source

# File lib/ruby_llm/agent.rb, line 230
def schema(value = nil, &block)
  return @schema if value.nil? && !block_given?

  @schema = block_given? ? block : value
end

Sets the structured output schema for chats this agent builds, applied via Chat#with_schema. Accepts a schema class, a JSON schema hash, or a block. A plain block is built with the RubyLLM::Schema DSL; a lambda is evaluated when the chat is built. Called with no arguments, returns the configured value.

schema PersonSchema
schema do
  string :verdict, enum: ["pass", "revise"]
  string :feedback
end

sync_instructions! (chat_or_id, **kwargs)

Source

# File lib/ruby_llm/agent.rb, line 356
def sync_instructions!(chat_or_id, **kwargs)
  raise ArgumentError, 'chat_model must be configured to use sync_instructions!' unless resolved_chat_model

  input_values, = partition_inputs(kwargs)
  record = chat_or_id.is_a?(resolved_chat_model) ? chat_or_id : resolved_chat_model.find(chat_or_id)
  apply_assume_model_exists(record)
  apply_protocol(record)
  runtime = runtime_context(chat: record, inputs: input_values)
  instructions_value = resolved_instructions_value(record, runtime, inputs: input_values)
  return record if instructions_value.nil?

  record.with_instructions(instructions_value)
  record
end

Re-renders this agent’s instructions and persists them on the given ::chat_model record (or the record found by that id). Keywords matching declared ::inputs become runtime inputs. Returns the record.

WorkAssistant.sync_instructions!(chat)

Raises ArgumentError if ::chat_model is not configured.

temperature(value = nil)

Source

# File lib/ruby_llm/agent.rb, line 134

Sets the sampling temperature for chats this agent builds. Called with no argument, returns the configured value.

temperature 0.2

thinking (effort: nil, budget: nil)

Source

# File lib/ruby_llm/agent.rb, line 166
def thinking(effort: nil, budget: nil)
  return @thinking if effort.nil? && budget.nil?

  @thinking = { effort: effort, budget: budget }
end

Sets the thinking effort or budget for chats this agent builds, applied via Chat#with_thinking. Called with no arguments, returns the configured value.

thinking effort: :low
thinking budget: 10_000

tool_options (**options, &block)

Source

# File lib/ruby_llm/agent.rb, line 109
def tool_options(**options, &block)
  return @tool_options || {} if options.empty? && !block_given?

  @tool_options = block_given? ? block : options
end

Sets how chats this agent builds use their tools, applied via Chat#with_tool_options. Accepts choice:, calls:, and concurrency:. A block defers evaluation until the chat is built. Called with no arguments, returns the configured options.

tool_options choice: :required, calls: :one

tools (*tools, &block)

Source

# File lib/ruby_llm/agent.rb, line 96
def tools(*tools, &block)
  return @tools || [] if tools.empty? && !block_given?

  @tools = block_given? ? block : tools.flatten
end

Declares the tools for chats this agent builds. A block defers construction until the chat is built. Configure how the model uses them with ::tool_options. Called with no arguments, returns the declared tools.

tools SearchDocs, LookupAccount
tools { [TodoTool.new(chat: chat)] }

Public Instance Methods

add_completion ()

Source

# File lib/ruby_llm/agent.rb, line 865

Appends a completed response to the conversation. See Chat#add_completion.

add_message ()

Source

# File lib/ruby_llm/agent.rb, line 860

Appends a message to the conversation. See Chat#add_message.

after_fallback ()

Source

# File lib/ruby_llm/agent.rb, line 820

Registers a callback run after a fallback attempt. See Chat#after_fallback.

after_message ()

Source

# File lib/ruby_llm/agent.rb, line 800

Registers a callback run after each assistant message. See Chat#after_message.

after_tool_result ()

Source

# File lib/ruby_llm/agent.rb, line 810

Registers a callback run after each tool result. See Chat#after_tool_result.

ask ()

Source

# File lib/ruby_llm/agent.rb, line 669

Sends a user message and returns the model’s final response. See Chat#ask.

ask_later ()

Source

# File lib/ruby_llm/agent.rb, line 840

Stages a question without asking it. See Chat#ask_later.

before_fallback ()

Source

# File lib/ruby_llm/agent.rb, line 815

Registers a callback run before trying a fallback model. See Chat#before_fallback.

before_message ()

Source

# File lib/ruby_llm/agent.rb, line 795

Registers a callback run before each assistant message. See Chat#before_message.

before_tool_call ()

Source

# File lib/ruby_llm/agent.rb, line 805

Registers a callback run before each tool call. See Chat#before_tool_call.

caching ()

Source

# File lib/ruby_llm/agent.rb, line 664

Returns the prompt caching configuration. See Chat#caching.

complete ()

Source

# File lib/ruby_llm/agent.rb, line 830

Runs the agentic loop until nothing is left to do. See Chat#complete.

complete? ()

Source

# File lib/ruby_llm/agent.rb, line 835

Returns whether the conversation needs no further work. See Chat#complete?.

cost ()

Source

# File lib/ruby_llm/agent.rb, line 874
def_delegators :chat, :model, :messages, :tools, :provider_options, :headers, :schema, :caching, :ask, :say,
               :with_tools, :without_tools, :with_tool_options, :without_tool_options, :with_model,
               :with_temperature, :without_temperature, :with_max_output_tokens, :without_max_output_tokens,
               :with_thinking, :without_thinking, :with_citations, :without_citations, :with_caching,
               :without_caching, :with_context, :without_context, :with_provider_options,
               :without_provider_options, :with_headers, :without_headers, :with_schema, :without_schema,
               :with_fallbacks, :without_fallbacks, :before_message, :after_message, :before_tool_call,
               :after_tool_result, :before_fallback, :after_fallback, :each, :complete, :complete?, :ask_later,
               :generate, :run_tools, :step, :add_message, :add_completion, :cost