ai-agents 0.1.0 → 0.1.2

data/examples/isp-support/interactive.rb

@@ -1,6 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+require "json"
 require_relative "../../lib/agents"
 require_relative "agents_factory"
 
@@ -13,8 +14,15 @@ class ISPSupportDemo
     end
 
     # Create agents
-    @agents = ISPSupport::AgentsFactory.create_agents
-    @triage_agent = @agents[:triage]
+    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]
+    )
+
     @context = {}
 
     puts "🏢 Welcome to ISP Customer Support!"
@@ -31,10 +39,8 @@ class ISPSupportDemo
       break if command_result == :exit
       next if command_result == :handled || user_input.empty?
 
-      # Determine which agent to use - either from context or triage agent
-      current_agent = @context[:current_agent] || @triage_agent
-
-      result = Agents::Runner.run(current_agent, user_input, context: @context)
+      # 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
@@ -50,6 +56,7 @@ class ISPSupportDemo
   def handle_command(input)
     case input.downcase
     when "exit", "quit"
+      dump_context_and_quit
       puts "👋 Goodbye!"
       :exit
     when "/help"
@@ -73,6 +80,21 @@ class ISPSupportDemo
     end
   end
 
+  def dump_context_and_quit
+    project_root = File.expand_path("../..", __dir__)
+    tmp_directory = File.join(project_root, "tmp")
+
+    # Ensure tmp directory exists
+    Dir.mkdir(tmp_directory) unless Dir.exist?(tmp_directory)
+
+    timestamp = Time.now.to_i
+    context_filename = File.join(tmp_directory, "context-#{timestamp}.json")
+
+    File.write(context_filename, JSON.pretty_generate(@context))
+
+    puts "💾 Context saved to tmp/context-#{timestamp}.json"
+  end
+
   def show_help
     puts "📋 Available Commands:"
     puts "  /help     - Show this help message"

data/examples/isp-support/tools/create_checkout_tool.rb

@@ -6,7 +6,7 @@ module ISPSupport
   # Tool for creating checkout links for new service subscriptions.
   class CreateCheckoutTool < Agents::Tool
     description "Create a secure checkout link for a service plan"
-    param :plan_name, String, "Name of the plan to purchase"
+    param :plan_name, type: "string", desc: "Name of the plan to purchase"
 
     def perform(_tool_context, plan_name:)
       session_id = SecureRandom.hex(8)

data/examples/isp-support/tools/create_lead_tool.rb

@@ -4,12 +4,26 @@ module ISPSupport
   # Tool for creating sales leads in the CRM system.
   class CreateLeadTool < Agents::Tool
     description "Create a new sales lead with customer information"
-    param :name, String, "Customer's full name"
-    param :email, String, "Customer's email address"
-    param :desired_plan, String, "Plan the customer is interested in"
+    param :name, type: "string", desc: "Customer's full name"
+    param :email, type: "string", desc: "Customer's email address"
+    param :desired_plan, type: "string", desc: "Plan the customer is interested in"
 
-    def perform(_tool_context, name:, email:, desired_plan:)
-      "Lead created for #{name} (#{email}) interested in #{desired_plan} plan. Sales team will contact within 24 hours."
+    def perform(tool_context, name:, email:, desired_plan:)
+      # Store lead information in state for follow-up
+      tool_context.state[:lead_name] = name
+      tool_context.state[:lead_email] = email
+      tool_context.state[:desired_plan] = desired_plan
+      tool_context.state[:lead_created_at] = Time.now.iso8601
+
+      # Check if we have existing customer info from CRM lookup
+      if tool_context.state[:customer_id]
+        existing_customer = tool_context.state[:customer_name]
+        "Lead created for existing customer #{existing_customer} (#{email}) " \
+        "interested in upgrading to #{desired_plan} plan. Sales team will contact within 24 hours."
+      else
+        "Lead created for #{name} (#{email}) interested in #{desired_plan} plan. " \
+        "Sales team will contact within 24 hours."
+      end
     end
   end
 end

data/examples/isp-support/tools/crm_lookup_tool.rb

@@ -6,9 +6,9 @@ module ISPSupport
   # Tool for looking up customer information from the CRM system.
   class CrmLookupTool < Agents::Tool
     description "Look up customer account information by account ID"
-    param :account_id, String, "Customer account ID (e.g., CUST001)"
+    param :account_id, type: "string", desc: "Customer account ID (e.g., CUST001)"
 
-    def perform(_tool_context, account_id:)
+    def perform(tool_context, account_id:)
       data_file = File.join(__dir__, "../data/customers.json")
       return "Customer database unavailable" unless File.exist?(data_file)
 
@@ -18,6 +18,18 @@ module ISPSupport
 
         return "Customer not found" unless customer
 
+        # Store customer information in shared state for other tools/agents
+        tool_context.state[:customer_id] = account_id.upcase
+        tool_context.state[:customer_name] = customer["name"]
+        tool_context.state[:customer_email] = customer["email"]
+        tool_context.state[:customer_phone] = customer["phone"]
+        tool_context.state[:customer_address] = customer["address"]
+        tool_context.state[:current_plan] = customer["plan"]["name"]
+        tool_context.state[:account_status] = customer["account_status"]
+        tool_context.state[:plan_price] = customer["plan"]["price"]
+        tool_context.state[:next_bill_date] = customer["billing"]["next_bill_date"]
+        tool_context.state[:account_balance] = customer["billing"]["balance"]
+
         # Return the entire customer data as JSON for the agent to process
         customer.to_json
       rescue StandardError

data/examples/isp-support/tools/search_docs_tool.rb

@@ -4,7 +4,7 @@ module ISPSupport
   # Tool for searching the knowledge base documentation.
   class SearchDocsTool < Agents::Tool
     description "Search knowledge base for troubleshooting steps and solutions"
-    param :query, String, "Search terms or description of the issue"
+    param :query, type: "string", desc: "Search terms or description of the issue"
 
     def perform(_tool_context, query:)
       case query.downcase

data/lib/agents/agent.rb

@@ -13,11 +13,16 @@
 #     tools: [calculator_tool, weather_tool]
 #   )
 #
-# @example Creating an agent with dynamic instructions
+# @example Creating an agent with dynamic state-aware instructions
 #   agent = Agents::Agent.new(
 #     name: "Support Agent",
 #     instructions: ->(context) {
-#       "You are supporting user #{context.context[:user_name]}"
+#       state = context.context[:state] || {}
+#       base = "You are a support agent."
+#       if state[:customer_name]
+#         base += " Customer: #{state[:customer_name]} (#{state[:customer_id]})"
+#       end
+#       base
 #     }
 #   )
 #
@@ -147,18 +152,25 @@ module Agents
     #     instructions: "You are a helpful support agent"
     #   )
     #
-    # @example Dynamic instructions based on context
+    # @example Dynamic instructions with state awareness
     #   agent = Agent.new(
-    #     name: "Support",
+    #     name: "Sales Agent",
     #     instructions: ->(context) {
-    #       user = context.context[:user]
-    #       "You are helping #{user.name}. They are a #{user.tier} customer with account #{user.id}"
+    #       state = context.context[:state] || {}
+    #       base = "You are a sales agent."
+    #       if state[:customer_name] && state[:current_plan]
+    #         base += " Customer: #{state[:customer_name]} on #{state[:current_plan]} plan."
+    #       end
+    #       base
     #     }
     #   )
     #
     # @param context [Agents::RunContext] The current execution context containing runtime data
     # @return [String, nil] The system prompt string or nil if no instructions are set
     def get_system_prompt(context)
+      # TODO: Add string interpolation support for instructions
+      # Allow instructions like "You are helping %{customer_name}" that automatically
+      # get state values injected from context[:state] using Ruby's % formatting
       case instructions
       when String
         instructions

data/lib/agents/agent_runner.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Agents
+  # Thread-safe agent execution manager that provides a clean API for multi-agent conversations.
+  # This class is designed to be created once and reused across multiple threads safely.
+  #
+  # The key insight here is separating agent registry/configuration (this class) from
+  # execution state (Runner instances). This allows the same AgentRunner to be used
+  # concurrently without thread safety issues.
+  #
+  # ## Usage Pattern
+  #   # Create once (typically at application startup)
+  #   runner = Agents::Runner.with_agents(triage_agent, billing_agent, support_agent)
+  #
+  #   # Use safely from multiple threads
+  #   result = runner.run("I need billing help")           # New conversation
+  #   result = runner.run("More help", context: context)   # Continue conversation
+  #
+  # ## Thread Safety Design
+  # - All instance variables are frozen after initialization (immutable state)
+  # - Agent registry is built once and never modified
+  # - Each run() call creates independent execution context
+  # - No shared mutable state between concurrent executions
+  #
+  class AgentRunner
+    # Initialize with a list of agents. The first agent becomes the default entry point.
+    #
+    # @param agents [Array<Agents::Agent>] List of agents, first one is the default entry point
+    def initialize(agents)
+      raise ArgumentError, "At least one agent must be provided" if agents.empty?
+
+      @agents = agents.dup.freeze
+      @default_agent = agents.first
+
+      # Build simple registry from provided agents - developer controls what's available
+      @registry = build_registry(agents).freeze
+    end
+
+    # Execute a conversation turn with automatic agent selection.
+    # For new conversations, uses the default agent (first in the list).
+    # For continuing conversations, determines the appropriate agent from conversation history.
+    #
+    # @param input [String] User's message
+    # @param context [Hash] Conversation context (will be restored if continuing conversation)
+    # @param max_turns [Integer] Maximum turns before stopping (default: 10)
+    # @return [RunResult] Execution result with output, messages, and updated context
+    def run(input, context: {}, max_turns: Runner::DEFAULT_MAX_TURNS)
+      # Determine which agent should handle this conversation
+      # Uses conversation history to maintain continuity across handoffs
+      current_agent = determine_conversation_agent(context)
+
+      # Execute using stateless Runner - each execution is independent and thread-safe
+      Runner.new.run(
+        current_agent,
+        input,
+        context: context,
+        registry: @registry,
+        max_turns: max_turns
+      )
+    end
+
+    private
+
+    # Build agent registry from provided agents only.
+    # Developer explicitly controls which agents are available for handoffs.
+    #
+    # @param agents [Array<Agents::Agent>] Agents to register
+    # @return [Hash<String, Agents::Agent>] Registry mapping agent names to agent instances
+    def build_registry(agents)
+      registry = {}
+      agents.each { |agent| registry[agent.name] = agent }
+      registry
+    end
+
+    # Determine which agent should handle the current conversation.
+    # For new conversations (empty context), uses the default agent.
+    # For continuing conversations, analyzes history to find the last agent that spoke.
+    #
+    # This implements Google ADK-style session continuation logic where the system
+    # automatically maintains conversation continuity without requiring manual agent tracking.
+    #
+    # @param context [Hash] Conversation context with potential history
+    # @return [Agents::Agent] Agent that should handle this conversation turn
+    def determine_conversation_agent(context)
+      history = context[:conversation_history] || []
+
+      # For new conversations, use the default (first) agent
+      return @default_agent if history.empty?
+
+      # Find the last assistant message with agent attribution
+      # We traverse in reverse to find the most recent agent that spoke
+      last_agent_name = history.reverse.find do |msg|
+        msg[:role] == :assistant && msg[:agent_name]
+      end&.dig(:agent_name)
+
+      # Try to resolve from registry, fall back to default if agent not found
+      # This handles cases where agent names in history don't match current registry
+      if last_agent_name && @registry[last_agent_name]
+        @registry[last_agent_name]
+      else
+        @default_agent
+      end
+    end
+  end
+end

data/lib/agents/chat.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require_relative "tool_context"
+
+module Agents
+  # Extended chat class that inherits from RubyLLM::Chat but adds proper handoff handling.
+  # This solves the infinite handoff loop problem by treating handoffs as turn-ending
+  # operations rather than allowing auto-continuation.
+  class Chat < RubyLLM::Chat
+    # Response object that indicates a handoff occurred
+    class HandoffResponse
+      attr_reader :target_agent, :response, :handoff_message
+
+      def initialize(target_agent:, response:, handoff_message:)
+        @target_agent = target_agent
+        @response = response
+        @handoff_message = handoff_message
+      end
+
+      def tool_call?
+        true
+      end
+
+      def content
+        @handoff_message
+      end
+    end
+
+    def initialize(model: nil, handoff_tools: [], context_wrapper: nil, **options)
+      super(model: model, **options)
+      @handoff_tools = handoff_tools
+      @context_wrapper = context_wrapper
+
+      # Register handoff tools with RubyLLM for schema generation
+      @handoff_tools.each { |tool| with_tool(tool) }
+    end
+
+    # Override the problematic auto-execution method from RubyLLM::Chat
+    def complete(&block)
+      @on[:new_message]&.call
+      response = @provider.complete(
+        messages,
+        tools: @tools,
+        temperature: @temperature,
+        model: @model.id,
+        connection: @connection,
+        &block
+      )
+      @on[:end_message]&.call(response)
+
+      add_message(response)
+
+      if response.tool_call?
+        handle_tools_with_handoff_detection(response, &block)
+      else
+        response
+      end
+    end
+
+    private
+
+    def handle_tools_with_handoff_detection(response, &block)
+      handoff_calls, regular_calls = classify_tool_calls(response.tool_calls)
+
+      if handoff_calls.any?
+        # Execute first handoff only
+        handoff_result = execute_handoff_tool(handoff_calls.first)
+
+        # Add tool result to conversation
+        add_tool_result(handoff_calls.first.id, handoff_result[:message])
+
+        # Return handoff response to signal agent switch (ends turn)
+        HandoffResponse.new(
+          target_agent: handoff_result[:target_agent],
+          response: response,
+          handoff_message: handoff_result[:message]
+        )
+      else
+        # Use RubyLLM's original tool execution for regular tools
+        execute_regular_tools_and_continue(regular_calls, &block)
+      end
+    end
+
+    def classify_tool_calls(tool_calls)
+      handoff_tool_names = @handoff_tools.map(&:name).map(&:to_s)
+
+      handoff_calls = []
+      regular_calls = []
+
+      tool_calls.each_value do |tool_call|
+        if handoff_tool_names.include?(tool_call.name)
+          handoff_calls << tool_call
+        else
+          regular_calls << tool_call
+        end
+      end
+
+      [handoff_calls, regular_calls]
+    end
+
+    def execute_handoff_tool(tool_call)
+      tool = @handoff_tools.find { |t| t.name.to_s == tool_call.name }
+      raise "Handoff tool not found: #{tool_call.name}" unless tool
+
+      # Execute the handoff tool directly with context
+      tool_context = ToolContext.new(run_context: @context_wrapper)
+      result = tool.execute(tool_context, **{}) # Handoff tools take no additional params
+
+      {
+        target_agent: tool.target_agent,
+        message: result.to_s
+      }
+    end
+
+    def execute_regular_tools_and_continue(tool_calls, &block)
+      # Execute each regular tool call
+      tool_calls.each do |tool_call|
+        @on[:new_message]&.call
+        result = execute_tool(tool_call)
+        message = add_tool_result(tool_call.id, result)
+        @on[:end_message]&.call(message)
+      end
+
+      # Continue conversation after tool execution
+      complete(&block)
+    end
+
+    # Reuse RubyLLM's existing tool execution logic
+    def execute_tool(tool_call)
+      tool = tools[tool_call.name.to_sym]
+      args = tool_call.arguments
+      tool.call(args)
+    end
+
+    def add_tool_result(tool_use_id, result)
+      add_message(
+        role: :tool,
+        content: result.is_a?(Hash) && result[:error] ? result[:error] : result.to_s,
+        tool_call_id: tool_use_id
+      )
+    end
+  end
+end

data/lib/agents/handoff.rb

@@ -95,18 +95,10 @@ module Agents
       @tool_description
     end
 
-    # Handoff tools implement first-call-wins semantics to prevent infinite loops
-    # Multiple handoff calls in a single response are ignored (like OpenAI SDK)
-    def perform(tool_context)
-      # First-call-wins: only set handoff if not already set
-      if tool_context.context[:pending_handoff]
-        return "Transfer request noted (already processing a handoff)."
-      end
-
-      # Set the handoff target
-      tool_context.context[:pending_handoff] = @target_agent
-
-      # Return a message that will be shown to the user
+    # Handoff tools now work with the extended Chat class for proper handoff handling
+    # No longer need context signaling - the Chat class detects handoffs directly
+    def perform(_tool_context)
+      # Simply return the transfer message - Chat class will handle the handoff
       "I'll transfer you to #{@target_agent.name} who can better assist you with this."
     end
 

data/lib/agents/runner.rb

@@ -54,21 +54,33 @@ module Agents
 
     class MaxTurnsExceeded < StandardError; end
 
-    # Convenience class method for running agents
-    def self.run(agent, input, context: {}, max_turns: DEFAULT_MAX_TURNS)
-      new.run(agent, input, context: context, max_turns: max_turns)
+    # Create a thread-safe agent runner for multi-agent conversations.
+    # The first agent becomes the default entry point for new conversations.
+    # All agents must be explicitly provided - no automatic discovery.
+    #
+    # @param agents [Array<Agents::Agent>] All agents that should be available for handoffs
+    # @return [AgentRunner] Thread-safe runner that can be reused across multiple conversations
+    #
+    # @example
+    #   runner = Agents::Runner.with_agents(triage_agent, billing_agent, support_agent)
+    #   result = runner.run("I need help")  # Uses triage_agent for new conversation
+    #   result = runner.run("More help", context: stored_context)  # Continues with appropriate agent
+    def self.with_agents(*agents)
+      AgentRunner.new(agents)
     end
 
-    # Execute an agent with the given input and context
+    # Execute an agent with the given input and context.
+    # This is now called internally by AgentRunner and should not be used directly.
     #
-    # @param starting_agent [Agents::Agent] The initial agent to run
+    # @param starting_agent [Agents::Agent] The agent to run
     # @param input [String] The user's input message
     # @param context [Hash] Shared context data accessible to all tools
+    # @param registry [Hash] Registry of agents for handoff resolution
     # @param max_turns [Integer] Maximum conversation turns before stopping
     # @return [RunResult] The result containing output, messages, and usage
-    def run(starting_agent, input, context: {}, max_turns: DEFAULT_MAX_TURNS)
-      # Determine current agent from context or use starting agent
-      current_agent = context[:current_agent] || starting_agent
+    def run(starting_agent, input, context: {}, registry: {}, max_turns: DEFAULT_MAX_TURNS)
+      # The starting_agent is already determined by AgentRunner based on conversation history
+      current_agent = starting_agent
 
       # Create context wrapper with deep copy for thread safety
       context_copy = deep_copy_context(context)
@@ -83,44 +95,55 @@ module Agents
         current_turn += 1
         raise MaxTurnsExceeded, "Exceeded maximum turns: #{max_turns}" if current_turn > max_turns
 
-        # Get response from LLM (RubyLLM handles tool execution)
-        response = if current_turn == 1
-                     chat.ask(input)
-                   else
-                     chat.complete
-                   end
+        # Get response from LLM (Extended Chat handles tool execution with handoff detection)
+        result = if current_turn == 1
+                   chat.ask(input)
+                 else
+                   chat.complete
+                 end
+        response = result
 
-        # Update usage
-        context_wrapper.usage.add(response.usage) if response.respond_to?(:usage) && response.usage
+        # Check for handoff response from our extended chat
+        if response.is_a?(Agents::Chat::HandoffResponse)
+          next_agent = response.target_agent
 
-        # Check for handoff via context (set by HandoffTool)
-        if context_wrapper.context[:pending_handoff]
-          next_agent = context_wrapper.context[:pending_handoff]
-          puts "[Agents] Handoff from #{current_agent.name} to #{next_agent.name}"
+          # Validate that the target agent is in our registry
+          # This prevents handoffs to agents that weren't explicitly provided
+          unless registry[next_agent.name]
+            puts "[Agents] Warning: Handoff to unregistered agent '#{next_agent.name}', continuing with current agent"
+            next if response.tool_call?
+
+            next
+          end
 
           # Save current conversation state before switching
           save_conversation_state(chat, context_wrapper, current_agent)
 
-          # Switch to new agent
+          # Switch to new agent - store agent name for persistence
           current_agent = next_agent
-          context_wrapper.context[:current_agent] = next_agent
-          context_wrapper.context.delete(:pending_handoff)
+          context_wrapper.context[:current_agent] = next_agent.name
 
           # Create new chat for new agent with restored history
           chat = create_chat(current_agent, context_wrapper)
           restore_conversation_history(chat, context_wrapper)
+
+          # Force the new agent to respond to the conversation context
+          # This ensures the user gets a response from the new agent
+          input = nil
           next
         end
 
-        # If no tools were called, we have our final response
+        # If tools were called, continue the loop to let them execute
         next if response.tool_call?
 
+        # If no tools were called, we have our final response
+
         # Save final state before returning
         save_conversation_state(chat, context_wrapper, current_agent)
 
         return RunResult.new(
           output: response.content,
-          messages: extract_messages(chat),
+          messages: extract_messages(chat, current_agent),
           usage: context_wrapper.usage,
           context: context_wrapper.context
         )
@@ -131,7 +154,7 @@ module Agents
 
       RunResult.new(
         output: "Conversation ended: #{e.message}",
-        messages: chat ? extract_messages(chat) : [],
+        messages: chat ? extract_messages(chat, current_agent) : [],
         usage: context_wrapper.usage,
         error: e,
         context: context_wrapper.context
@@ -142,7 +165,7 @@ module Agents
 
       RunResult.new(
         output: nil,
-        messages: chat ? extract_messages(chat) : [],
+        messages: chat ? extract_messages(chat, current_agent) : [],
         usage: context_wrapper.usage,
         error: e,
         context: context_wrapper.context
@@ -185,11 +208,11 @@ module Agents
 
     def save_conversation_state(chat, context_wrapper, current_agent)
       # Extract messages from chat
-      messages = extract_messages(chat)
+      messages = extract_messages(chat, current_agent)
 
       # Update context with latest state
       context_wrapper.context[:conversation_history] = messages
-      context_wrapper.context[:current_agent] = current_agent
+      context_wrapper.context[:current_agent] = current_agent.name
       context_wrapper.context[:turn_count] = (context_wrapper.context[:turn_count] || 0) + 1
       context_wrapper.context[:last_updated] = Time.now
 
@@ -203,19 +226,26 @@ module Agents
       # Get system prompt (may be dynamic)
       system_prompt = agent.get_system_prompt(context_wrapper)
 
-      # Wrap tools with context for thread-safe execution
-      wrapped_tools = agent.all_tools.map do |tool|
-        ToolWrapper.new(tool, context_wrapper)
-      end
+      # Separate handoff tools from regular tools
+      handoff_tools = agent.handoff_agents.map { |target_agent| HandoffTool.new(target_agent) }
+      regular_tools = agent.tools
+
+      # Only wrap regular tools - handoff tools will be handled directly by Chat
+      wrapped_regular_tools = regular_tools.map { |tool| ToolWrapper.new(tool, context_wrapper) }
+
+      # Create extended chat with handoff awareness and context
+      chat = Agents::Chat.new(
+        model: agent.model,
+        handoff_tools: handoff_tools,        # Direct tools, no wrapper
+        context_wrapper: context_wrapper     # Pass context directly
+      )
 
-      # Create chat with proper RubyLLM API
-      chat = RubyLLM.chat(model: agent.model)
       chat.with_instructions(system_prompt) if system_prompt
-      chat.with_tools(*wrapped_tools) if wrapped_tools.any?
+      chat.with_tools(*wrapped_regular_tools) if wrapped_regular_tools.any?
       chat
     end
 
-    def extract_messages(chat)
+    def extract_messages(chat, current_agent)
       return [] unless chat.respond_to?(:messages)
 
       chat.messages.filter_map do |msg|
@@ -223,10 +253,16 @@ module Agents
         next unless %i[user assistant].include?(msg.role)
         next unless msg.content && !msg.content.strip.empty?
 
-        {
+        message = {
           role: msg.role,
           content: msg.content
         }
+
+        # Add agent attribution for assistant messages to enable conversation continuity
+        # This allows AgentRunner to determine which agent should continue the conversation
+        message[:agent_name] = current_agent.name if msg.role == :assistant && current_agent
+
+        message
       end
     end
   end