# RubyLLM::Agent < Object --- # Includes: Enumerable --- # Extended by: Forwardable --- An Agent is a reusable chat configuration defined as a class. Subclasses declare a model, instructions, tools, and other settings once, then build configured chats wherever they are needed. class SupportAgent < RubyLLM::Agent model "gpt-5-nano" instructions "You are a concise support assistant." tools SearchDocs, LookupAccount end SupportAgent.new.ask "How do I reset my API key?" ::chat returns a configured Chat. When ::chat_model names an ActiveRecord chat class, ::create, ::create!, and ::find return configured records of that class instead. Configuration that depends on runtime state goes in blocks or lambdas. They are evaluated when a chat is built, with `chat` and any declared ::inputs available as methods: class WorkAssistant < RubyLLM::Agent inputs :workspace instructions { "You are helping #{workspace.name}" } end WorkAssistant.chat(workspace: workspace) Agent instances delegate the Chat API (#ask, #complete, #with_tools, and so on) to the wrapped chat, which is available via #chat. Agents are enumerable over their messages. --- # Class methods: caching chat chat_model citations context create create! fallbacks find headers inputs instructions max_output_tokens model new provider_options schema sync_instructions! temperature thinking tool_options tools # Instance methods: add_completion add_message after_fallback after_message after_tool_result ask ask_later before_fallback before_message before_tool_call caching chat complete complete? cost each generate headers messages model provider_options run_tools say schema step tools with_caching with_citations with_context with_fallbacks with_headers with_model with_provider_options with_schema with_temperature with_thinking with_tool_options with_tools without_caching without_citations without_context without_fallbacks without_headers without_provider_options without_schema without_temperature without_thinking without_tool_options without_tools # Attributes: attr_reader chat # RubyLLM::Agent::caching ### Implementation from Agent --- caching(**options, &block) --- Sets prompt caching options for chats this agent builds, applied via Chat#with_caching. A block defers evaluation until the chat is built. Called with no arguments, returns the configured value. caching ttl: "1h" # RubyLLM::Agent::chat ### Implementation from Agent --- chat(**kwargs) --- 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" # RubyLLM::Agent::chat_model ### Implementation from Agent --- chat_model(value = nil) --- 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 # RubyLLM::Agent::citations ### Implementation from Agent --- citations(value = nil) --- Enables or disables citations for chats this agent builds, applied via Chat#with_citations or Chat#without_citations. Called with no argument, returns the configured value. citations true # RubyLLM::Agent::context ### Implementation from Agent --- context(value = nil) --- Sets a Context whose configuration chats this agent builds should use, applied via Chat#with_context. Called with no argument, returns the configured context. # RubyLLM::Agent::create ### Implementation from Agent --- create(**kwargs) --- 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. # RubyLLM::Agent::create! ### Implementation from Agent --- create!(**kwargs) --- Like ::create, but calls the model's `create!`, raising if the record is invalid. chat = WorkAssistant.create!(user: current_user) # RubyLLM::Agent::fallbacks ### Implementation from Agent --- fallbacks(*models, **options) --- 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] # RubyLLM::Agent::find ### Implementation from Agent --- find(id, **kwargs) --- 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. # RubyLLM::Agent::headers ### Implementation from Agent --- headers(**headers, &block) --- 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. # RubyLLM::Agent::inputs ### Implementation from Agent --- inputs(*names) --- 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 # RubyLLM::Agent::instructions ### Implementation from Agent --- instructions(text = nil, **prompt_locals, &block) --- Sets system instructions for chats this agent builds. Accepts a string, a block evaluated when the chat is built, or keyword locals for the agent's conventional prompt template (for a WorkAssistant agent, `app/prompts/work_assistant/instructions.txt.erb`). instructions "You are a helpful assistant." instructions { "You are helping #{workspace.name}" } instructions display_name: -> { chat.user.display_name_or_email } A named agent uses its conventional template automatically when it exists, even without calling this method. Called with no arguments, returns the configured value. # RubyLLM::Agent::max_output_tokens ### Implementation from Agent --- max_output_tokens(value = nil) --- Caps the number of tokens chats this agent builds may generate. Called with no argument, returns the configured value. max_output_tokens 1000 # RubyLLM::Agent::model ### Implementation from Agent --- model(model_id = nil, **options) --- Sets the model used by chats this agent builds. Extra `options` are forwarded to RubyLLM.chat, including `provider:` to disambiguate the model and `protocol:` to override its wire protocol. Called with no arguments, returns the configured chat keywords. model "gpt-5-nano" model "gpt-5.4", provider: :openai, protocol: :responses # RubyLLM::Agent::new ### Implementation from Agent --- new(chat: nil, inputs: nil, persist_instructions: true, **kwargs) --- 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) # RubyLLM::Agent::provider_options ### Implementation from Agent --- provider_options(**provider_options, &block) --- Sets options in the provider's request vocabulary for chats this agent builds, applied via Chat#with_provider_options. A block defers evaluation until the chat is built. Called with no arguments, returns the configured value. provider_options max_output_tokens: 256 # RubyLLM::Agent::schema ### Implementation from Agent --- schema(value = nil, &block) --- Sets the structured output schema for chats this agent builds, applied via Chat#with_schema. Accepts a schema class, a JSON schema hash, or a block. A plain block is built with the RubyLLM::Schema DSL; a lambda is evaluated when the chat is built. Called with no arguments, returns the configured value. schema PersonSchema schema do string :verdict, enum: ["pass", "revise"] string :feedback end # RubyLLM::Agent::sync_instructions! ### Implementation from Agent --- sync_instructions!(chat_or_id, **kwargs) --- 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. # RubyLLM::Agent::temperature ### Implementation from Agent --- temperature(value = nil) --- Sets the sampling temperature for chats this agent builds. Called with no argument, returns the configured value. temperature 0.2 # RubyLLM::Agent::thinking ### Implementation from Agent --- thinking(effort: nil, budget: nil) --- Sets the thinking effort or budget for chats this agent builds, applied via Chat#with_thinking. Called with no arguments, returns the configured value. thinking effort: :low thinking budget: 10_000 # RubyLLM::Agent::tool_options ### Implementation from Agent --- tool_options(**options, &block) --- 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 # RubyLLM::Agent::tools ### Implementation from Agent --- tools(*tools, &block) --- 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)] } # RubyLLM::Agent#add_completion ### Implementation from Agent --- add_completion() --- Appends a completed response to the conversation. See Chat#add_completion. # RubyLLM::Agent#add_message ### Implementation from Agent --- add_message() --- Appends a message to the conversation. See Chat#add_message. # RubyLLM::Agent#after_fallback ### Implementation from Agent --- after_fallback() --- Registers a callback run after a fallback attempt. See Chat#after_fallback. # RubyLLM::Agent#after_message ### Implementation from Agent --- after_message() --- Registers a callback run after each assistant message. See Chat#after_message. # RubyLLM::Agent#after_tool_result ### Implementation from Agent --- after_tool_result() --- Registers a callback run after each tool result. See Chat#after_tool_result. # RubyLLM::Agent#ask ### Implementation from Agent --- ask() --- Sends a user message and returns the model's final response. See Chat#ask. # RubyLLM::Agent#ask_later ### Implementation from Agent --- ask_later() --- Stages a question without asking it. See Chat#ask_later. # RubyLLM::Agent#before_fallback ### Implementation from Agent --- before_fallback() --- Registers a callback run before trying a fallback model. See Chat#before_fallback. # RubyLLM::Agent#before_message ### Implementation from Agent --- before_message() --- Registers a callback run before each assistant message. See Chat#before_message. # RubyLLM::Agent#before_tool_call ### Implementation from Agent --- before_tool_call() --- Registers a callback run before each tool call. See Chat#before_tool_call. # RubyLLM::Agent#caching ### Implementation from Agent --- caching() --- Returns the prompt caching configuration. See Chat#caching. # RubyLLM::Agent#complete ### Implementation from Agent --- complete() --- Runs the agentic loop until nothing is left to do. See Chat#complete. # RubyLLM::Agent#complete? ### Implementation from Agent --- complete?() --- Returns whether the conversation needs no further work. See Chat#complete?. # RubyLLM::Agent#cost ### Implementation from Agent --- cost() --- Returns the accumulated cost of the conversation. See Chat#cost. # RubyLLM::Agent#each ### Implementation from Agent --- each() --- Yields each message in the conversation. See Chat#each. # RubyLLM::Agent#generate ### Implementation from Agent --- generate() --- Calls the model once and appends its response. See Chat#generate. # RubyLLM::Agent#headers ### Implementation from Agent --- headers() --- Returns the custom HTTP headers set on the chat. See Chat#headers. # RubyLLM::Agent#messages ### Implementation from Agent --- messages() --- Returns the messages exchanged so far. See Chat#messages. # RubyLLM::Agent#model ### Implementation from Agent --- model() --- Returns the Model::Info of the chat's model. See Chat#model. # RubyLLM::Agent#provider_options ### Implementation from Agent --- provider_options() --- Returns the provider request options set on the chat. See Chat#provider_options. # RubyLLM::Agent#run_tools ### Implementation from Agent --- run_tools() --- Executes the pending tool calls and appends their results. See Chat#run_tools. # RubyLLM::Agent#say ### Implementation from Agent --- say() --- Same as #ask. See Chat#say. # RubyLLM::Agent#schema ### Implementation from Agent --- schema() --- Returns the structured output schema set on the chat. See Chat#schema. # RubyLLM::Agent#step ### Implementation from Agent --- step() --- Advances the conversation by one move. See Chat#step. # RubyLLM::Agent#tools ### Implementation from Agent --- tools() --- Returns the tools registered on the chat. See Chat#tools. # RubyLLM::Agent#with_caching ### Implementation from Agent --- with_caching() --- Configures prompt caching. See Chat#with_caching. # RubyLLM::Agent#with_citations ### Implementation from Agent --- with_citations() --- Enables citations. See Chat#with_citations. # RubyLLM::Agent#with_context ### Implementation from Agent --- with_context() --- Applies a configuration Context. See Chat#with_context. # RubyLLM::Agent#with_fallbacks ### Implementation from Agent --- with_fallbacks() --- Configures fallback models. See Chat#with_fallbacks. # RubyLLM::Agent#with_headers ### Implementation from Agent --- with_headers() --- Sets custom HTTP headers. See Chat#with_headers. # RubyLLM::Agent#with_model ### Implementation from Agent --- with_model() --- Switches the chat to a different model. See Chat#with_model. # RubyLLM::Agent#with_provider_options ### Implementation from Agent --- with_provider_options() --- Sets options in the provider's request vocabulary. See Chat#with_provider_options. # RubyLLM::Agent#with_schema ### Implementation from Agent --- with_schema() --- Sets a structured output schema. See Chat#with_schema. # RubyLLM::Agent#with_temperature ### Implementation from Agent --- with_temperature() --- Sets the sampling temperature. See Chat#with_temperature. # RubyLLM::Agent#with_thinking ### Implementation from Agent --- with_thinking() --- Adjusts thinking effort or budget. See Chat#with_thinking. # RubyLLM::Agent#with_tool_options ### Implementation from Agent --- with_tool_options() --- Configures how the model uses its tools. See Chat#with_tool_options. # RubyLLM::Agent#with_tools ### Implementation from Agent --- with_tools() --- Registers tools on the chat. See Chat#with_tools. # RubyLLM::Agent#without_caching ### Implementation from Agent --- without_caching() --- Disables prompt caching. See Chat#without_caching. # RubyLLM::Agent#without_citations ### Implementation from Agent --- without_citations() --- Disables citations. See Chat#without_citations. # RubyLLM::Agent#without_context ### Implementation from Agent --- without_context() --- Returns the chat to the global configuration. See Chat#without_context. # RubyLLM::Agent#without_fallbacks ### Implementation from Agent --- without_fallbacks() --- Removes all fallback models. See Chat#without_fallbacks. # RubyLLM::Agent#without_headers ### Implementation from Agent --- without_headers() --- Removes all custom HTTP headers. See Chat#without_headers. # RubyLLM::Agent#without_provider_options ### Implementation from Agent --- without_provider_options() --- Removes all provider request options. See Chat#without_provider_options. # RubyLLM::Agent#without_schema ### Implementation from Agent --- without_schema() --- Removes the structured output schema. See Chat#without_schema. # RubyLLM::Agent#without_temperature ### Implementation from Agent --- without_temperature() --- Removes the temperature override. See Chat#without_temperature. # RubyLLM::Agent#without_thinking ### Implementation from Agent --- without_thinking() --- Clears the thinking configuration. See Chat#without_thinking. # RubyLLM::Agent#without_tool_options ### Implementation from Agent --- without_tool_options() --- Resets the tool options. See Chat#without_tool_options. # RubyLLM::Agent#without_tools ### Implementation from Agent --- without_tools() --- Removes all tools from the chat. See Chat#without_tools.