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-6-luna"
  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. Most blocks run after a chat is built, with chat and any declared ::inputs available as methods. The model block runs before a chat exists. A deferred context block also runs before Chat construction in plain Ruby, but receives the Rails chat record while Rails configures it:

class WorkAssistant < RubyLLM::Agent
  inputs :workspace

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

WorkAssistant.chat(workspace: workspace)

Agent instances delegate Chat’s conversation API (ask, complete, with_tools, and so on) to the wrapped chat, which is available via chat. Direct transcript replacement stays on the wrapped chat because Rails-backed chat models own their message association. Agents are enumerable over their messages.

Attributes

chat [R]

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

Public Class Methods

caching (enabled = true, **options, &block)

Source

# File lib/ruby_llm/agent.rb, line 396
def caching(enabled = true, **options, &block) # rubocop:disable Metrics/PerceivedComplexity, Style/OptionalBooleanParameter
  return caching(**enabled.transform_keys(&:to_sym), **options, &block) if enabled.is_a?(Hash)

  raise ArgumentError, 'caching accepts false or caching options' unless [true, false].include?(enabled)
  raise ArgumentError, 'caching accepts options or a block, not both' if options.any? && block
  raise ArgumentError, 'caching false does not accept options or a block' if !enabled && (options.any? || block)

  @caching = block || (enabled ? options : false)
end

Enables prompt caching for chats this agent builds, applied via Chat#with_caching. With no options, the provider’s default behavior applies. Pass false to stop RubyLLM from sending cache controls. A provider may still cache prompts implicitly. A block defers evaluation until the chat is built. Accepts keywords or an options Hash.

caching
caching false
caching ttl: "1h"
caching { { ttl: workspace.cache_ttl } }

chat (**kwargs)

Source

# File lib/ruby_llm/agent.rb, line 603
def chat(**kwargs)
  input_values, chat_options = partition_inputs(kwargs)
  context_value = resolved_context(inputs: input_values)
  chat = build_chat(inputs: input_values, options: chat_options, resolved_context: context_value)
  apply_configuration(chat, input_values:, persist_instructions: true, resolved_context: context_value)
  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 500
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 = true)

Source

# File lib/ruby_llm/agent.rb, line 379
def citations(value = true) # rubocop:disable Style/OptionalBooleanParameter
  raise ArgumentError, 'citations accepts true or false' unless [true, false].include?(value)

  @citations = value
end

Enables citations for chats this agent builds, applied via Chat#with_citations. Pass false to disable them.

citations
citations false

code_execution (enabled = true, **options)

Source

# File lib/ruby_llm/agent.rb, line 311
def code_execution(enabled = true, **options) # rubocop:disable Style/OptionalBooleanParameter
  @code_execution = CodeExecution.options(enabled, options)
end

Lets chats this agent builds run code in the configured sandbox, applied via Chat#with_code_execution. Accepts the same options as keywords or a Hash. Pass false to disable it. Passing nil raises ArgumentError.

code_execution
code_execution false
code_execution languages: [:ruby, :python], gems: %w[prawn]
code_execution sandbox: ReadOnlySandbox, escalate_to: [WorkspaceSandbox]
code_execution mounts: -> { { "templates" => chat.templates_dir } }

A mounts lambda runs before each run, with chat and the agent’s inputs in scope, like the agent’s other lambdas.

compaction (options = {})

Source

# File lib/ruby_llm/agent.rb, line 289
def compaction(options = {})
  options = {} if options == true
  unless options == false || options.is_a?(Hash)
    raise ArgumentError, 'compaction accepts true, false, or compaction options'
  end

  @compaction = options
end

Enables context compaction for chats this agent builds, applied via Chat#with_compaction. With no options, the provider’s own defaults apply. Pass false to disable it.

compaction
compaction false
compaction at: 50_000

context (value = nil, &block)

Source

# File lib/ruby_llm/agent.rb, line 479
def context(value = nil, &block)
  raise ArgumentError, 'Pass a context or a block, not both' if value && block

  validate_context_proc(value)

  return @context if value.nil? && !block

  @context = if block
               block.arity.zero? ? block : RubyLLM.context(&block)
             else
               value
             end
end

Sets a Context whose configuration chats this agent builds should use, applied via Chat#with_context. A block taking a configuration argument creates an isolated Context when the agent class is defined. A zero-argument block or Proc value defers evaluation until a chat is built or configured, with declared ::inputs available as methods. In plain Ruby, chat is nil; in Rails mode, chat is the record being configured. Called with no argument or block, returns the configured context or deferred Proc.

context SharedContext
context { |config| config.request_timeout = 180 }
context -> { RubyLLM.context { |config| config.openai_api_key = api_key } }

create (**)

Source

# File lib/ruby_llm/agent.rb, line 618
def create(**)
  with_rails_chat_record(:create, **)
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! (**)

Source

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

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

chat = WorkAssistant.create!(user: current_user)

end_user (value = nil, &block)

Source

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

  @end_user = block || value
end

Sets the safety identifier for chats this agent builds, applied via Chat#with_end_user. A block defers evaluation until the chat is built, so the id can come from the agent’s inputs. Called with no arguments, returns the configured value.

end_user "tenant-42"
end_user { workspace.public_id }

fallbacks (*models, on: Fallback::DEFAULT_ERRORS)

Source

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

  @fallbacks = models.flatten.compact
  @fallback_options = { on: }
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]

file_store(store = default, spill_to_file: 10_000, owner: nil)

Source

# File lib/ruby_llm/agent.rb, line 333
def file_store(store = Chat::FileReferences::DEFAULT_STORE, spill_to_file: Chat::FileReferences::SPILL_TO_FILE,
               owner: nil)
  return @file_store = false if store.nil?

  Chat::FileReferences.validate(store, spill_to_file:, store_lambda: true)
  @file_store = { store:, spill_to_file:, owner: }.compact.freeze
end

Attaches a FileStore to chats this agent builds, with the tools to work with it, applied via Chat#with_file_store, which takes the same arguments. A store lambda runs once for each chat, with chat and the agent’s inputs in scope, like the agent’s other lambdas, and so does an owner lambda for a persisted chat. Pass nil to remove the store a parent agent declared.

file_store
file_store spill_to_file: 20_000
file_store -> { RubyLLM.file_store.directory("tmp/chats/#{chat.id}") }
file_store owner: -> { chat.user }
file_store nil

Each chat gets a store of its own: without store, a new FileStore::Memory, or for a persisted chat, its files in Active Storage.

find (id, **kwargs)

Source

# File lib/ruby_llm/agent.rb, line 638
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 422
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 514
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, append: false, persist: true, cache_until_here: false, **prompt_locals, &block)

Source

# File lib/ruby_llm/agent.rb, line 226
def instructions(text = nil, append: false, persist: true, cache_until_here: false, **prompt_locals, &block)
  return instruction_declarations if text.nil? && prompt_locals.empty? && !block_given?

  (@instruction_declarations ||= []) << {
    value: block || text || { prompt: 'instructions', locals: prompt_locals },
    append: append,
    persist: persist,
    cache_until_here: cache_until_here
  }
end

Adds 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). Multiple declarations are applied in order.

instructions "You are a helpful assistant."
instructions { "You are helping #{workspace.name}" }
instructions display_name: -> { chat.user.display_name_or_email }
instructions append: true, persist: false do
  "Today is #{Date.current}"
end

The class’s own declarations take precedence over its conventional template. Inherited declarations are used only when neither exists. In Rails mode, declarations persist when the record is created unless persist: false; ::find always reapplies them without rewriting history. Called with no arguments, returns the declarations.

max_output_tokens(value = nil)

Source

# File lib/ruby_llm/agent.rb, line 255
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

mcp (*servers, defer: nil, &block)

Source

# File lib/ruby_llm/agent.rb, line 173
def mcp(*servers, defer: nil, &block)
  return @mcp || [] if servers.empty? && !block_given?

  @mcp_defer = defer
  @mcp = block_given? ? block : servers.flatten
end

Connects MCP servers to chats this agent builds, applied via Chat#with_mcp. A block defers construction until the chat is built, with the declared ::inputs available. Called with no arguments, returns the declared servers.

mcp Files
mcp { [Linear.new(user: user), Files] }

Pass defer: as Chat#with_mcp takes it, or a lambda that decides when the chat is built:

mcp GitHub, defer: true

model (model_id = nil, **options, &block)

Source

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

  model_value = block || model_id
  options[:model] = model_value unless model_value.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. A block picks the model when the chat is built, with the declared ::inputs available as methods. Called with no arguments, returns the configured chat keywords.

model "gpt-6-luna"
model "gpt-6.1-sol", provider: :openai, protocol: :responses
model { quality == :high ? "gpt-6.1-sol" : "gpt-6-luna" }

The block runs before the chat exists, so it can read inputs but not chat.

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

Source

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

  if chat
    @chat = chat
    self.class.apply_configuration(@chat, input_values:, persist_instructions:)
    return
  end

  context_value = self.class.resolved_context(inputs: input_values)
  @chat = self.class.build_chat(
    inputs: input_values,
    options: chat_options,
    resolved_context: context_value
  )
  self.class.apply_configuration(
    @chat,
    input_values:,
    persist_instructions:,
    resolved_context: context_value
  )
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 413
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 service_tier: "flex"

provider_tools (*tools, **tools_with_options, &block)

Source

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

  @provider_tools = block_given? ? block : RubyLLM::Tools::ProviderTools.normalize(tools, tools_with_options)
end

Enables provider-executed tools for chats this agent builds, applied via Chat#with_provider_tools. Accepts the same aliases, options, and raw Hashes; a block defers evaluation until the chat is built. Called with no arguments, returns the declared entries.

provider_tools :web_search
provider_tools web_search: { allowed_domains: ["ruby-lang.org"] }

rescue_from (*exception_classes, with: nil, &block)

Source

# File lib/ruby_llm/agent.rb, line 550
def rescue_from(*exception_classes, with: nil, &block)
  raise ArgumentError, 'rescue_from needs a handler: pass with: or a block' unless with || block
  raise ArgumentError, 'rescue_from takes with: or a block, not both' if with && block

  exception_classes.flatten.each do |exception_class|
    rescue_handlers << [rescue_handler_key(exception_class), with || block]
  end
end

Registers a handler for exceptions raised by the chat operations of this agent’s instances: ask, say, ask_later, complete, generate, run_tools, step, count_tokens, and compact. Name the handler with with: or pass a block; either runs on the agent instance, so the agent’s chat, inputs, and class name are available for instrumentation.

class ApplicationAgent < RubyLLM::Agent
  rescue_from RubyLLM::RateLimitError, Faraday::TimeoutError, with: :handle_transient
  rescue_from RubyLLM::BadRequestError do |error|
    error_tracker.notify(error)
    raise
  end

  private

  def handle_transient(error)
    metrics.increment("llm.api_error", type: "transient")
    raise
  end
end

Handlers are searched in reverse declaration order, so the last matching one wins. Re-raise inside a handler to let the caller see the exception; otherwise the handler’s return value becomes the operation’s return value. Exceptions no handler matches are re-raised. Subclasses inherit the handlers declared when they are defined.

Exception classes may be named as Strings, which defers constant lookup until an exception is raised.

schema (value = nil, &block)

Source

# File lib/ruby_llm/agent.rb, line 440
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 Schematist::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

skills (*skills)

Source

# File lib/ruby_llm/agent.rb, line 353
def skills(*skills)
  return @skills if skills.empty?

  @skills = Skill.selection(skills)
end

Gives chats this agent builds the skills named, applied via Chat#with_skills when the chat is built. Symbols name folders under Skill.roots, Strings and Pathnames are paths to skill folders, true is every skill under the roots, and false removes the skills a parent agent declared. An agent without a skills declaration has no skills. Called with no arguments, returns the declaration: the names, true, false, or nil.

skills :invoices, :refunds
skills true
skills false

sync_instructions (chat_or_id, **kwargs)

Source

# File lib/ruby_llm/agent.rb, line 656
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)
  apply_context(record, runtime)
  apply_instructions(
    record,
    runtime,
    inputs: input_values,
    persist: true,
    persistent_only: true
  )
  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 238

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

temperature 0.2

thinking (enabled = true, **options)

Source

# File lib/ruby_llm/agent.rb, line 274
def thinking(enabled = true, **options) # rubocop:disable Style/OptionalBooleanParameter
  return thinking(**enabled.transform_keys(&:to_sym), **options) if enabled.is_a?(Hash)

  validate_thinking_options(enabled, options)
  @thinking = enabled ? options : false
end

Enables thinking for chats this agent builds, applied via Chat#with_thinking. With no options, RubyLLM chooses from the model’s registered controls. Accepts keywords or an options Hash. Pass false to disable it. Passing nil raises ArgumentError.

thinking
thinking false
thinking effort: :low
thinking budget: 10_000
thinking display: :summarized

tool_options (**options, &block)

Source

# File lib/ruby_llm/agent.rb, line 187
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, defer: nil, &block)

Source

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

  @tools_defer = defer
  @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)] }

Pass defer: as Chat#with_tools takes it, or a lambda that decides when the chat is built:

tools SearchDocs, LookupAccount, defer: true
tools(defer: -> { many_tools? }) { connected_tools }

Public Instance Methods

add_message(message_or_attributes)

Source

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

Delegates to Chat#add_message. See that method for arguments and return values.

after_dequeue(&block)

Source

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

Delegates to Chat#after_dequeue. See that method for arguments and return values.

after_fallback(&block)

Source

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

Delegates to Chat#after_fallback. See that method for arguments and return values.

after_file_write(&block)

Source

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

Delegates to Chat#after_file_write. See that method for arguments and return values.

after_message(&block)

Source

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

Delegates to Chat#after_message. See that method for arguments and return values.

after_queue(&block)

Source

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

Delegates to Chat#after_queue. See that method for arguments and return values.

after_tool_progress(&block)

Source

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

Delegates to Chat#after_tool_progress. See that method for arguments and return values.

after_tool_result(&block)

Source

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

Delegates to Chat#after_tool_result. See that method for arguments and return values.

after_unqueue(&block)

Source

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

Delegates to Chat#after_unqueue. See that method for arguments and return values.

answer(request, **values)

Source

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

Delegates to Chat#answer. See that method for arguments and return values.

approve(tool_call, remember: false)

Source

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

Delegates to Chat#approve. See that method for arguments and return values.

ask(message = nil, with: nil, &block)

Source

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

Delegates to Chat#ask, routing exceptions through the handlers declared with ::rescue_from.

ask_later(message = nil, with: nil)

Source

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

Stages a message through Chat#ask_later without calling the provider. Returns the wrapped chat. Exceptions use ::rescue_from handlers.

awaiting_approval?()

Source

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

Delegates to Chat#awaiting_approval?. See that method for arguments and return values.

awaiting_input?()

Source

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

Delegates to Chat#awaiting_input?. See that method for arguments and return values.

awaiting_tasks?()

Source

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

Delegates to Chat#awaiting_tasks?. See that method for arguments and return values.

before_fallback(&block)

Source

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

Delegates to Chat#before_fallback. See that method for arguments and return values.

before_message(&block)

Source

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

Delegates to Chat#before_message. See that method for arguments and return values.

before_request(&block)

Source

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

Delegates to Chat#before_request. See that method for arguments and return values.

before_tool_call(&block)

Source

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

Delegates to Chat#before_tool_call. See that method for arguments and return values.

cache_until_here(ttl: nil)

Source

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

Delegates to Chat#cache_until_here. See that method for arguments and return values.

caching

Source

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

Delegates to Chat#caching. See that method for arguments and return values.

cancel()

Source

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

Delegates to Chat#cancel. See that method for arguments and return values.

cancelled?()

Source

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

Delegates to Chat#cancelled?. See that method for arguments and return values.

citations

Source

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

Delegates to Chat#citations. See that method for arguments and return values.

code_execution

Source

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

Delegates to Chat#code_execution. See that method for arguments and return values.

compact

Source

# File lib/ruby_llm/agent.rb, line 1625
GUARDED_OPERATIONS.each do |operation|
  define_method(operation) do |*args, **kwargs, &block|
    chat.public_send(operation, *args, **kwargs, &block)
  rescue StandardError => e
    rescue_with_handler(e)
  end
end

Compacts the model context through Chat#compact and returns its Message. Exceptions use ::rescue_from handlers.

compaction

Source

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

Delegates to Chat#compaction. See that method for arguments and return values.

complete(&block)

Source

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

Delegates to Chat#complete, routing exceptions through the handlers declared with ::rescue_from.

complete?()

Source

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

Delegates to Chat#complete?. See that method for arguments and return values.

concurrency

Source

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

Delegates to Chat#concurrency. See that method for arguments and return values.

context

Source

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

Delegates to Chat#context. See that method for arguments and return values.

convert_unsupported_attachments(&block)

Source

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

Delegates to Chat#convert_unsupported_attachments. See that method for arguments and return values.

cost()

Source

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

Delegates to Chat#cost. See that method for arguments and return values.

count_tokens(message = nil)

Source

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

Counts request tokens through Chat#count_tokens without generating a response. Returns an Integer. Exceptions use ::rescue_from handlers.

decline(request)

Source

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

Delegates to Chat#decline. See that method for arguments and return values.

deferred_tools

Source

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

Delegates to Chat#deferred_tools. See that method for arguments and return values.

deny(tool_call)

Source

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

Delegates to Chat#deny. See that method for arguments and return values.

each(&block)

Source

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

Delegates to Chat#each. See that method for arguments and return values.

end_user

Source

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

Delegates to Chat#end_user. See that method for arguments and return values.

fallbacks

Source

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

Delegates to Chat#fallbacks. See that method for arguments and return values.

file_store

Source

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

Delegates to Chat#file_store. See that method for arguments and return values.

generate(&block)

Source

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

Generates one response through Chat#generate without executing tools. Returns a Message. Exceptions use ::rescue_from handlers.

headers

Source

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

Delegates to Chat#headers. See that method for arguments and return values.

max_output_tokens

Source

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

Returns Chat#max_output_tokens from the wrapped chat.

mcp

Source

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

Delegates to Chat#mcp. See that method for arguments and return values.

messages

Source

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

Delegates to Chat#messages. See that method for arguments and return values.

model

Source

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

Delegates to Chat#model. See that method for arguments and return values.

pending_approvals()

Source

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

Delegates to Chat#pending_approvals. See that method for arguments and return values.

pending_inputs()

Source

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

Delegates to Chat#pending_inputs. See that method for arguments and return values.

pending_tasks()

Source

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

Delegates to Chat#pending_tasks. See that method for arguments and return values.

provider

Source

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

Delegates to Chat#provider. See that method for arguments and return values.

provider_options

Source

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

Delegates to Chat#provider_options. See that method for arguments and return values.

provider_tools

Source

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

Delegates to Chat#provider_tools. See that method for arguments and return values.

queue(message = nil, with: nil, steer: true, owner: nil)

Source

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

Delegates to Chat#queue. See that method for arguments and return values.

queued_messages()

Source

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

Delegates to Chat#queued_messages. See that method for arguments and return values.

render()

Source

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

Delegates to Chat#render. See that method for arguments and return values.

rescue_with_handler (exception)

Source

# File lib/ruby_llm/agent.rb, line 1636
def rescue_with_handler(exception)
  handler = self.class.rescue_handler_for(exception)
  raise exception unless handler

  return instance_exec(exception, &handler) unless handler.is_a?(Symbol)

  handler_method = method(handler)
  handler_method.arity.zero? ? handler_method.call : handler_method.call(exception)
end

Runs the ::rescue_from handler matching exception and returns its value, or re-raises when no handler matches. The chat operations call this for you.

run_tools

Source

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

Runs pending tools through Chat#run_tools, respecting approval decisions. Returns the wrapped chat. Exceptions use ::rescue_from handlers.

say(message = nil, with: nil, &block)

Source

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

Delegates to Chat#say, the alias for Chat#ask, with ::rescue_from handling.

schema

Source

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

Delegates to Chat#schema. See that method for arguments and return values.

skills

Source

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

Delegates to Chat#skills. See that method for arguments and return values.

step(&block)

Source

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

Advances the conversation through Chat#step. Returns a Message or nil when no progress is possible. Exceptions use ::rescue_from handlers.

temperature

Source

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

Returns Chat#temperature from the wrapped chat.

thinking()

Source

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

Delegates to Chat#thinking. See that method for arguments and return values.

tokens()

Source

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

Delegates to Chat#tokens. See that method for arguments and return values.

tool_options()

Source

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

Delegates to Chat#tool_options. See that method for arguments and return values.

tools

Source

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

Delegates to Chat#tools. See that method for arguments and return values.

unqueue(queued)

Source

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

Delegates to Chat#unqueue. See that method for arguments and return values.

waiting?()

Source

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

Delegates to Chat#waiting?. See that method for arguments and return values.

with_caching(options = {})

Source

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

Delegates to Chat#with_caching. See that method for arguments and return values.

with_citations(enabled = true)

Source

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

Delegates to Chat#with_citations. See that method for arguments and return values.

with_code_execution(enabled = true, **options)

Source

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

Delegates to Chat#with_code_execution. See that method for arguments and return values.

with_compaction(options = {})

Source

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

Delegates to Chat#with_compaction. See that method for arguments and return values.

with_context(context)

Source

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

Delegates to Chat#with_context. See that method for arguments and return values.

with_end_user(end_user)

Source

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

Delegates to Chat#with_end_user. See that method for arguments and return values.

with_fallbacks(*models, on: Fallback::DEFAULT_ERRORS)

Source

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

Delegates to Chat#with_fallbacks. See that method for arguments and return values.

with_file_store(store = RubyLLM.file_store.memory, spill_to_file: 10_000)

Source

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

Delegates to Chat#with_file_store. See that method for arguments and return values.

with_headers(headers)

Source

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

Delegates to Chat#with_headers. See that method for arguments and return values.

with_instructions(instructions, append: false, cache_until_here: false)

Source

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

Delegates to Chat#with_instructions. See that method for arguments and return values.

with_max_output_tokens(max_output_tokens)

Source

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

Delegates to Chat#with_max_output_tokens. See that method for arguments and return values.

with_mcp(*servers, defer: nil)

Source

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

Delegates to Chat#with_mcp. See that method for arguments and return values.

with_model(model_id, provider: nil, protocol: nil, assume_model_exists: false)

Source

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

Delegates to Chat#with_model. See that method for arguments and return values.

with_provider_options(provider_options)

Source

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

Delegates to Chat#with_provider_options. See that method for arguments and return values.

with_provider_tools(*tools, **tools_with_options)

Source

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

Delegates to Chat#with_provider_tools. See that method for arguments and return values.

with_schema(schema)

Source

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

Delegates to Chat#with_schema. See that method for arguments and return values.

with_skills(*skills)

Source

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

Delegates to Chat#with_skills. See that method for arguments and return values.

with_temperature(temperature)

Source

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

Delegates to Chat#with_temperature. See that method for arguments and return values.

with_thinking(enabled = true, **options)

Source

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

Delegates to Chat#with_thinking. See that method for arguments and return values.

with_tool_options(**options)

Source

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

Delegates to Chat#with_tool_options. See that method for arguments and return values.

with_tools(*tools, defer: nil)

Source

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

Delegates to Chat#with_tools. See that method for arguments and return values.