ruby_llm-agents 3.11.0 → 3.12.0

data/lib/ruby_llm/agents/base_agent.rb

@@ -47,7 +47,8 @@ module RubyLLM
       extend DSL::Reliability
       extend DSL::Caching
       extend DSL::Queryable
-      extend DSL::Agents
+      extend DSL::Knowledge
+      include DSL::Knowledge::InstanceMethods
       include CacheHelper
 
       class << self
@@ -169,9 +170,9 @@ module RubyLLM
             description: description,
             schema: schema&.respond_to?(:name) ? schema.name : schema&.class&.name,
             tools: tools.map { |t| t.respond_to?(:name) ? t.name : t.to_s },
-            agents: agents_config.agent_entries.map { |e| e[:agent_class].name },
             parameters: params.transform_values { |v| v.slice(:type, :required, :default, :desc) },
             thinking: thinking_config,
+            cache_prompts: cache_prompts || nil,
             caching: caching_config,
             reliability: reliability_configured? ? reliability_config : nil
           }.compact
@@ -234,12 +235,18 @@ module RubyLLM
         # Enables or returns streaming mode for this agent
         #
         # @param value [Boolean, nil] Whether to enable streaming
+        # @param overridable [Boolean, nil] When true, this field can be changed from the dashboard
         # @return [Boolean] The current streaming setting
-        def streaming(value = nil)
+        def streaming(value = nil, overridable: nil)
           @streaming = value unless value.nil?
-          return @streaming unless @streaming.nil?
+          register_overridable(:streaming) if overridable
+          base = if @streaming.nil?
+            superclass.respond_to?(:streaming) ? superclass.streaming : default_streaming
+          else
+            @streaming
+          end
 
-          superclass.respond_to?(:streaming) ? superclass.streaming : default_streaming
+          apply_override(:streaming, base)
         end
 
         # @!endgroup
@@ -248,10 +255,10 @@ module RubyLLM
 
         # Sets or returns the tools available to this agent
         #
-        # @param tool_classes [Array<Class>] Tool classes to make available
+        # @param tool_classes [Class, Array<Class>] Tool classes to make available
         # @return [Array<Class>] The current tools
-        def tools(tool_classes = nil)
-          @tools = Array(tool_classes) if tool_classes
+        def tools(*tool_classes)
+          @tools = tool_classes.flatten if tool_classes.any?
           @tools || (superclass.respond_to?(:tools) ? superclass.tools : [])
         end
 
@@ -262,10 +269,14 @@ module RubyLLM
         # Sets or returns the temperature for LLM responses
         #
         # @param value [Float, nil] Temperature value (0.0-2.0)
+        # @param overridable [Boolean, nil] When true, this field can be changed from the dashboard
         # @return [Float] The current temperature setting
-        def temperature(value = nil)
+        def temperature(value = nil, overridable: nil)
           @temperature = value if value
-          @temperature || (superclass.respond_to?(:temperature) ? superclass.temperature : default_temperature)
+          register_overridable(:temperature) if overridable
+          base = @temperature || (superclass.respond_to?(:temperature) ? superclass.temperature : default_temperature)
+
+          apply_override(:temperature, base)
         end
 
         # @!endgroup
@@ -389,23 +400,19 @@ module RubyLLM
       # System prompt for LLM instructions
       #
       # If a class-level `system` DSL is defined, it will be used.
-      # When `agents` are declared, auto-generated sections describing
-      # direct tools and agent delegates are appended.
+      # Knowledge entries declared via `knows` are auto-appended.
       #
       # @return [String, nil] System instructions, or nil for none
       def system_prompt
-        base = base_system_prompt
-        append_agents_system_prompt(base)
-      end
-
-      # Returns the raw system prompt without agent/tool sections
-      #
-      # @return [String, nil]
-      def base_system_prompt
         system_config = self.class.system_config
-        return resolve_prompt_from_config(system_config) if system_config
+        base = system_config ? resolve_prompt_from_config(system_config) : nil
 
-        nil
+        knowledge = compiled_knowledge
+        if knowledge.present?
+          base ? "#{base}\n\n#{knowledge}" : knowledge
+        else
+          base
+        end
       end
 
       # Assistant prefill to prime the model's response
@@ -564,41 +571,6 @@ module RubyLLM
         end
       end
 
-      # Appends auto-generated agent/tool sections to the system prompt
-      # when agents are declared via the `agents` DSL.
-      #
-      # @param base [String, nil] The base system prompt
-      # @return [String, nil] System prompt with agent sections appended
-      def append_agents_system_prompt(base)
-        config = self.class.agents_config
-        return base if config.agent_entries.empty?
-
-        all_tools = resolved_tools
-        tools = all_tools.reject { |t| t.respond_to?(:agent_delegate?) && t.agent_delegate? }
-        agents = all_tools.select { |t| t.respond_to?(:agent_delegate?) && t.agent_delegate? }
-
-        sections = [base].compact
-
-        if tools.any?
-          sections << "\n## Direct Tools"
-          sections << "Fast, local operations:\n"
-          sections << tools.map { |t| "- #{tool_name_for(t)}: #{tool_description_for(t)}" }.join("\n")
-        end
-
-        if agents.any?
-          sections << "\n## Agents"
-          sections << "Specialized AI agents for substantial tasks."
-          sections << "Multiple agents can work simultaneously when called in the same turn.\n"
-          sections << agents.map { |t| "- #{tool_name_for(t)}: #{tool_description_for(t)}" }.join("\n")
-        end
-
-        if config.instructions_text
-          sections << "\n#{config.instructions_text}"
-        end
-
-        sections.join("\n")
-      end
-
       # Returns the description for a tool class
       #
       # @param tool [Class] A tool class
@@ -615,58 +587,19 @@ module RubyLLM
 
       # Resolves tools for this execution
       #
-      # Agent classes in the tools list are automatically wrapped as
-      # RubyLLM::Tool subclasses via AgentTool.for. Regular tool classes
-      # pass through unchanged.
-      #
       # @return [Array<Class>] Tool classes to use
       # @raise [ArgumentError] If duplicate tool names are detected
       def resolved_tools
-        raw = if self.class.method_defined?(:tools, false)
+        all_tools = if self.class.method_defined?(:tools, false)
           tools
         else
           self.class.tools
         end
 
-        regular_tools = raw.map { |tool_class| wrap_if_agent(tool_class) }
-        agent_tools = resolve_agent_list
-
-        all_tools = regular_tools + agent_tools
         detect_duplicate_tool_names!(all_tools)
         all_tools
       end
 
-      # Wraps agent classes from the `agents` DSL as AgentTool instances
-      # with `agent_delegate?` marker, forwarded params, and description overrides.
-      #
-      # @return [Array<Class>] Wrapped agent tool classes
-      def resolve_agent_list
-        config = self.class.agents_config
-        return [] if config.agent_entries.empty?
-
-        config.agent_entries.map do |entry|
-          agent_class = entry[:agent_class]
-          AgentTool.for(
-            agent_class,
-            forwarded_params: config.forwarded_params,
-            description_override: config.description_for(agent_class),
-            delegate: true
-          )
-        end
-      end
-
-      # Wraps an agent class as a tool, or returns the tool class as-is.
-      #
-      # @param tool_class [Class] A tool or agent class
-      # @return [Class] The original or wrapped class
-      def wrap_if_agent(tool_class)
-        if tool_class.respond_to?(:ancestors) && tool_class.ancestors.include?(RubyLLM::Agents::BaseAgent)
-          AgentTool.for(tool_class)
-        else
-          tool_class
-        end
-      end
-
       # Raises if two tools resolve to the same name.
       #
       # @param tools [Array] Resolved tool classes or instances
@@ -806,7 +739,7 @@ module RubyLLM
         @context = context
         client = build_client(context)
 
-        # Make context available to AgentTool instances during tool execution
+        # Make context available to Tool instances during tool execution
         previous_context = Thread.current[:ruby_llm_agents_caller_context]
         Thread.current[:ruby_llm_agents_caller_context] = context
 
@@ -843,9 +776,20 @@ module RubyLLM
         end
         client = client.with_temperature(temperature)
 
-        client = client.with_instructions(system_prompt) if system_prompt
+        use_prompt_caching = self.class.cache_prompts && anthropic_model?(effective_model)
+
+        if system_prompt
+          sys_content = if use_prompt_caching
+            RubyLLM::Providers::Anthropic::Content.new(system_prompt, cache: true)
+          else
+            system_prompt
+          end
+          client = client.with_instructions(sys_content)
+        end
+
         client = client.with_schema(schema) if schema
         client = client.with_tools(*resolved_tools) if resolved_tools.any?
+        apply_tool_prompt_caching(client) if use_prompt_caching && resolved_tools.any?
         client = setup_tool_tracking(client) if resolved_tools.any?
         client = apply_messages(client, resolved_messages) if resolved_messages.any?
         client = client.with_thinking(**resolved_thinking) if resolved_thinking
@@ -959,6 +903,14 @@ module RubyLLM
         # Store tracked tool calls in context for instrumentation
         context[:tool_calls] = @tracked_tool_calls if @tracked_tool_calls.any?
 
+        # Capture Anthropic prompt caching metrics
+        if response.respond_to?(:cached_tokens) && response.cached_tokens&.positive?
+          context[:cached_tokens] = response.cached_tokens
+        end
+        if response.respond_to?(:cache_creation_tokens) && response.cache_creation_tokens&.positive?
+          context[:cache_creation_tokens] = response.cache_creation_tokens
+        end
+
         calculate_costs(response, context) if context.input_tokens
       end
 
@@ -993,6 +945,37 @@ module RubyLLM
         nil
       end
 
+      # Checks whether the given model is served by Anthropic
+      #
+      # Looks up the model's provider in the registry, falling back to
+      # model ID pattern matching when the registry is unavailable.
+      #
+      # @param model_id [String] The model ID
+      # @return [Boolean]
+      def anthropic_model?(model_id)
+        info = find_model_info(model_id)
+        return info.provider.to_s == "anthropic" if info&.provider
+
+        # Fallback: match common Anthropic model ID patterns
+        model_id.to_s.match?(/\Aclaude/i)
+      end
+
+      # Adds cache_control to the last tool so Anthropic caches all tool definitions
+      #
+      # Uses a singleton method override on the last tool instance so the
+      # cache_control is merged into the API payload by RubyLLM's
+      # Tools.function_for without mutating the tool class.
+      #
+      # @param client [RubyLLM::Chat] The chat client with tools already added
+      def apply_tool_prompt_caching(client)
+        last_tool = client.tools.values.last
+        return unless last_tool
+
+        last_tool.define_singleton_method(:provider_params) do
+          super().merge(cache_control: {type: "ephemeral"})
+        end
+      end
+
       # Builds a Result object from the response
       #
       # @param content [Object] The processed content
@@ -1087,35 +1070,18 @@ module RubyLLM
         client
           .on_tool_call do |tool_call|
             start_tracking_tool_call(tool_call)
-            name = extract_tool_call_value(tool_call, :name)
-            event_type = agent_delegate_name?(name) ? :agent_start : :tool_start
-            emit_stream_event(event_type, tool_call_start_data(tool_call))
+            emit_stream_event(:tool_start, tool_call_start_data(tool_call))
           end
           .on_tool_result do |result|
-            name = @pending_tool_call&.dig(:name)
-            event_type = agent_delegate_name?(name) ? :agent_end : :tool_end
             end_data = tool_call_end_data(result)
             complete_tool_call_tracking(result)
-            emit_stream_event(event_type, end_data)
+            emit_stream_event(:tool_end, end_data)
           end
       end
 
-      # Checks whether a tool name corresponds to an agent delegate
-      #
-      # @param tool_name [String] The tool name
-      # @return [Boolean]
-      def agent_delegate_name?(tool_name)
-        return false unless tool_name
-
-        resolved_tools.any? do |t|
-          t.respond_to?(:agent_delegate?) && t.agent_delegate? &&
-            tool_name_for(t) == tool_name
-        end
-      end
-
       # Emits a StreamEvent to the caller's stream block when stream_events is enabled
       #
-      # @param type [Symbol] Event type (:chunk, :tool_start, :tool_end, :agent_start, :agent_end, :error)
+      # @param type [Symbol] Event type (:chunk, :tool_start, :tool_end, :error)
       # @param data [Hash] Event-specific data
       def emit_stream_event(type, data)
         return unless @context&.stream_block && @context.stream_events?
@@ -1123,27 +1089,18 @@ module RubyLLM
         @context.stream_block.call(StreamEvent.new(type, data))
       end
 
-      # Builds data hash for a tool_start/agent_start event
+      # Builds data hash for a tool_start event
       #
       # @param tool_call [Object] The tool call object from RubyLLM
       # @return [Hash] Event data
       def tool_call_start_data(tool_call)
-        name = extract_tool_call_value(tool_call, :name)
-        data = {
-          tool_name: name,
+        {
+          tool_name: extract_tool_call_value(tool_call, :name),
           input: extract_tool_call_value(tool_call, :arguments) || {}
-        }
-
-        if agent_delegate_name?(name)
-          agent_tool = resolved_tools.find { |t| tool_name_for(t) == name && t.respond_to?(:agent_class) }
-          data[:agent_name] = name
-          data[:agent_class] = agent_tool&.agent_class&.name
-        end
-
-        data.compact
+        }.compact
       end
 
-      # Builds data hash for a tool_end/agent_end event from the pending tool call
+      # Builds data hash for a tool_end event from the pending tool call
       #
       # @param result [Object] The tool result
       # @return [Hash] Event data

data/lib/ruby_llm/agents/core/base.rb

@@ -72,8 +72,13 @@ module RubyLLM
       # @param context [Pipeline::Context] The execution context
       # @return [void] Sets context.output with the result
       def execute(context)
+        @context = context
         @execution_started_at = context.started_at || Time.current
 
+        # Make context available to Tool instances during tool execution
+        previous_context = Thread.current[:ruby_llm_agents_caller_context]
+        Thread.current[:ruby_llm_agents_caller_context] = context
+
         # Run before_call callbacks
         run_callbacks(:before, context)
 
@@ -87,10 +92,14 @@ module RubyLLM
         run_callbacks(:after, context, response)
 
         context.output = build_result(processed_content, response, context)
+      rescue RubyLLM::Agents::CancelledError
+        context.output = Result.new(content: nil, cancelled: true)
       rescue RubyLLM::UnauthorizedError, RubyLLM::ForbiddenError => e
         raise_with_setup_hint(e, context)
       rescue RubyLLM::ModelNotFoundError => e
         raise_with_model_hint(e, context)
+      ensure
+        Thread.current[:ruby_llm_agents_caller_context] = previous_context
       end
 
       # Returns the resolved tenant ID for tracking

data/lib/ruby_llm/agents/core/configuration.rb

@@ -448,7 +448,8 @@ module RubyLLM
         :helicone_pricing_enabled,
         :helicone_pricing_url,
         :llmpricing_enabled,
-        :llmpricing_url
+        :llmpricing_url,
+        :knowledge_path
 
       # Attributes with validation (readers only, custom setters below)
       attr_reader :default_temperature,
@@ -752,6 +753,9 @@ module RubyLLM
         @elevenlabs_base_cost_per_1k = nil
         # ElevenLabs models cache TTL in seconds (6 hours)
         @elevenlabs_models_cache_ttl = 21_600
+
+        # Knowledge defaults
+        @knowledge_path = "app/agents/knowledge"
       end
 
       # Returns the configured cache store, falling back to Rails.cache

data/lib/ruby_llm/agents/core/version.rb

@@ -4,6 +4,6 @@ module RubyLLM
   module Agents
     # Current version of the RubyLLM::Agents gem
     # @return [String] Semantic version string
-    VERSION = "3.11.0"
+    VERSION = "3.12.0"
   end
 end

data/lib/ruby_llm/agents/dsl/base.rb

@@ -43,6 +43,13 @@ module RubyLLM
       #
       #   RubyExpert.ask("What is metaprogramming?")
       #
+      # @example Dashboard-overridable settings
+      #   class SupportAgent < RubyLLM::Agents::BaseAgent
+      #     model "gpt-4o", overridable: true        # can be changed from the dashboard
+      #     temperature 0.7, overridable: true        # can be changed from the dashboard
+      #     timeout 30                                # locked to code value
+      #   end
+      #
       # @example Dynamic prompts with method overrides
       #   class SmartAgent < RubyLLM::Agents::BaseAgent
       #     def system_prompt
@@ -63,12 +70,18 @@ module RubyLLM
         # Sets or returns the LLM model for this agent class
         #
         # @param value [String, nil] The model identifier to set
+        # @param overridable [Boolean, nil] When true, this field can be changed from the dashboard
         # @return [String] The current model setting
         # @example
         #   model "gpt-4o"
-        def model(value = nil)
+        # @example Dashboard-overridable
+        #   model "gpt-4o", overridable: true
+        def model(value = nil, overridable: nil)
           @model = value if value
-          @model || inherited_or_default(:model, default_model)
+          register_overridable(:model) if overridable
+          base = @model || inherited_or_default(:model, default_model)
+
+          apply_override(:model, base)
         end
 
         # Sets the user prompt template
@@ -206,12 +219,45 @@ module RubyLLM
         # Sets or returns the timeout in seconds for LLM requests
         #
         # @param value [Integer, nil] Timeout in seconds
+        # @param overridable [Boolean, nil] When true, this field can be changed from the dashboard
         # @return [Integer] The current timeout setting
         # @example
         #   timeout 30
-        def timeout(value = nil)
+        # @example Dashboard-overridable
+        #   timeout 30, overridable: true
+        def timeout(value = nil, overridable: nil)
           @timeout = value if value
-          @timeout || inherited_or_default(:timeout, default_timeout)
+          register_overridable(:timeout) if overridable
+          base = @timeout || inherited_or_default(:timeout, default_timeout)
+
+          apply_override(:timeout, base)
+        end
+
+        # Enables Anthropic prompt caching for this agent
+        #
+        # When enabled, adds cache_control breakpoints to the system prompt
+        # and the last tool definition so Anthropic caches them across
+        # multi-turn agent loops. This reduces input token costs by ~90%
+        # on subsequent calls within the same cache window (~5 minutes).
+        #
+        # Only takes effect when the resolved model is served by Anthropic.
+        # Non-Anthropic models silently ignore this setting.
+        #
+        # @param value [Boolean, nil] Whether to enable prompt caching
+        # @return [Boolean] The current setting
+        #
+        # @example
+        #   class BuildAgent < ApplicationAgent
+        #     cache_prompts true
+        #     system "You are a build assistant."
+        #     tools BuildTool, TestTool, DeployTool
+        #   end
+        #
+        def cache_prompts(value = nil)
+          @cache_prompts = value unless value.nil?
+          return @cache_prompts if defined?(@cache_prompts) && !@cache_prompts.nil?
+
+          inherited_or_default(:cache_prompts, false)
         end
 
         # Sets or returns the response schema for structured output
@@ -259,6 +305,47 @@ module RubyLLM
 
         # @!endgroup
 
+        # @!group Dashboard Override Support
+
+        # Returns which fields are overridable for this agent
+        #
+        # @return [Array<Symbol>] The list of overridable field names
+        def overridable_fields
+          own = @overridable_fields || []
+          inherited = superclass.respond_to?(:overridable_fields) ? superclass.overridable_fields : []
+          (own + inherited).uniq
+        end
+
+        # Returns true if any field is overridable from the dashboard
+        #
+        # @return [Boolean]
+        def overridable?
+          overridable_fields.any?
+        end
+
+        # Returns the currently active dashboard overrides for this agent
+        #
+        # Only returns overrides for fields that are declared overridable.
+        #
+        # @return [Hash{String => Object}] Active override values
+        def active_overrides
+          return {} unless overridable?
+
+          raw = load_overrides
+          raw.select { |field, _| overridable_fields.include?(field.to_sym) }
+        end
+
+        # Clears the in-memory override cache so the next access reloads from DB
+        #
+        # Called automatically by AgentOverride after_save/after_destroy callbacks.
+        #
+        # @return [void]
+        def clear_override_cache!
+          @_override_cache = nil
+        end
+
+        # @!endgroup
+
         private
 
         # Auto-registers parameters found in prompt template placeholders
@@ -310,6 +397,46 @@ module RubyLLM
         rescue
           120
         end
+
+        # Registers a field as overridable from the dashboard
+        #
+        # @param field [Symbol] The field name
+        # @return [void]
+        def register_overridable(field)
+          @overridable_fields = (@overridable_fields || []) | [field]
+        end
+
+        # Applies a dashboard override if the field is overridable and an override exists
+        #
+        # @param field [Symbol] The field name
+        # @param base [Object] The code-defined value to use as fallback
+        # @return [Object] The override value, or the base value
+        def apply_override(field, base)
+          return base unless overridable_fields.include?(field)
+
+          override = resolve_override(field)
+          override.nil? ? base : override
+        end
+
+        # Fetches the override value for a single field from the cached override hash
+        #
+        # @param field [Symbol] The field name
+        # @return [Object, nil] The override value, or nil
+        def resolve_override(field)
+          @_override_cache = load_overrides unless defined?(@_override_cache) && @_override_cache
+          @_override_cache[field.to_s]
+        end
+
+        # Loads all overrides for this agent from the database
+        #
+        # @return [Hash{String => Object}] The override settings hash
+        def load_overrides
+          return {} unless defined?(RubyLLM::Agents::AgentOverride)
+
+          RubyLLM::Agents::AgentOverride.find_by(agent_type: name)&.settings || {}
+        rescue
+          {}
+        end
       end
     end
   end