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.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 326
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 533
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 430
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 309
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

compaction (options = {})

Source

# File lib/ruby_llm/agent.rb, line 280
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 409
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 548
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 557
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 297
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 383
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 568
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 352
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 444
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 217
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 246
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 164
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 125
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-5.6-luna"
model "gpt-5.6", provider: :openai, protocol: :responses
model { quality == :high ? "gpt-5.6" : "gpt-5.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 925
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 343
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 192
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 480
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 370
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

sync_instructions (chat_or_id, **kwargs)

Source

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

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 265
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 178
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 145
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 1341

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

after_fallback(&block)

Source

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

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

after_message(&block)

Source

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

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 1101

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 1095

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 1137

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

approve(tool_call)

Source

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

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 1365

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 1385

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 1305

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

awaiting_input?()

Source

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

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

awaiting_tasks?()

Source

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

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

before_fallback(&block)

Source

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

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

before_message(&block)

Source

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

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

before_request(&block)

Source

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

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 1089

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 1149

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

caching

Source

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

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

cancel()

Source

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

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

cancelled?()

Source

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

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

citations

Source

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

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

compact

Source

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

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

complete(&block)

Source

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

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

complete?()

Source

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

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

concurrency

Source

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

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

context

Source

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

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

convert_unsupported_attachments(&block)

Source

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

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

cost()

Source

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

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

count_tokens(message = nil)

Source

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

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 1143

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

deferred_tools

Source

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

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

deny(tool_call)

Source

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

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

each(&block)

Source

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

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

end_user

Source

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

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

fallbacks

Source

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

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

generate(&block)

Source

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

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 1209

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

max_output_tokens

Source

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

Returns Chat#max_output_tokens from the wrapped chat.

mcp

Source

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

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

messages

Source

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

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

model

Source

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

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

pending_approvals()

Source

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

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

pending_inputs()

Source

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

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

pending_tasks()

Source

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

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

provider

Source

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

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

provider_options

Source

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

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

provider_tools

Source

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

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

render()

Source

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

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

rescue_with_handler (exception)

Source

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

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 1379

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

schema

Source

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

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

step(&block)

Source

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

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 1269

Returns Chat#temperature from the wrapped chat.

thinking()

Source

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

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

tokens()

Source

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

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

tool_options()

Source

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

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

tools

Source

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

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

waiting?()

Source

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

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

with_caching(options = {})

Source

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

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 1011

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

with_compaction(options = {})

Source

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

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

with_context(context)

Source

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

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 1017

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 1059

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

with_headers(headers)

Source

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

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 957

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 999

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 969

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 987

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 1041

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 975

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 1053

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

with_temperature(temperature)

Source

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

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 1005

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 981

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 963

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