ruby_llm-agents 3.11.0 → 3.13.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

@@ -50,9 +50,26 @@ module RubyLLM
       #   When false, executions are logged synchronously.
       #   @return [Boolean] Enable async logging (default: true)
 
+      # @!attribute [rw] soft_purge_after
+      #   How long to keep full execution details (prompts, responses, tool calls,
+      #   attempts) before the retention job destroys them. The executions row is
+      #   preserved so cost, token, and latency analytics remain intact. A
+      #   truncated copy of the error message is stamped into metadata for
+      #   long-term error-rate trend analysis.
+      #   Set to nil to disable soft purging.
+      #   @return [ActiveSupport::Duration, nil] Soft-purge window (default: 30.days)
+
+      # @!attribute [rw] hard_purge_after
+      #   How long to keep the executions row itself before the retention job
+      #   destroys it entirely. Must be greater than soft_purge_after when both
+      #   are set. Set to nil to retain executions indefinitely.
+      #   @return [ActiveSupport::Duration, nil] Hard-purge window (default: 365.days)
+
       # @!attribute [rw] retention_period
-      #   How long to retain execution records before cleanup.
-      #   @return [ActiveSupport::Duration] Retention period (default: 30.days)
+      #   Deprecated. Alias for hard_purge_after, kept for backward compatibility.
+      #   Prefer configuring soft_purge_after and hard_purge_after explicitly.
+      #   @return [ActiveSupport::Duration, nil] Hard-purge window
+      #   @deprecated Use {#hard_purge_after} instead.
 
       # @!attribute [rw] anomaly_cost_threshold
       #   Cost threshold in dollars that triggers anomaly logging.
@@ -379,7 +396,6 @@ module RubyLLM
       # Attributes without validation (simple accessors)
       attr_accessor :default_model,
         :async_logging,
-        :retention_period,
         :dashboard_parent_controller,
         :basic_auth_username,
         :basic_auth_password,
@@ -448,7 +464,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,
@@ -463,7 +480,9 @@ module RubyLLM
         :tenant_resolver,
         :tenant_config_resolver,
         :default_retries,
-        :budgets
+        :budgets,
+        :soft_purge_after,
+        :hard_purge_after
 
       attr_writer :cache_store
 
@@ -593,6 +612,44 @@ module RubyLLM
         @default_embedding_batch_size = value
       end
 
+      # Sets soft_purge_after with validation
+      #
+      # @param value [ActiveSupport::Duration, Numeric, nil] Window or nil to disable
+      # @raise [ArgumentError] If value is not a Duration/Numeric or nil, or is negative
+      def soft_purge_after=(value)
+        validate_purge_window!(:soft_purge_after, value)
+        @soft_purge_after = value
+        validate_purge_ordering!
+      end
+
+      # Sets hard_purge_after with validation
+      #
+      # @param value [ActiveSupport::Duration, Numeric, nil] Window or nil to disable
+      # @raise [ArgumentError] If value is not a Duration/Numeric or nil, or is negative
+      def hard_purge_after=(value)
+        validate_purge_window!(:hard_purge_after, value)
+        @hard_purge_after = value
+        validate_purge_ordering!
+      end
+
+      # Deprecated alias for hard_purge_after.
+      #
+      # @return [ActiveSupport::Duration, nil]
+      # @deprecated Use {#hard_purge_after} instead.
+      def retention_period
+        hard_purge_after
+      end
+
+      # Deprecated setter for retention_period (maps to hard_purge_after).
+      #
+      # @param value [ActiveSupport::Duration, Numeric, nil]
+      # @deprecated Use {#hard_purge_after=} instead.
+      def retention_period=(value)
+        warn "[DEPRECATION] RubyLLM::Agents config.retention_period is deprecated. " \
+          "Use config.hard_purge_after instead (and set config.soft_purge_after for two-tier retention)."
+        self.hard_purge_after = value
+      end
+
       # Sets default_embedding_dimensions with validation
       #
       # @param value [Integer, nil] Dimensions (must be nil or > 0)
@@ -615,7 +672,8 @@ module RubyLLM
         @default_timeout = 60
         @cache_store = nil
         @async_logging = true
-        @retention_period = 30.days
+        @soft_purge_after = 30.days
+        @hard_purge_after = 365.days
         @anomaly_cost_threshold = 5.00
         @anomaly_duration_threshold = 10_000
         @dashboard_auth = ->(_controller) { true }
@@ -752,6 +810,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
@@ -956,7 +1017,8 @@ module RubyLLM
           },
           logging: {
             async_logging: async_logging,
-            retention_period: retention_period,
+            soft_purge_after: soft_purge_after,
+            hard_purge_after: hard_purge_after,
             job_retry_attempts: job_retry_attempts,
             track_executions: track_executions,
             track_cache_hits: track_cache_hits,
@@ -1157,6 +1219,30 @@ module RubyLLM
           raise ArgumentError, "budgets[:enforcement] must be :none, :soft, or :hard"
         end
       end
+
+      # Validates a purge-window value (Duration, Numeric seconds, or nil).
+      #
+      # @param attr [Symbol] Attribute name for error messages
+      # @param value [ActiveSupport::Duration, Numeric, nil] Value to validate
+      # @raise [ArgumentError] If value is neither nil nor a non-negative duration/number
+      def validate_purge_window!(attr, value)
+        return if value.nil?
+        return if value.is_a?(ActiveSupport::Duration) && value.to_i >= 0
+        return if value.is_a?(Numeric) && value >= 0
+
+        raise ArgumentError, "#{attr} must be an ActiveSupport::Duration, non-negative Numeric, or nil"
+      end
+
+      # Ensures soft_purge_after is strictly less than hard_purge_after when both are set.
+      #
+      # @raise [ArgumentError] If ordering is violated
+      def validate_purge_ordering!
+        return if @soft_purge_after.nil? || @hard_purge_after.nil?
+        return if @soft_purge_after.to_i < @hard_purge_after.to_i
+
+        raise ArgumentError, "soft_purge_after (#{@soft_purge_after.inspect}) must be less than " \
+          "hard_purge_after (#{@hard_purge_after.inspect})"
+      end
     end
   end
 end

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.13.0"
   end
 end