ai-agents 0.1.2 → 0.2.0

data/examples/collaborative-copilot/tools/search_knowledge_base_tool.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Copilot
+  # Tool for searching knowledge base articles and documentation
+  class SearchKnowledgeBaseTool < Agents::Tool
+    description "Search help documentation and knowledge base for solutions"
+    param :query, type: "string", desc: "Search terms or keywords to find relevant articles"
+    param :category, type: "string",
+                     desc: "Optional: filter by category (troubleshooting, account, development, billing)", required: false
+
+    def perform(_tool_context, query:, category: nil)
+      data_file = File.join(__dir__, "../data/knowledge_base.json")
+      return "Knowledge base unavailable" unless File.exist?(data_file)
+
+      begin
+        kb_data = JSON.parse(File.read(data_file))
+        articles = kb_data["articles"]
+        query_text = query.downcase
+        matches = []
+
+        articles.each do |article_id, article|
+          # Skip if category filter is specified and doesn't match
+          next if category && article["category"] != category.downcase
+
+          # Simple keyword matching
+          text_to_search = [
+            article["title"],
+            article["tags"].join(" "),
+            article["content"]
+          ].join(" ").downcase
+
+          next unless text_to_search.include?(query_text)
+
+          matches << {
+            article_id: article_id,
+            title: article["title"],
+            category: article["category"],
+            tags: article["tags"],
+            content_preview: "#{article["content"][0...200]}..."
+          }
+        end
+
+        if matches.empty?
+          "No knowledge base articles found for: #{query}"
+        else
+          JSON.pretty_generate({ query: query, articles: matches })
+        end
+      rescue StandardError => e
+        "Error searching knowledge base: #{e.message}"
+      end
+    end
+  end
+end

data/examples/collaborative-copilot/tools/search_linear_issues_tool.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Copilot
+  # Tool for searching Linear issues for development context and bug reports
+  class SearchLinearIssuesTool < Agents::Tool
+    description "Search Linear issues for bug reports, feature requests, and development context"
+    param :query, type: "string", desc: "Search terms (keywords, error messages, or feature descriptions)"
+    param :status, type: "string", desc: "Optional: filter by status (backlog, in_progress, completed, resolved)",
+                   required: false
+    param :priority, type: "string", desc: "Optional: filter by priority (low, medium, high)", required: false
+
+    def perform(_tool_context, query:, status: nil, priority: nil)
+      data_file = File.join(__dir__, "../data/linear_issues.json")
+      return "Linear issues database unavailable" unless File.exist__(data_file)
+
+      begin
+        linear_data = JSON.parse(File.read(data_file))
+        issues = linear_data["issues"]
+        query_text = query.downcase
+        matches = []
+
+        issues.each do |issue_id, issue|
+          # Apply filters
+          next if status && issue["status"] != status.downcase
+          next if priority && issue["priority"] != priority.downcase
+
+          # Simple keyword matching
+          text_to_search = [
+            issue["title"],
+            issue["description"],
+            issue["labels"].join(" "),
+            issue["resolution"]
+          ].compact.join(" ").downcase
+
+          next unless text_to_search.include?(query_text)
+
+          matches << {
+            issue_id: issue_id,
+            title: issue["title"],
+            status: issue["status"],
+            priority: issue["priority"],
+            labels: issue["labels"],
+            description: "#{issue["description"][0...200]}...",
+            resolution: issue["resolution"]
+          }
+        end
+
+        if matches.empty?
+          "No Linear issues found for: #{query}"
+        else
+          JSON.pretty_generate({ query: query, issues: matches })
+        end
+      rescue StandardError => e
+        "Error searching Linear issues: #{e.message}"
+      end
+    end
+  end
+end

data/examples/isp-support/interactive.rb

@@ -14,16 +14,20 @@ class ISPSupportDemo
     end
 
     # Create agents
-    agents = ISPSupport::AgentsFactory.create_agents
+    @agents = ISPSupport::AgentsFactory.create_agents
 
     # Create thread-safe runner with all agents (triage first = default entry point)
     @runner = Agents::Runner.with_agents(
-      agents[:triage],
-      agents[:sales],
-      agents[:support]
+      @agents[:triage],
+      @agents[:sales],
+      @agents[:support]
     )
 
+    # Setup real-time callbacks for UI feedback
+    setup_callbacks
+
     @context = {}
+    @current_status = ""
 
     puts "🏢 Welcome to ISP Customer Support!"
     puts "Type '/help' for commands or 'exit' to quit."
@@ -39,12 +43,18 @@ class ISPSupportDemo
       break if command_result == :exit
       next if command_result == :handled || user_input.empty?
 
+      # Clear any previous status and show agent is working
+      clear_status_line
+      print "🤖 Processing..."
+
       # Use the runner - it automatically determines the right agent from context
       result = @runner.run(user_input, context: @context)
 
       # Update our context with the returned context from Runner
       @context = result.context if result.respond_to?(:context) && result.context
 
+      # Clear status and show response
+      clear_status_line
       puts "🤖 #{result.output || "[No output]"}"
 
       puts
@@ -53,6 +63,35 @@ class ISPSupportDemo
 
   private
 
+  def setup_callbacks
+    @runner.on_agent_thinking do |agent_name, _input|
+      update_status("🧠 #{agent_name} is thinking...")
+    end
+
+    @runner.on_tool_start do |tool_name, _args|
+      update_status("🔧 Using #{tool_name}...")
+    end
+
+    @runner.on_tool_complete do |tool_name, _result|
+      update_status("✅ #{tool_name} completed")
+    end
+
+    @runner.on_agent_handoff do |from_agent, to_agent, _reason|
+      update_status("🔄 Handoff: #{from_agent} → #{to_agent}")
+    end
+  end
+
+  def update_status(message)
+    clear_status_line
+    print message
+    $stdout.flush
+  end
+
+  def clear_status_line
+    print "\r#{" " * 80}\r" # Clear the current line
+    $stdout.flush
+  end
+
   def handle_command(input)
     case input.downcase
     when "exit", "quit"

data/lib/agents/agent.rb

@@ -178,5 +178,39 @@ module Agents
         instructions.call(context)
       end
     end
+
+    # Transform this agent into a tool, callable by other agents.
+    # This enables agent-to-agent collaboration without conversation handoffs.
+    #
+    # Agent-as-tool is different from handoffs in two key ways:
+    # 1. The wrapped agent receives generated input, not conversation history
+    # 2. The wrapped agent returns a result to the calling agent, rather than taking over
+    #
+    # @param name [String, nil] Override the tool name (defaults to snake_case agent name)
+    # @param description [String, nil] Override the tool description
+    # @param output_extractor [Proc, nil] Custom proc to extract/transform the agent's output
+    # @param params [Hash] Additional parameter definitions for the tool
+    # @return [Agents::AgentTool] A tool that wraps this agent
+    #
+    # @example Basic agent-as-tool
+    #   research_agent = Agent.new(name: "Researcher", instructions: "Research topics")
+    #   research_tool = research_agent.as_tool(
+    #     name: "research_topic",
+    #     description: "Research a topic using company knowledge base"
+    #   )
+    #
+    # @example Custom output extraction
+    #   analyzer_tool = analyzer_agent.as_tool(
+    #     output_extractor: ->(result) { result.context[:extracted_data]&.to_json || result.output }
+    #   )
+    #
+    def as_tool(name: nil, description: nil, output_extractor: nil)
+      AgentTool.new(
+        agent: self,
+        name: name,
+        description: description,
+        output_extractor: output_extractor
+      )
+    end
   end
 end

data/lib/agents/agent_runner.rb

@@ -11,6 +11,8 @@ module Agents
   # ## Usage Pattern
   #   # Create once (typically at application startup)
   #   runner = Agents::Runner.with_agents(triage_agent, billing_agent, support_agent)
+  #     .on_tool_start { |tool_name, args| broadcast_event('tool_start', tool_name, args) }
+  #     .on_tool_complete { |tool_name, result| broadcast_event('tool_complete', tool_name, result) }
   #
   #   # Use safely from multiple threads
   #   result = runner.run("I need billing help")           # New conversation
@@ -22,6 +24,10 @@ module Agents
   # - Each run() call creates independent execution context
   # - No shared mutable state between concurrent executions
   #
+  # ## Callback Thread Safety
+  # Callback registration is thread-safe using internal synchronization. Multiple threads
+  # can safely register callbacks concurrently without data races.
+  #
   class AgentRunner
     # Initialize with a list of agents. The first agent becomes the default entry point.
     #
@@ -30,10 +36,19 @@ module Agents
       raise ArgumentError, "At least one agent must be provided" if agents.empty?
 
       @agents = agents.dup.freeze
+      @callbacks_mutex = Mutex.new
       @default_agent = agents.first
 
       # Build simple registry from provided agents - developer controls what's available
       @registry = build_registry(agents).freeze
+
+      # Initialize callback storage - use thread-safe arrays
+      @callbacks = {
+        tool_start: [],
+        tool_complete: [],
+        agent_thinking: [],
+        agent_handoff: []
+      }
     end
 
     # Execute a conversation turn with automatic agent selection.
@@ -50,15 +65,65 @@ module Agents
       current_agent = determine_conversation_agent(context)
 
       # Execute using stateless Runner - each execution is independent and thread-safe
+      # Pass callbacks to enable real-time event notifications
       Runner.new.run(
         current_agent,
         input,
         context: context,
         registry: @registry,
-        max_turns: max_turns
+        max_turns: max_turns,
+        callbacks: @callbacks
       )
     end
 
+    # Register a callback for tool start events.
+    # Called when an agent is about to execute a tool.
+    #
+    # @param block [Proc] Callback block that receives (tool_name, args)
+    # @return [self] For method chaining
+    def on_tool_start(&block)
+      return self unless block
+
+      @callbacks_mutex.synchronize { @callbacks[:tool_start] << block }
+      self
+    end
+
+    # Register a callback for tool completion events.
+    # Called when an agent has finished executing a tool.
+    #
+    # @param block [Proc] Callback block that receives (tool_name, result)
+    # @return [self] For method chaining
+    def on_tool_complete(&block)
+      return self unless block
+
+      @callbacks_mutex.synchronize { @callbacks[:tool_complete] << block }
+      self
+    end
+
+    # Register a callback for agent thinking events.
+    # Called when an agent is about to make an LLM call.
+    #
+    # @param block [Proc] Callback block that receives (agent_name, input)
+    # @return [self] For method chaining
+    def on_agent_thinking(&block)
+      return self unless block
+
+      @callbacks_mutex.synchronize { @callbacks[:agent_thinking] << block }
+      self
+    end
+
+    # Register a callback for agent handoff events.
+    # Called when control is transferred from one agent to another.
+    #
+    # @param block [Proc] Callback block that receives (from_agent, to_agent, reason)
+    # @return [self] For method chaining
+    def on_agent_handoff(&block)
+      return self unless block
+
+      @callbacks_mutex.synchronize { @callbacks[:agent_handoff] << block }
+      self
+    end
+
     private
 
     # Build agent registry from provided agents only.

data/lib/agents/agent_tool.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Agents
+  # AgentTool wraps an agent as a tool, enabling agent-to-agent collaboration
+  # without conversation handoffs. This implementation constrains wrapped agents
+  # for safety and predictability.
+  #
+  # Key constraints:
+  # 1. Wrapped agents cannot perform handoffs (empty registry)
+  # 2. Limited turn count to prevent infinite loops
+  # 3. Isolated context (only shared state, no conversation history)
+  # 4. Always returns to calling agent
+  #
+  # @example Customer support copilot with specialized agents
+  #   conversation_agent = Agent.new(
+  #     name: "ConversationAnalyzer",
+  #     instructions: "Extract order IDs and customer intent from conversation history"
+  #   )
+  #
+  #   actions_agent = Agent.new(
+  #     name: "ShopifyActions",
+  #     instructions: "Perform Shopify operations",
+  #     tools: [shopify_tool]
+  #   )
+  #
+  #   copilot = Agent.new(
+  #     name: "SupportCopilot",
+  #     tools: [
+  #       conversation_agent.as_tool(
+  #         name: "analyze_conversation",
+  #         description: "Extract key info from conversation history"
+  #       ),
+  #       actions_agent.as_tool(
+  #         name: "shopify_action",
+  #         description: "Perform Shopify operations like refunds"
+  #       )
+  #     ]
+  #   )
+  class AgentTool < Tool
+    attr_reader :wrapped_agent, :tool_name, :tool_description, :output_extractor
+
+    # Default parameter for agent tools
+    param :input, type: "string", desc: "Input message for the agent"
+
+    # Initialize an AgentTool that wraps an agent as a callable tool
+    #
+    # @param agent [Agents::Agent] The agent to wrap as a tool
+    # @param name [String, nil] Override the tool name (defaults to snake_case agent name)
+    # @param description [String, nil] Override the tool description
+    # @param output_extractor [Proc, nil] Custom proc to extract/transform the agent's output
+    def initialize(agent:, name: nil, description: nil, output_extractor: nil)
+      @wrapped_agent = agent
+      @tool_name = name || transform_agent_name(agent.name)
+      @tool_description = description || "Execute #{agent.name} agent"
+      @output_extractor = output_extractor
+
+      super()
+    end
+
+    def name
+      @tool_name
+    end
+
+    def description
+      @tool_description
+    end
+
+    # Execute the wrapped agent with constraints to prevent handoffs and recursion
+    def perform(tool_context, input:)
+      # Create isolated context for the wrapped agent
+      isolated_context = create_isolated_context(tool_context.context)
+
+      # Execute with explicit constraints:
+      # 1. Empty registry prevents handoffs
+      # 2. Low max_turns prevents infinite loops
+      # 3. Isolated context prevents history access
+      result = Runner.new.run(
+        @wrapped_agent,
+        input,
+        context: isolated_context,
+        registry: {}, # CONSTRAINT: No handoffs allowed
+        max_turns: 3  # CONSTRAINT: Limited turns for tool execution
+      )
+
+      return "Agent execution failed: #{result.error.message}" if result.error
+
+      # Extract output
+      if @output_extractor
+        @output_extractor.call(result)
+      else
+        result.output || "No output from #{@wrapped_agent.name}"
+      end
+    rescue StandardError => e
+      "Error executing #{@wrapped_agent.name}: #{e.message}"
+    end
+
+    private
+
+    def transform_agent_name(name)
+      name.downcase.gsub(/\s+/, "_").gsub(/[^a-z0-9_]/, "")
+    end
+
+    # Create isolated context that only shares state, not conversation artifacts
+    def create_isolated_context(parent_context)
+      isolated = {}
+
+      # Only share the state - everything else is conversation-specific
+      isolated[:state] = parent_context[:state] if parent_context[:state]
+
+      isolated
+    end
+  end
+end

data/lib/agents/callback_manager.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Agents
+  # Manager for handling and emitting callback events in a thread-safe manner.
+  # Provides both generic emit() method and typed convenience methods.
+  #
+  # @example Using generic emit
+  #   manager.emit(:tool_start, tool_name, args)
+  #
+  # @example Using typed methods
+  #   manager.emit_tool_start(tool_name, args)
+  #   manager.emit_agent_thinking(agent_name, input)
+  class CallbackManager
+    # Supported callback event types
+    EVENT_TYPES = %i[
+      tool_start
+      tool_complete
+      agent_thinking
+      agent_handoff
+    ].freeze
+
+    def initialize(callbacks = {})
+      @callbacks = callbacks.dup.freeze
+    end
+
+    # Generic method to emit any callback event type
+    #
+    # @param event_type [Symbol] The type of event to emit
+    # @param args [Array] Arguments to pass to callbacks
+    def emit(event_type, *args)
+      callback_list = @callbacks[event_type] || []
+
+      callback_list.each do |callback|
+        callback.call(*args)
+      rescue StandardError => e
+        # Log callback errors but don't let them crash execution
+        warn "Callback error for #{event_type}: #{e.message}"
+      end
+    end
+
+    # Metaprogramming: Create typed emit methods for each event type
+    #
+    # This generates methods like:
+    #   emit_tool_start(tool_name, args)
+    #   emit_tool_complete(tool_name, result)
+    #   emit_agent_thinking(agent_name, input)
+    #   emit_agent_handoff(from_agent, to_agent, reason)
+    EVENT_TYPES.each do |event_type|
+      define_method("emit_#{event_type}") do |*args|
+        emit(event_type, *args)
+      end
+    end
+  end
+end

data/lib/agents/handoff.rb

@@ -12,35 +12,10 @@ module Agents
   # 4. The tool signals the handoff through context
   # 5. The Runner detects this and switches to the new agent
   #
-  # ## First-Call-Wins Implementation
-  # This implementation uses "first-call-wins" semantics to prevent infinite handoff loops.
-  #
-  # ### The Problem We Solved
-  # During development, we discovered that LLMs could call the same handoff tool multiple times
-  # in a single response, leading to infinite loops:
-  #
-  # 1. User: "My internet isn't working but my account shows active"
-  # 2. Triage Agent hands off to Support Agent
-  # 3. Support Agent sees account info is needed, hands back to Triage Agent
-  # 4. Triage Agent sees technical issue, hands off to Support Agent again
-  # 5. This creates an infinite ping-pong loop
-  #
-  # ### Root Cause Analysis
-  # Unlike OpenAI's SDK which processes tool calls before execution, RubyLLM automatically
-  # executes all tool calls in a response. This meant:
-  # - LLM calls handoff tool 10+ times in one response
-  # - Each call sets context[:pending_handoff], overwriting previous values
-  # - Runner processes handoffs after tool execution, seeing only the last one
-  # - Multiple handoff signals created conflicting state
-  #
-  # TODO: Overall, this problem can be tackled better if we replace the RubyLLM chat
-  # program with our own implementation.
-  #
-  # ### The Solution
-  # We implemented first-call-wins semantics inspired by OpenAI's approach:
-  # - First handoff call in a response sets the pending handoff
-  # - Subsequent calls are ignored with a "transfer in progress" message
-  # - This prevents loops and mirrors OpenAI SDK behavior
+  # ## Loop Prevention
+  # The library prevents infinite handoff loops by processing only the first handoff
+  # tool call in any LLM response. This is handled automatically by the Chat class
+  # which detects handoff tools and processes them separately from regular tools.
   #
   # ## Why Tools Instead of Instructions
   # Using tools for handoffs has several advantages:
@@ -66,12 +41,11 @@ module Agents
   #   # LLM calls: handoff_to_billing()
   #   # Runner switches to billing_agent for the next turn
   #
-  # @example First-call-wins in action
+  # @example Multiple handoff handling
   #   # Single LLM response with multiple handoff calls:
-  #   # Call 1: handoff_to_support() -> Sets pending_handoff, returns "Transferring to Support"
-  #   # Call 2: handoff_to_support() -> Ignored, returns "Transfer already in progress"
-  #   # Call 3: handoff_to_billing() -> Ignored, returns "Transfer already in progress"
-  #   # Result: Only transfers to Support Agent (first call wins)
+  #   # Call 1: handoff_to_support() -> Processed and executed
+  #   # Call 2: handoff_to_billing() -> Ignored (only first handoff processed)
+  #   # Result: Only transfers to Support Agent
   class HandoffTool < Tool
     attr_reader :target_agent
 

data/lib/agents/message_extractor.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Agents
+  # Service object responsible for extracting and formatting conversation messages
+  # from RubyLLM chat objects into a format suitable for persistence and context restoration.
+  #
+  # Handles different message types:
+  # - User messages: Basic content preservation
+  # - Assistant messages: Includes agent attribution and tool calls
+  # - Tool result messages: Links back to original tool calls
+  #
+  # @example Extract messages from a chat
+  #   messages = MessageExtractor.extract_messages(chat, current_agent)
+  #   #=> [
+  #     { role: :user, content: "Hello" },
+  #     { role: :assistant, content: "Hi!", agent_name: "Support", tool_calls: [...] },
+  #     { role: :tool, content: "Result", tool_call_id: "call_123" }
+  #   ]
+  class MessageExtractor
+    # Extract messages from a chat object for conversation history persistence
+    #
+    # @param chat [Object] Chat object that responds to :messages
+    # @param current_agent [Agent] The agent currently handling the conversation
+    # @return [Array<Hash>] Array of message hashes suitable for persistence
+    def self.extract_messages(chat, current_agent)
+      new(chat, current_agent).extract
+    end
+
+    def initialize(chat, current_agent)
+      @chat = chat
+      @current_agent = current_agent
+    end
+
+    def extract
+      return [] unless @chat.respond_to?(:messages)
+
+      @chat.messages.filter_map do |msg|
+        case msg.role
+        when :user, :assistant
+          extract_user_or_assistant_message(msg)
+        when :tool
+          extract_tool_message(msg)
+        end
+      end
+    end
+
+    private
+
+    def extract_user_or_assistant_message(msg)
+      return nil unless msg.content && !msg.content.strip.empty?
+
+      message = {
+        role: msg.role,
+        content: msg.content
+      }
+
+      if msg.role == :assistant
+        # Add agent attribution for conversation continuity
+        message[:agent_name] = @current_agent.name if @current_agent
+
+        # Add tool calls if present
+        if msg.tool_call? && msg.tool_calls
+          # RubyLLM stores tool_calls as Hash with call_id => ToolCall object
+          # Reference: RubyLLM::StreamAccumulator#tool_calls_from_stream
+          message[:tool_calls] = msg.tool_calls.values.map(&:to_h)
+        end
+      end
+
+      message
+    end
+
+    def extract_tool_message(msg)
+      return nil unless msg.tool_result?
+
+      {
+        role: msg.role,
+        content: msg.content,
+        tool_call_id: msg.tool_call_id
+      }
+    end
+  end
+end

data/lib/agents/run_context.rb

@@ -56,14 +56,17 @@
 #   # - No race conditions or data leakage between runs
 module Agents
   class RunContext
-    attr_reader :context, :usage
+    attr_reader :context, :usage, :callbacks, :callback_manager
 
     # Initialize a new RunContext with execution context and usage tracking
     #
     # @param context [Hash] The execution context data (will be duplicated for isolation)
-    def initialize(context)
+    # @param callbacks [Hash] Optional callbacks for real-time event notifications
+    def initialize(context, callbacks: {})
       @context = context
       @usage = Usage.new
+      @callbacks = callbacks || {}
+      @callback_manager = CallbackManager.new(@callbacks)
     end
 
     # Usage tracks token consumption across all LLM calls within a single run.