omni_agent 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53319cab79a557426f4a7a109a1627c425cffe49d56dc6f2d0baba58ab74b24d
-  data.tar.gz: 541ff86413a12fbf65f95c12945e45a74d9baac18f9f7d446f5dce3281ae93ce
+  metadata.gz: ea0324a20bc12e064b994b4fcdf7af700cd0280ba7b0609dc75724717e9fc881
+  data.tar.gz: dfda03e711340e59dfbb1cd803bc785a51bbe39d972992c6a26fb5b2d4d8761a
 SHA512:
-  metadata.gz: 996ba6f8c9679fea087dccc4fc202de1b4fb2e8debece3fa63438719447819590294b0e965228ff4fb2e93eb25556283cce000dde2f04bba8fb2ee14a3b3ccfd
-  data.tar.gz: 8620ac25e792aa0213f00abbf717b814c4b3cca8a09af45a8659f9e557d9df5c0e33363ff109615f139403595630832cf8ff0c370d88a1a26bdfc74bb97ccd6e
+  metadata.gz: 72739c339838d0f38c172455226ff79244ab7e739920ec9e7b89f16182d220a1526886bff1f85b7b943bc6426676d5cc4dbd727f903c612df401587fc627f3f0
+  data.tar.gz: b90d265c701efaf90d5d5f5e5f9aac3b337095e998d413bf5e872e05d794a9793a44e0bd669425d30ee13eabd50ded2f0fdc2c19cadbc1ff976ec02d0e8d888f

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.8](https://github.com/ACR1209/omni_agent/compare/omni_agent/v0.1.7...omni_agent/v0.1.8) (2026-07-07)
+
+
+### Features
+
+* implement multi-agent delegation with context forwarding and depth control ([e9b5497](https://github.com/ACR1209/omni_agent/commit/e9b5497b0af89172701bf4c5d93b8d5dccc77a26))
+
 ## [0.1.7](https://github.com/ACR1209/omni_agent/compare/omni_agent-v0.1.6...omni_agent/v0.1.7) (2026-06-22)
 
 

data/README.md

@@ -97,6 +97,38 @@ module ResearchAgent::Tools
 end
 ```
 
+## Multi-Agent Delegation
+
+`delegate_to` turns an agent into a supervisor: it wraps another agent class as a tool, so the supervisor's LLM can decide when to hand off to it. The delegated agent is a normal, independently defined agent (e.g. `app/agents/research_agent.rb`) — no manual tool file needed.
+
+```ruby
+class SupervisorAgent < OmniAgent::Agent
+	use_model "gpt-4o"
+
+	delegate_to ResearchAgent, as: :research,  description: "Look up factual info"
+	delegate_to MathAgent,     as: :calculate, description: "Do arithmetic"
+end
+```
+
+Each delegated agent runs in isolation (its own fresh instance, no shared context) and returns its final answer as the tool result. Delegation depth is capped by `OmniAgent.configuration.max_delegation_depth` (default `5`) to guard against runaway recursive delegation; exceeding it raises `OmniAgent::MaxDelegationDepthError`.
+
+Pass `run_alias:` to call a `run_aliases` method (or any zero-arg run entrypoint) on the delegated agent instead of its default `#run` — useful when the sub-agent should render a different prompt file for delegated calls:
+
+```ruby
+class SupervisorAgent < OmniAgent::Agent
+	delegate_to SupportAgent, as: :triage_ticket, run_alias: :triage
+end
+```
+
+Pass `forward:` to share part (or all) of the supervisor's context with the delegated agent — an array of context keys, or `true` to forward everything. Omitted keys, and the default (`forward: []`), keep the delegated agent fully isolated:
+
+```ruby
+class SupervisorAgent < OmniAgent::Agent
+	delegate_to ResearchAgent, as: :research, forward: [ :user, :locale ]
+	delegate_to MathAgent,     as: :calculate, forward: true
+end
+```
+
 ## Evals
 
 `OmniAgent::Eval` lets you test agent quality: deterministic assertions (tool calls, output matching) and pluggable LLM-as-judge scoring.

data/lib/omni_agent/agent.rb

@@ -84,6 +84,21 @@ module OmniAgent
         end
       end
 
+      def delegate_to(agent_class, as:, description: nil, run_alias: nil, forward: [])
+        unless agent_class.is_a?(Class) && agent_class <= OmniAgent::Agent
+          raise ArgumentError, "delegate_to requires an OmniAgent::Agent subclass"
+        end
+
+        tool_class = build_delegated_tool_class(agent_class, description: description, run_alias: run_alias, forward: forward)
+        delegated_tools_module.const_set(delegated_tool_const_name(as), tool_class)
+
+        @delegated_tool_classes = configured_delegated_tool_classes + [ tool_class ]
+      end
+
+      def configured_delegated_tool_classes
+        @delegated_tool_classes || []
+      end
+
       def with(context = nil, provider_override: nil, model_override: nil, options_override: {}, **context_keywords)
         merged_context = {}
         merged_context.merge!(context) if context.is_a?(Hash)
@@ -112,6 +127,58 @@ module OmniAgent
 
       private
 
+      def delegated_tools_module
+        @delegated_tools_module ||= const_set(:DelegatedTools, Module.new)
+      end
+
+      def delegated_tool_const_name(as)
+        as.to_s.split(/[_\s]+/).reject(&:empty?).map { |part| part[0].upcase + part[1..] }.join
+      end
+
+      def build_delegated_tool_class(agent_class, description:, run_alias:, forward:)
+        tool_description = description || "Delegate to #{agent_class.name}."
+
+        Class.new(OmniAgent::Tool) do
+          description tool_description
+
+          input do
+            string :input, description: "Input/question to send to the delegated agent."
+          end
+
+          define_method(:execute) do |input:|
+            forwarded_context = OmniAgent::Agent.__send__(:filter_forwarded_context, context, forward)
+            OmniAgent::Agent.__send__(:run_delegated_agent, agent_class, input, run_alias, forwarded_context)
+          end
+        end
+      end
+
+      def filter_forwarded_context(context, forward)
+        return {} unless context.is_a?(Hash)
+        return context.dup if forward == true
+        return {} if forward.nil? || forward == false
+
+        keys = Array(forward).map(&:to_sym)
+        context.select { |key, _| keys.include?(key.to_sym) }
+      end
+
+      def run_delegated_agent(agent_class, input, run_alias, forwarded_context)
+        depth = (Thread.current[:omni_agent_delegation_depth] ||= 0)
+        max_depth = OmniAgent.configuration.max_delegation_depth
+
+        if depth >= max_depth
+          raise OmniAgent::MaxDelegationDepthError,
+                "Exceeded max_delegation_depth (#{max_depth}) while delegating to #{agent_class.name}."
+        end
+
+        Thread.current[:omni_agent_delegation_depth] = depth + 1
+        begin
+          entrypoint = run_alias || :run
+          agent_class.new.public_send(entrypoint, input, context: forwarded_context).answer
+        ensure
+          Thread.current[:omni_agent_delegation_depth] = depth
+        end
+      end
+
       def normalize_callbacks(callback_type, callbacks)
         raise ArgumentError, "#{callback_type} requires at least one method name" if callbacks.empty?
 
@@ -196,6 +263,7 @@ module OmniAgent
 
           if tool_class
             tool_instance = tool_class.new
+            tool_instance.context = context if tool_instance.respond_to?(:context=)
 
             begin
               result = tool_instance.invoke(tool_args)
@@ -238,12 +306,17 @@ module OmniAgent
 
     def available_tools
       tool_namespace = "#{self.class.name}::Tools".safe_constantize
-      return [] unless tool_namespace
 
-      tool_namespace.constants.filter_map do |const_name|
-        const = tool_namespace.const_get(const_name)
-        const if const.is_a?(Class) && const < OmniAgent::Tool
+      namespace_tools = if tool_namespace
+        tool_namespace.constants.filter_map do |const_name|
+          const = tool_namespace.const_get(const_name)
+          const if const.is_a?(Class) && const < OmniAgent::Tool
+        end
+      else
+        []
       end
+
+      namespace_tools + self.class.configured_delegated_tool_classes
     end
 
     private

data/lib/omni_agent/configuration.rb

@@ -1,7 +1,7 @@
 module OmniAgent
   class Configuration
     attr_accessor :default_provider, :default_model, :max_retries, :retry_base_delay, :max_tool_iterations,
-                  :eval_judge_provider, :eval_judge_model, :eval_cache_enabled, :eval_cache_path
+                  :max_delegation_depth, :eval_judge_provider, :eval_judge_model, :eval_cache_enabled, :eval_cache_path
 
     def initialize
       @default_provider = :openai
@@ -9,6 +9,7 @@ module OmniAgent
       @max_retries = 3
       @retry_base_delay = 0.5
       @max_tool_iterations = 10
+      @max_delegation_depth = 5
       @eval_judge_provider = nil
       @eval_judge_model = nil
       @eval_cache_enabled = true

data/lib/omni_agent/errors.rb

@@ -4,6 +4,7 @@ module OmniAgent
     class MissingDependencyError < Error; end
     class UnknownProviderError < Error; end
     class MaxToolIterationsError < Error; end
+    class MaxDelegationDepthError < Error; end
     class EvalAssertionError < Error; end
   end
 
@@ -11,5 +12,6 @@ module OmniAgent
   MissingDependencyError = Errors::MissingDependencyError
   UnknownProviderError = Errors::UnknownProviderError
   MaxToolIterationsError = Errors::MaxToolIterationsError
+  MaxDelegationDepthError = Errors::MaxDelegationDepthError
   EvalAssertionError = Errors::EvalAssertionError
 end

data/lib/omni_agent/tool.rb

@@ -69,6 +69,12 @@ module OmniAgent
       end
     end
 
+    attr_accessor :context
+
+    def initialize
+      @context = {}
+    end
+
     def invoke(arguments_hash)
       filtered_kwargs = self.class.parse_arguments(arguments_hash)
       execute(**filtered_kwargs)

data/lib/omni_agent/version.rb

@@ -1,3 +1,3 @@
 module OmniAgent
-  VERSION = "0.1.7"
+  VERSION = "0.1.8"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omni_agent
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - ACR1209