ruby_llm-agents 3.10.0 → 3.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00477ed5ab4c97d2b28bb0b697288882744f1c377613224361233e0b3a145273
-  data.tar.gz: bac4d24f3599fbf7f3045e5ac41b1e85d047d74491b5dcc1dfb1c47cc85a5f60
+  metadata.gz: 2db1aa75b826b63dae9aec7ee8bee4e3597ce9dab4509e49dcd5cc6bdd8b3aa8
+  data.tar.gz: aa5b53d9558b0724ba89a39575b2ac2c3ba2eda550c87d3388f3f66cbda6d0e3
 SHA512:
-  metadata.gz: 29ac67e031dc46d3b0d19f91843e6b2e034f0246445a5ad1d6ce453a2782f41948a92947a3a6e36d177d381756858185f87aa9b07d723123e1af3914f66ab136
-  data.tar.gz: d479f5076373eea1f30d8c797cd885d0788c7a081860a72fd69ee5dc3f77631860577eab91c14c09dd7f9fda709da41de90fb74b8a626b9094145f071e19259b
+  metadata.gz: c5537dd90aaceadb9b0948687d3a1ed6635e5c93d8b82a2eae23f805dcb3fc14c32c37aa3fa7bf56a581b48ea72e0d8b0c730f750fc866a6fc4461d784a3ac49
+  data.tar.gz: ebbaa8c6c7cf7d27163fbd33c1436cd3332ebbc7069eef6a6b24b50d12e75fd7b962dfaba21faf94d52e8a7ba67a37073c33dc82c91058beb32d486ef3565fc8

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
@@ -817,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
@@ -843,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
@@ -993,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/version.rb

@@ -4,6 +4,6 @@ module RubyLLM
   module Agents
     # Current version of the RubyLLM::Agents gem
     # @return [String] Semantic version string
-    VERSION = "3.10.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/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.rb

@@ -26,6 +26,9 @@ 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"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-agents
 version: !ruby/object:Gem::Version
-  version: 3.10.0
+  version: 3.11.0
 platform: ruby
 authors:
 - adham90
@@ -240,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
@@ -326,6 +327,7 @@ 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