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 365
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 572
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 469
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 348
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 306
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 284
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 448
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 587
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 596
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 336
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, **options)

Source

# File lib/ruby_llm/agent.rb, line 422
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 607
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 391
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 483
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 221
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 250
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 168
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:

mcp GitHub, defer: true

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

Source

# File lib/ruby_llm/agent.rb, line 129
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 982
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 382
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 196
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 519
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 409
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 322
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 625
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 233

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 269
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 182
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 149
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:

tools SearchDocs, LookupAccount, defer: true

Public Instance Methods

add_message(message_or_attributes)

Source

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

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

after_fallback(&block)

Source

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

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

after_message(&block)

Source

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

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

after_tool_progress(&block)

Source

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

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 1164

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

answer(request, **values)

Source

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

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 1194

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 1446

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 1466

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 1386

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

awaiting_input?()

Source

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

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

awaiting_tasks?()

Source

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

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

before_fallback(&block)

Source

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

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

before_message(&block)

Source

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

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

before_request(&block)

Source

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

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 1158

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 1218

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

caching

Source

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

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

cancel()

Source

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

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

cancelled?()

Source

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

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

citations

Source

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

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

code_execution

Source

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

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

compact

Source

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

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

complete(&block)

Source

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

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

complete?()

Source

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

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

concurrency

Source

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

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

context

Source

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

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

convert_unsupported_attachments(&block)

Source

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

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

cost()

Source

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

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

count_tokens(message = nil)

Source

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

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 1212

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

deferred_tools

Source

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

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

deny(tool_call)

Source

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

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

each(&block)

Source

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

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

end_user

Source

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

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

fallbacks

Source

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

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

generate(&block)

Source

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

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 1278

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

max_output_tokens

Source

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

Returns Chat#max_output_tokens from the wrapped chat.

mcp

Source

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

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

messages

Source

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

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

model

Source

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

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

pending_approvals()

Source

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

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

pending_inputs()

Source

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

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

pending_tasks()

Source

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

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

provider

Source

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

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

provider_options

Source

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

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

provider_tools

Source

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

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

render()

Source

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

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

rescue_with_handler (exception)

Source

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

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 1460

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

schema

Source

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

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

skills

Source

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

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

step(&block)

Source

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

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 1350

Returns Chat#temperature from the wrapped chat.

thinking()

Source

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

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

tokens()

Source

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

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

tool_options()

Source

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

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

tools

Source

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

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

waiting?()

Source

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

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

with_caching(options = {})

Source

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

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 1068

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 1092

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 1080

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

with_context(context)

Source

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

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 1074

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 1128

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

with_headers(headers)

Source

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

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 1014

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 1056

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 1026

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 1044

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 1110

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 1032

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 1122

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

with_skills(*skills)

Source

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

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

with_temperature(temperature)

Source

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

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 1062

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 1038

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 1020

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