ruby_llm-agents 3.9.0 → 3.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6925b14509a50c3bbf5efb8d0e37f5a38b4d2f52f13f3c7ecd7af588f832c5c1
-  data.tar.gz: 4332d03ebaf4bd94f3e314656e7f6755475c5ad45661a8c1e76e6e324d37ec2e
+  metadata.gz: 2db1aa75b826b63dae9aec7ee8bee4e3597ce9dab4509e49dcd5cc6bdd8b3aa8
+  data.tar.gz: aa5b53d9558b0724ba89a39575b2ac2c3ba2eda550c87d3388f3f66cbda6d0e3
 SHA512:
-  metadata.gz: e12ea68a14b7c9ec683ae7b07a14d9d422922fc8e5233d7296fd42bc6100097bb929da87b6c52fe55929779a17c04e59253fa490c40147558392a32a79023fa6
-  data.tar.gz: 9d0d5d249ee0bb6bac741d5c1087ade27ba0a6d032184bb01e1ecfc0d43f79453fbd12cd22e9e4f3eeca7b457bfb242ebca7ebc4e010f44387b9ee8a13bf0865
+  metadata.gz: c5537dd90aaceadb9b0948687d3a1ed6635e5c93d8b82a2eae23f805dcb3fc14c32c37aa3fa7bf56a581b48ea72e0d8b0c730f750fc866a6fc4461d784a3ac49
+  data.tar.gz: ebbaa8c6c7cf7d27163fbd33c1436cd3332ebbc7069eef6a6b24b50d12e75fd7b962dfaba21faf94d52e8a7ba67a37073c33dc82c91058beb32d486ef3565fc8

data/app/models/ruby_llm/agents/execution.rb

@@ -74,6 +74,10 @@ module RubyLLM
       has_one :detail, class_name: "RubyLLM::Agents::ExecutionDetail",
         foreign_key: :execution_id, dependent: :destroy
 
+      # Individual tool call records (real-time tracking)
+      has_many :tool_executions, class_name: "RubyLLM::Agents::ToolExecution",
+        foreign_key: :execution_id, dependent: :destroy
+
       # Delegations so existing code keeps working transparently
       delegate :system_prompt, :user_prompt, :assistant_prompt, :response, :error_message,
         :messages_summary, :tool_calls, :attempts, :fallback_chain,

data/app/models/ruby_llm/agents/tool_execution.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Tracks individual tool calls within an agent execution.
+    #
+    # Created in real-time as each tool runs (INSERT on start, UPDATE on complete),
+    # enabling live dashboard views and queryable tool-level analytics.
+    #
+    # @example Querying tool executions
+    #   execution.tool_executions.where(status: "error")
+    #   ToolExecution.where(tool_name: "bash").where("duration_ms > ?", 10_000)
+    #
+    class ToolExecution < ::ActiveRecord::Base
+      self.table_name = "ruby_llm_agents_tool_executions"
+
+      VALID_STATUSES = %w[running success error timed_out cancelled].freeze
+
+      belongs_to :execution, class_name: "RubyLLM::Agents::Execution"
+
+      validates :tool_name, presence: true
+      validates :status, presence: true, inclusion: {in: VALID_STATUSES}
+    end
+  end
+end

data/lib/ruby_llm/agents/agent_tool.rb

@@ -11,19 +11,25 @@ module RubyLLM
       # Wraps an agent class as a RubyLLM::Tool subclass.
       #
       # @param agent_class [Class] A BaseAgent subclass
+      # @param forwarded_params [Array<Symbol>] Params auto-injected from parent (excluded from LLM schema)
+      # @param description_override [String, nil] Custom description for the tool
+      # @param delegate [Boolean] Whether this tool represents an agent delegate (from `agents` DSL)
       # @return [Class] An anonymous RubyLLM::Tool subclass
-      def self.for(agent_class)
+      def self.for(agent_class, forwarded_params: [], description_override: nil, delegate: false)
         tool_name = derive_tool_name(agent_class)
-        tool_desc = agent_class.respond_to?(:description) ? agent_class.description : nil
+        tool_desc = description_override || (agent_class.respond_to?(:description) ? agent_class.description : nil)
         agent_params = agent_class.respond_to?(:params) ? agent_class.params : {}
         captured_agent_class = agent_class
+        captured_forwarded = Array(forwarded_params).map(&:to_sym)
+        is_delegate = delegate
 
         Class.new(RubyLLM::Tool) do
           description tool_desc if tool_desc
 
-          # Map agent params to tool params
+          # Map agent params to tool params, excluding forwarded ones
           agent_params.each do |name, config|
             next if name.to_s.start_with?("_")
+            next if captured_forwarded.include?(name.to_sym)
 
             param name,
               desc: config[:desc] || "#{name} parameter",
@@ -34,6 +40,8 @@ module RubyLLM
           # Store references on the class
           define_singleton_method(:agent_class) { captured_agent_class }
           define_singleton_method(:tool_name) { tool_name }
+          define_singleton_method(:agent_delegate?) { is_delegate }
+          define_singleton_method(:forwarded_params) { captured_forwarded }
 
           # Instance #name returns the derived tool name
           define_method(:name) { tool_name }
@@ -54,6 +62,16 @@ module RubyLLM
               call_kwargs[:_parent_execution_id] = caller_ctx.execution_id
               call_kwargs[:_root_execution_id] = caller_ctx.root_execution_id || caller_ctx.execution_id
               call_kwargs[:tenant] = caller_ctx.tenant_object if caller_ctx.tenant_id && !call_kwargs.key?(:tenant)
+
+              # Inject forwarded params from the parent agent instance
+              if captured_forwarded.any? && caller_ctx.agent_instance
+                captured_forwarded.each do |param_name|
+                  next if call_kwargs.key?(param_name)
+                  if caller_ctx.agent_instance.respond_to?(param_name)
+                    call_kwargs[param_name] = caller_ctx.agent_instance.send(param_name)
+                  end
+                end
+              end
             end
 
             result = captured_agent_class.call(**call_kwargs)

data/lib/ruby_llm/agents/base_agent.rb

@@ -47,6 +47,7 @@ module RubyLLM
       extend DSL::Reliability
       extend DSL::Caching
       extend DSL::Queryable
+      extend DSL::Agents
       include CacheHelper
 
       class << self
@@ -168,6 +169,7 @@ 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,
             caching: caching_config,
@@ -387,10 +389,19 @@ module RubyLLM
       # System prompt for LLM instructions
       #
       # If a class-level `system` DSL is defined, it will be used.
-      # Otherwise returns nil.
+      # When `agents` are declared, auto-generated sections describing
+      # direct tools and agent delegates are 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
 
@@ -512,6 +523,7 @@ module RubyLLM
           tenant: resolve_tenant,
           skip_cache: @options[:skip_cache],
           stream_block: (block if streaming_enabled?),
+          stream_events: @options[:stream_events] == true,
           parent_execution_id: @parent_execution_id,
           root_execution_id: @root_execution_id,
           debug: @options[:debug],
@@ -552,6 +564,55 @@ 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
+      # @return [String] The tool's description
+      def tool_description_for(tool)
+        if tool.respond_to?(:description) && tool.description
+          tool.description
+        elsif tool.is_a?(Class) && tool < RubyLLM::Tool
+          tool.new.respond_to?(:description) ? tool.new.description : tool.name.to_s
+        else
+          tool.name.to_s
+        end
+      end
+
       # Resolves tools for this execution
       #
       # Agent classes in the tools list are automatically wrapped as
@@ -567,9 +628,31 @@ module RubyLLM
           self.class.tools
         end
 
-        wrapped = raw.map { |tool_class| wrap_if_agent(tool_class) }
-        detect_duplicate_tool_names!(wrapped)
-        wrapped
+        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.
@@ -720,6 +803,7 @@ module RubyLLM
       # @param context [Pipeline::Context] The execution context
       # @return [void] Sets context.output with the result
       def execute(context)
+        @context = context
         client = build_client(context)
 
         # Make context available to AgentTool instances during tool execution
@@ -730,6 +814,8 @@ module RubyLLM
         capture_response(response, context)
         result = build_result(process_response(response), response, context)
         context.output = result
+      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
@@ -815,7 +901,11 @@ module RubyLLM
 
           response = client.complete do |chunk|
             first_chunk_at ||= Time.current
-            context.stream_block.call(chunk)
+            if context.stream_events?
+              context.stream_block.call(StreamEvent.new(:chunk, {content: chunk.content}))
+            else
+              context.stream_block.call(chunk)
+            end
           end
 
           if first_chunk_at
@@ -841,7 +931,11 @@ module RubyLLM
 
         response = client.ask(user_prompt, **ask_opts) do |chunk|
           first_chunk_at ||= Time.current
-          context.stream_block.call(chunk)
+          if context.stream_events?
+            context.stream_block.call(StreamEvent.new(:chunk, {content: chunk.content}))
+          else
+            context.stream_block.call(chunk)
+          end
         end
 
         if first_chunk_at
@@ -991,8 +1085,80 @@ module RubyLLM
       # @return [RubyLLM::Chat] Client with tracking callbacks
       def setup_tool_tracking(client)
         client
-          .on_tool_call { |tool_call| start_tracking_tool_call(tool_call) }
-          .on_tool_result { |result| complete_tool_call_tracking(result) }
+          .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))
+          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)
+          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 data [Hash] Event-specific data
+      def emit_stream_event(type, data)
+        return unless @context&.stream_block && @context.stream_events?
+
+        @context.stream_block.call(StreamEvent.new(type, data))
+      end
+
+      # Builds data hash for a tool_start/agent_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,
+          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
+      end
+
+      # Builds data hash for a tool_end/agent_end event from the pending tool call
+      #
+      # @param result [Object] The tool result
+      # @return [Hash] Event data
+      def tool_call_end_data(result)
+        return {} unless @pending_tool_call
+
+        started_at = @pending_tool_call[:started_at]
+        duration_ms = started_at ? ((Time.current - started_at) * 1000).to_i : nil
+        result_data = extract_tool_result(result)
+
+        {
+          tool_name: @pending_tool_call[:name],
+          status: result_data[:status],
+          duration_ms: duration_ms
+        }.compact
       end
 
       # Starts tracking a tool call

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

@@ -387,6 +387,7 @@ module RubyLLM
         :default_total_timeout,
         :default_streaming,
         :default_tools,
+        :default_tool_timeout,
         :default_thinking,
         :on_alert,
         :persist_prompts,
@@ -639,6 +640,7 @@ module RubyLLM
         # Streaming, tools, and thinking defaults
         @default_streaming = false
         @default_tools = []
+        @default_tool_timeout = nil
         @default_thinking = nil
 
         # Governance defaults

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

@@ -29,6 +29,9 @@ module RubyLLM
     # Raised when an execution cannot be replayed
     class ReplayError < Error; end
 
+    # Raised when an agent execution is cancelled via on_cancelled
+    class CancelledError < Error; end
+
     # Raised when the TTS API returns an error response
     class SpeechApiError < Error
       attr_reader :status, :response_body

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.9.0"
+    VERSION = "3.11.0"
   end
 end

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

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    module DSL
+      # DSL module for declaring sub-agents on an agent class.
+      #
+      # Provides two forms — simple list for common cases, block for
+      # per-agent configuration:
+      #
+      # @example Simple form
+      #   agents [ModelsAgent, ViewsAgent], forward: [:workspace_path]
+      #
+      # @example Block form
+      #   agents do
+      #     use ModelsAgent, timeout: 180, description: "Build models"
+      #     use ViewsAgent
+      #     forward :workspace_path, :project_id
+      #     parallel true
+      #   end
+      #
+      module Agents
+        # Declares sub-agents for this agent class.
+        #
+        # @param list [Array<Class>, nil] Agent classes (simple form)
+        # @param options [Hash] Global options (simple form)
+        # @yield Configuration block (block form)
+        # @return [Array<Hash>] Agent entries
+        def agents(list = nil, **options, &block)
+          if block
+            config = AgentsConfig.new
+            config.instance_eval(&block)
+            @agents_config = config
+          elsif list
+            config = AgentsConfig.new
+            Array(list).each { |a| config.use(a) }
+            options.each { |k, v| config.send(k, *Array(v)) }
+            @agents_config = config
+          end
+          @agents_config&.agent_entries || []
+        end
+
+        # Returns the agents configuration object.
+        #
+        # @return [AgentsConfig] Configuration (empty if no agents declared)
+        def agents_config
+          @agents_config ||
+            (superclass.respond_to?(:agents_config) ? superclass.agents_config : nil) ||
+            AgentsConfig.new
+        end
+      end
+    end
+
+    # Configuration object for the `agents` DSL.
+    #
+    # Holds the list of agent entries and global options like
+    # `parallel`, `forward`, `max_depth`, and `instructions`.
+    #
+    class AgentsConfig
+      attr_reader :agent_entries
+
+      def initialize
+        @agent_entries = []
+        @options = {
+          parallel: true,
+          timeout: nil,
+          max_depth: 5,
+          forward: [],
+          instructions: nil
+        }
+      end
+
+      # Registers an agent class with optional per-agent overrides.
+      #
+      # @param agent_class [Class] A BaseAgent subclass
+      # @param timeout [Integer, nil] Per-agent timeout override
+      # @param description [String, nil] Per-agent description override
+      def use(agent_class, timeout: nil, description: nil)
+        @agent_entries << {
+          agent_class: agent_class,
+          timeout: timeout,
+          description: description
+        }
+      end
+
+      # @!group Global Options
+
+      def parallel(value = true)
+        @options[:parallel] = value
+      end
+
+      def timeout(seconds)
+        @options[:timeout] = seconds
+      end
+
+      def max_depth(depth)
+        @options[:max_depth] = depth
+      end
+
+      def instructions(text)
+        @options[:instructions] = text
+      end
+
+      def forward(*params)
+        @options[:forward] = params.flatten
+      end
+
+      # @!endgroup
+
+      # @!group Query Methods
+
+      def parallel?
+        @options[:parallel]
+      end
+
+      def timeout_for(agent_class)
+        entry = @agent_entries.find { |e| e[:agent_class] == agent_class }
+        entry&.dig(:timeout) || @options[:timeout]
+      end
+
+      def forwarded_params
+        @options[:forward]
+      end
+
+      def max_depth_value
+        @options[:max_depth]
+      end
+
+      def instructions_text
+        @options[:instructions]
+      end
+
+      def description_for(agent_class)
+        entry = @agent_entries.find { |e| e[:agent_class] == agent_class }
+        entry&.dig(:description)
+      end
+
+      # @!endgroup
+    end
+  end
+end

data/lib/ruby_llm/agents/dsl.rb

@@ -4,6 +4,7 @@ require_relative "dsl/base"
 require_relative "dsl/reliability"
 require_relative "dsl/caching"
 require_relative "dsl/queryable"
+require_relative "dsl/agents"
 
 module RubyLLM
   module Agents

data/lib/ruby_llm/agents/pipeline/context.rb

@@ -50,7 +50,7 @@ module RubyLLM
         attr_accessor :trace
 
         # Streaming support
-        attr_accessor :stream_block, :skip_cache
+        attr_accessor :stream_block, :skip_cache, :stream_events
 
         # Agent metadata
         attr_reader :agent_class, :agent_type
@@ -65,7 +65,7 @@ module RubyLLM
         # @param skip_cache [Boolean] Whether to skip caching
         # @param stream_block [Proc, nil] Block for streaming
         # @param options [Hash] Additional options passed to the agent
-        def initialize(input:, agent_class:, agent_instance: nil, model: nil, tenant: nil, skip_cache: false, stream_block: nil, parent_execution_id: nil, root_execution_id: nil, **options)
+        def initialize(input:, agent_class:, agent_instance: nil, model: nil, tenant: nil, skip_cache: false, stream_block: nil, stream_events: false, parent_execution_id: nil, root_execution_id: nil, **options)
           @input = input
           @agent_class = agent_class
           @agent_instance = agent_instance
@@ -87,6 +87,7 @@ module RubyLLM
           # Execution options
           @skip_cache = skip_cache
           @stream_block = stream_block
+          @stream_events = stream_events
 
           # Debug trace
           @trace = []
@@ -132,6 +133,13 @@ module RubyLLM
           @trace << {middleware: middleware_name, started_at: started_at, duration_ms: duration_ms, action: action}.compact
         end
 
+        # Are stream events enabled?
+        #
+        # @return [Boolean]
+        def stream_events?
+          @stream_events == true
+        end
+
         # Was the result served from cache?
         #
         # @return [Boolean]
@@ -243,6 +251,7 @@ module RubyLLM
             model: @model,
             skip_cache: @skip_cache,
             stream_block: @stream_block,
+            stream_events: @stream_events,
             **opts_without_tenant
           )
           # Preserve resolved tenant state

data/lib/ruby_llm/agents/pipeline/middleware/budget.rb

@@ -124,7 +124,7 @@ module RubyLLM
                 tenant.record_execution!(
                   cost: context.total_cost || 0,
                   tokens: context.total_tokens || 0,
-                  error: context.error?
+                  error: context.failed?
                 )
                 return
               end
@@ -146,8 +146,6 @@ module RubyLLM
                 tenant_id: context.tenant_id
               )
             end
-          rescue => e
-            error("Failed to record spend: #{e.message}", context)
           end
         end
       end

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

@@ -112,6 +112,11 @@ module RubyLLM
       #   @return [String, nil] The agent class that produced this result
       attr_reader :agent_class_name
 
+      # @!group Cancellation
+      # @!attribute [r] cancelled
+      #   @return [Boolean] Whether the execution was cancelled
+      attr_reader :cancelled
+
       # @!group Debug
       # @!attribute [r] trace
       #   @return [Array<Hash>, nil] Pipeline trace entries (when debug: true)
@@ -173,6 +178,9 @@ module RubyLLM
         # Tracking
         @agent_class_name = options[:agent_class_name]
 
+        # Cancellation
+        @cancelled = options[:cancelled] || false
+
         # Debug trace
         @trace = options[:trace]
 
@@ -222,6 +230,13 @@ module RubyLLM
         !success?
       end
 
+      # Returns whether the execution was cancelled
+      #
+      # @return [Boolean] true if cancelled
+      def cancelled?
+        cancelled == true
+      end
+
       # Returns whether a fallback model was used
       #
       # @return [Boolean] true if chosen_model_id differs from model_id

data/lib/ruby_llm/agents/routing/result.rb

@@ -5,15 +5,23 @@ module RubyLLM
     module Routing
       # Wraps a standard Result with routing-specific accessors.
       #
-      # Delegates all standard Result methods (tokens, cost, timing, etc.)
-      # to the underlying result, adding only the route-specific interface.
+      # When the route has an `agent:` mapping, the router auto-delegates
+      # to that agent. The delegated result is available via `delegated_result`,
+      # and `content` returns the delegated agent's content.
       #
-      # @example
+      # @example Classification only (no agent mapping)
       #   result = SupportRouter.call(message: "I was charged twice")
       #   result.route        # => :billing
-      #   result.agent_class  # => BillingAgent (if mapped)
-      #   result.success?     # => true
-      #   result.total_cost   # => 0.0001
+      #   result.delegated?   # => false
+      #
+      # @example Auto-delegation (with agent mapping)
+      #   result = SupportRouter.call(message: "I was charged twice")
+      #   result.route            # => :billing
+      #   result.delegated?       # => true
+      #   result.delegated_to     # => BillingAgent
+      #   result.content          # => BillingAgent's response content
+      #   result.routing_cost     # => cost of classification step
+      #   result.total_cost       # => classification + delegation
       #
       class RoutingResult < Result
         # @return [Symbol] The classified route name
@@ -25,6 +33,9 @@ module RubyLLM
         # @return [String] The raw text response from the LLM
         attr_reader :raw_response
 
+        # @return [Result, nil] The result from the delegated agent (if auto-delegated)
+        attr_reader :delegated_result
+
         # Creates a new RoutingResult by wrapping a base Result with route data.
         #
         # @param base_result [Result] The standard Result from BaseAgent execution
@@ -32,14 +43,32 @@ module RubyLLM
         # @option route_data [Symbol] :route The classified route name
         # @option route_data [Class, nil] :agent_class Mapped agent class
         # @option route_data [String] :raw_response Raw LLM text
+        # @option route_data [Result, nil] :delegated_result Result from auto-delegation
         def initialize(base_result:, route_data:)
+          @delegated_result = route_data[:delegated_result]
+          @routing_cost = base_result.total_cost
+
+          # When delegated, merge costs from both classification and delegation
+          total = if @delegated_result
+            (base_result.total_cost || 0) + (@delegated_result.respond_to?(:total_cost) ? @delegated_result.total_cost || 0 : 0)
+          else
+            base_result.total_cost
+          end
+
+          # Use delegated content when available
+          effective_content = if @delegated_result
+            @delegated_result.respond_to?(:content) ? @delegated_result.content : route_data
+          else
+            route_data
+          end
+
           super(
-            content: route_data,
+            content: effective_content,
             input_tokens: base_result.input_tokens,
             output_tokens: base_result.output_tokens,
             input_cost: base_result.input_cost,
             output_cost: base_result.output_cost,
-            total_cost: base_result.total_cost,
+            total_cost: total,
             model_id: base_result.model_id,
             chosen_model_id: base_result.chosen_model_id,
             temperature: base_result.temperature,
@@ -58,6 +87,27 @@ module RubyLLM
           @raw_response = route_data[:raw_response]
         end
 
+        # Whether the router auto-delegated to a mapped agent
+        #
+        # @return [Boolean]
+        def delegated?
+          !@delegated_result.nil?
+        end
+
+        # The agent class that was auto-invoked (alias for agent_class)
+        #
+        # @return [Class, nil]
+        def delegated_to
+          @agent_class if delegated?
+        end
+
+        # Cost of the classification step only (excluding delegation)
+        #
+        # @return [Float]
+        def routing_cost
+          @routing_cost || 0
+        end
+
         # Converts the result to a hash including routing fields.
         #
         # @return [Hash] All result data plus route, agent_class, raw_response
@@ -65,7 +115,8 @@ module RubyLLM
           super.merge(
             route: route,
             agent_class: agent_class&.name,
-            raw_response: raw_response
+            raw_response: raw_response,
+            delegated: delegated?
           )
         end
       end

data/lib/ruby_llm/agents/routing.rb

@@ -131,10 +131,29 @@ module RubyLLM
       end
 
       # Override build_result to return a RoutingResult.
+      # Auto-delegates to the mapped agent when the route has an `agent:` mapping.
       def build_result(content, response, context)
         base = super
+
+        # Auto-delegate to the mapped agent
+        agent_class = content[:agent_class]
+        if agent_class
+          content[:delegated_result] = agent_class.call(**delegation_params)
+        end
+
         RoutingResult.new(base_result: base, route_data: content)
       end
+
+      # Builds params to forward to the delegated agent.
+      # Forwards original message and custom params, excludes routing internals.
+      #
+      # @return [Hash] Params for the delegated agent
+      def delegation_params
+        forward = @options.except(:dry_run, :skip_cache, :debug, :stream_events)
+        forward[:_parent_execution_id] = @parent_execution_id if @parent_execution_id
+        forward[:_root_execution_id] = @root_execution_id if @root_execution_id
+        forward
+      end
     end
   end
 end

data/lib/ruby_llm/agents/stream_event.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Typed event emitted during streaming execution.
+    #
+    # When `stream_events: true` is passed to an agent call, the stream
+    # block receives StreamEvent objects instead of raw RubyLLM chunks.
+    # This provides visibility into the full execution lifecycle —
+    # text chunks, tool invocations, agent delegations, and errors.
+    #
+    # @example Basic usage
+    #   MyAgent.call(query: "test", stream_events: true) do |event|
+    #     case event.type
+    #     when :chunk       then print event.data[:content]
+    #     when :tool_start  then puts "Running #{event.data[:tool_name]}..."
+    #     when :tool_end    then puts "Done (#{event.data[:duration_ms]}ms)"
+    #     when :agent_start then puts "Delegated to #{event.data[:agent_name]}"
+    #     when :agent_end   then puts "Agent done (#{event.data[:duration_ms]}ms)"
+    #     when :error       then puts "Error: #{event.data[:message]}"
+    #     end
+    #   end
+    #
+    class StreamEvent
+      # @return [Symbol] Event type (:chunk, :tool_start, :tool_end,
+      #   :agent_start, :agent_end, :error)
+      attr_reader :type
+
+      # @return [Hash] Event-specific data
+      attr_reader :data
+
+      # Creates a new StreamEvent
+      #
+      # @param type [Symbol] The event type
+      # @param data [Hash] Event-specific data
+      def initialize(type, data = {})
+        @type = type
+        @data = data
+      end
+
+      # @return [Boolean] Whether this is a text chunk event
+      def chunk?
+        @type == :chunk
+      end
+
+      # @return [Boolean] Whether this is a tool lifecycle event
+      def tool_event?
+        @type == :tool_start || @type == :tool_end
+      end
+
+      # @return [Boolean] Whether this is an agent lifecycle event
+      def agent_event?
+        @type == :agent_start || @type == :agent_end
+      end
+
+      # @return [Boolean] Whether this is an error event
+      def error?
+        @type == :error
+      end
+
+      def to_h
+        {type: @type, data: @data}
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/tool.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module RubyLLM
+  module Agents
+    # Base class for tools that need access to the agent's execution context.
+    #
+    # Inherits from RubyLLM::Tool and adds:
+    # - `context` accessor: read agent params, tenant, execution ID
+    # - `timeout` DSL: per-tool timeout in seconds
+    # - Error handling: exceptions become error strings for the LLM
+    # - Tool execution tracking: records each tool call in the database
+    #
+    # Users implement `execute()` — the standard RubyLLM convention.
+    # This class overrides `call()` to wrap execution with its features.
+    #
+    # @example Defining a tool
+    #   class BashTool < RubyLLM::Agents::Tool
+    #     description "Run a shell command"
+    #     timeout 30
+    #
+    #     param :command, desc: "The command to run", required: true
+    #
+    #     def execute(command:)
+    #       context.container_id  # reads agent param
+    #       # ... run command ...
+    #     end
+    #   end
+    #
+    # @example Using with an agent
+    #   class CodingAgent < ApplicationAgent
+    #     param :container_id, required: true
+    #     tools [BashTool]
+    #   end
+    #
+    #   CodingAgent.call(query: "list files", container_id: "abc123")
+    #
+    class Tool < RubyLLM::Tool
+      # The execution context, set before each call.
+      # Provides access to agent params, tenant, execution ID.
+      #
+      # @return [ToolContext, nil]
+      attr_reader :context
+
+      class << self
+        # Sets or gets the per-tool timeout in seconds.
+        #
+        # @param value [Integer, nil] Timeout in seconds (setter)
+        # @return [Integer, nil] The configured timeout (getter)
+        def timeout(value = nil)
+          if value
+            @timeout = value
+          else
+            @timeout
+          end
+        end
+      end
+
+      # Wraps RubyLLM's call() with context, timeout, tracking, and error handling.
+      #
+      # RubyLLM's Chat calls tool.call(args) during the tool loop.
+      # We set up context, create a tracking record, apply timeout,
+      # then delegate to super (which validates args and calls execute).
+      #
+      # @param args [Hash] Tool arguments from the LLM
+      # @return [String, Tool::Halt] The tool result or a Halt signal
+      def call(args)
+        pipeline_context = Thread.current[:ruby_llm_agents_caller_context]
+        @context = pipeline_context ? ToolContext.new(pipeline_context) : nil
+
+        record = start_tool_tracking(pipeline_context, args)
+
+        check_cancelled!(pipeline_context)
+
+        timeout_seconds = self.class.timeout
+        timeout_seconds ||= RubyLLM::Agents.configuration.default_tool_timeout
+
+        result = if timeout_seconds
+          Timeout.timeout(timeout_seconds) { super }
+        else
+          super
+        end
+
+        complete_tool_tracking(record, result, status: "success")
+        result
+      rescue Timeout::Error
+        complete_tool_tracking(record, nil, status: "timed_out", error: "Timed out after #{timeout_seconds}s")
+        "TIMEOUT: Tool did not complete within #{timeout_seconds}s."
+      rescue RubyLLM::Agents::CancelledError
+        complete_tool_tracking(record, nil, status: "cancelled")
+        raise # Let cancellation propagate to BaseAgent
+      rescue => e
+        complete_tool_tracking(record, nil, status: "error", error: e.message)
+        "ERROR (#{e.class}): #{e.message}"
+      end
+
+      private
+
+      # Creates a "running" ToolExecution record before the tool runs.
+      # Silently skips if no execution_id or ToolExecution is not available.
+      #
+      # @param pipeline_context [Pipeline::Context, nil]
+      # @param args [Hash] The tool arguments
+      # @return [ToolExecution, nil]
+      def start_tool_tracking(pipeline_context, args)
+        return nil unless pipeline_context&.execution_id
+        return nil unless defined?(ToolExecution)
+
+        @tool_iteration = (@tool_iteration || 0) + 1
+
+        ToolExecution.create!(
+          execution_id: pipeline_context.execution_id,
+          tool_name: name,
+          iteration: @tool_iteration,
+          status: "running",
+          input: normalize_input(args),
+          started_at: Time.current
+        )
+      rescue => e
+        # Don't let tracking failures break tool execution
+        Rails.logger.debug("[RubyLLM::Agents::Tool] Tracking failed: #{e.message}") if defined?(Rails) && Rails.logger
+        nil
+      end
+
+      # Updates the ToolExecution record after the tool completes.
+      #
+      # @param record [ToolExecution, nil]
+      # @param result [Object, nil] The tool result
+      # @param status [String] Final status
+      # @param error [String, nil] Error message
+      def complete_tool_tracking(record, result, status:, error: nil)
+        return unless record
+
+        completed_at = Time.current
+        duration_ms = record.started_at ? ((completed_at - record.started_at) * 1000).to_i : nil
+        output_str = result.is_a?(RubyLLM::Tool::Halt) ? result.content.to_s : result.to_s
+
+        record.update!(
+          status: status,
+          output: truncate_output(output_str),
+          output_bytes: output_str.bytesize,
+          error_message: error,
+          completed_at: completed_at,
+          duration_ms: duration_ms
+        )
+      rescue => e
+        Rails.logger.debug("[RubyLLM::Agents::Tool] Tracking update failed: #{e.message}") if defined?(Rails) && Rails.logger
+      end
+
+      def check_cancelled!(pipeline_context)
+        return unless pipeline_context
+        on_cancelled = pipeline_context[:on_cancelled]
+        return unless on_cancelled.respond_to?(:call)
+        raise CancelledError, "Execution cancelled" if on_cancelled.call
+      end
+
+      def normalize_input(args)
+        return {} if args.nil?
+        args.respond_to?(:to_h) ? args.to_h : {}
+      end
+
+      def truncate_output(str)
+        max = RubyLLM::Agents.configuration.try(:tool_result_max_length) || 10_000
+        (str.length > max) ? str[0, max] + "... (truncated)" : str
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/tool_context.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Read-only wrapper around Pipeline::Context for tool authors.
+    #
+    # Exposes agent params and execution metadata to tools without
+    # leaking pipeline internals. Supports both method-style and
+    # hash-style access to agent params.
+    #
+    # @example Method-style access
+    #   context.container_id   # reads agent param
+    #   context.tenant_id      # fixed attribute
+    #
+    # @example Hash-style access
+    #   context[:container_id]
+    #
+    class ToolContext
+      # Execution record ID — links tool calls to the agent execution
+      #
+      # @return [Integer, nil]
+      def id
+        @ctx.execution_id
+      end
+
+      # Tenant ID from the pipeline context
+      #
+      # @return [String, nil]
+      def tenant_id
+        @ctx.tenant_id
+      end
+
+      # Agent class name
+      #
+      # @return [String, nil]
+      def agent_type
+        @ctx.agent_class&.name
+      end
+
+      # Hash-style access to agent params
+      #
+      # @param key [Symbol, String] The param key
+      # @return [Object, nil]
+      def [](key)
+        @agent_options[key.to_sym] || @agent_options[key.to_s]
+      end
+
+      def initialize(pipeline_context)
+        @ctx = pipeline_context
+        @agent_options = @ctx.agent_instance&.send(:options) || {}
+      end
+
+      private
+
+      # Method-style access to agent params
+      def method_missing(method_name, *args)
+        key = method_name.to_sym
+        if @agent_options.key?(key) || @agent_options.key?(key.to_s)
+          self[key]
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        key = method_name.to_sym
+        @agent_options.key?(key) || @agent_options.key?(key.to_s) || super
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents.rb

@@ -26,6 +26,13 @@ require_relative "agents/base_agent"
 # Agent-as-Tool adapter
 require_relative "agents/agent_tool"
 
+# Streaming events
+require_relative "agents/stream_event"
+
+# Tool base class and context for coding agents
+require_relative "agents/tool_context"
+require_relative "agents/tool"
+
 # Infrastructure - Budget & Utilities
 require_relative "agents/infrastructure/circuit_breaker"
 require_relative "agents/infrastructure/budget_tracker"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-agents
 version: !ruby/object:Gem::Version
-  version: 3.9.0
+  version: 3.11.0
 platform: ruby
 authors:
 - adham90
@@ -98,6 +98,7 @@ files:
 - app/models/ruby_llm/agents/tenant/resettable.rb
 - app/models/ruby_llm/agents/tenant/trackable.rb
 - app/models/ruby_llm/agents/tenant_budget.rb
+- app/models/ruby_llm/agents/tool_execution.rb
 - app/services/ruby_llm/agents/agent_registry.rb
 - app/views/layouts/ruby_llm/agents/application.html.erb
 - app/views/ruby_llm/agents/agents/_config_agent.html.erb
@@ -239,6 +240,7 @@ files:
 - lib/ruby_llm/agents/core/llm_tenant.rb
 - lib/ruby_llm/agents/core/version.rb
 - lib/ruby_llm/agents/dsl.rb
+- lib/ruby_llm/agents/dsl/agents.rb
 - lib/ruby_llm/agents/dsl/base.rb
 - lib/ruby_llm/agents/dsl/caching.rb
 - lib/ruby_llm/agents/dsl/queryable.rb
@@ -325,7 +327,10 @@ files:
 - lib/ruby_llm/agents/routing.rb
 - lib/ruby_llm/agents/routing/class_methods.rb
 - lib/ruby_llm/agents/routing/result.rb
+- lib/ruby_llm/agents/stream_event.rb
 - lib/ruby_llm/agents/text/embedder.rb
+- lib/ruby_llm/agents/tool.rb
+- lib/ruby_llm/agents/tool_context.rb
 - lib/ruby_llm/agents/track_report.rb
 - lib/ruby_llm/agents/tracker.rb
 - lib/tasks/ruby_llm_agents.rake