ai-agents 0.1.0

data/examples/isp-support/interactive.rb

@@ -0,0 +1,135 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../../lib/agents"
+require_relative "agents_factory"
+
+# Simple ISP Customer Support Demo
+class ISPSupportDemo
+  def initialize
+    # Configure the Agents SDK with API key
+    Agents.configure do |config|
+      config.openai_api_key = ENV["OPENAI_API_KEY"]
+    end
+
+    # Create agents
+    @agents = ISPSupport::AgentsFactory.create_agents
+    @triage_agent = @agents[:triage]
+    @context = {}
+
+    puts "🏢 Welcome to ISP Customer Support!"
+    puts "Type '/help' for commands or 'exit' to quit."
+    puts
+  end
+
+  def start
+    loop do
+      print "💬 You: "
+      user_input = gets.chomp.strip
+
+      command_result = handle_command(user_input)
+      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)
+
+      # Update our context with the returned context from Runner
+      @context = result.context if result.respond_to?(:context) && result.context
+
+      puts "🤖 #{result.output || "[No output]"}"
+
+      puts
+    end
+  end
+
+  private
+
+  def handle_command(input)
+    case input.downcase
+    when "exit", "quit"
+      puts "👋 Goodbye!"
+      :exit
+    when "/help"
+      show_help
+      :handled
+    when "/reset"
+      @context.clear
+      puts "🔄 Context reset. Starting fresh conversation."
+      :handled
+    when "/agents"
+      show_agents
+      :handled
+    when "/tools"
+      show_tools
+      :handled
+    when "/context"
+      show_context
+      :handled
+    else
+      :not_command # Not a command, continue with normal processing
+    end
+  end
+
+  def show_help
+    puts "📋 Available Commands:"
+    puts "  /help     - Show this help message"
+    puts "  /reset    - Clear conversation context and start fresh"
+    puts "  /agents   - List all available agents"
+    puts "  /tools    - Show tools available to agents"
+    puts "  /context  - Show current conversation context"
+    puts "  exit/quit - End the session"
+    puts
+    puts "💡 Example customer requests:"
+    puts "  - 'What's my current plan?' (try account ID: CUST001)"
+    puts "  - 'I want to upgrade my internet'"
+    puts "  - 'My internet is slow'"
+  end
+
+  def show_agents
+    puts "🤖 Available Agents:"
+    @agents.each do |key, agent|
+      puts "  #{agent.name} - #{get_agent_description(key)}"
+    end
+  end
+
+  def show_tools
+    puts "🔧 Agent Tools:"
+    @agents.each_value do |agent|
+      puts "  #{agent.name}:"
+      if agent.all_tools.empty?
+        puts "    (no tools)"
+      else
+        agent.all_tools.each do |tool|
+          puts "    - #{tool.name}: #{tool.description}"
+        end
+      end
+    end
+  end
+
+  def show_context
+    puts "📊 Current Context:"
+    if @context.empty?
+      puts "  (empty)"
+    else
+      @context.each do |key, value|
+        puts "  #{key}: #{value}"
+      end
+    end
+  end
+
+  def get_agent_description(key)
+    case key
+    when :triage then "Routes customers to appropriate specialists"
+    when :customer_info then "Handles account information and billing"
+    when :sales then "Manages new sales and upgrades"
+    when :support then "Provides technical support and troubleshooting"
+    else "Unknown agent"
+    end
+  end
+end
+
+# Run the demo
+ISPSupportDemo.new.start if __FILE__ == $PROGRAM_NAME

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+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"
+
+    def perform(_tool_context, plan_name:)
+      session_id = SecureRandom.hex(8)
+      "https://checkout.isp.com/#{session_id}"
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+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"
+
+    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."
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "json"
+
+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)"
+
+    def perform(_tool_context, account_id:)
+      data_file = File.join(__dir__, "../data/customers.json")
+      return "Customer database unavailable" unless File.exist?(data_file)
+
+      begin
+        customers = JSON.parse(File.read(data_file))
+        customer = customers[account_id.upcase]
+
+        return "Customer not found" unless customer
+
+        # Return the entire customer data as JSON for the agent to process
+        customer.to_json
+      rescue StandardError
+        "Error looking up customer"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ISPSupport
+  # Tool for escalating complex issues to human support agents.
+  class EscalateToHumanTool < Agents::Tool
+    description "Escalate the issue to a human support agent"
+
+    def perform(_tool_context)
+      "I'm connecting you to a human support agent. Please hold while I transfer your case. A live agent will be with you shortly to provide personalized assistance."
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+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"
+
+    def perform(_tool_context, query:)
+      case query.downcase
+      when /slow|speed/
+        "Try restarting your modem and router. Unplug for 30 seconds, then plug back in. Test speed at speedtest.net."
+      when /no internet|down|offline/
+        "Check modem lights are solid green. Unplug modem for 30 seconds, then plug back in. Wait 3 minutes for restart."
+      when /wifi|wireless/
+        "Check WiFi is enabled on device. Verify correct password. Move closer to router. Restart router if needed."
+      else
+        "General troubleshooting: Restart modem and router, check cable connections, test with different device."
+      end
+    end
+  end
+end

data/lib/agents/agent.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+# The core agent definition that represents an AI assistant with specific capabilities.
+# Agents are immutable, thread-safe objects that can be cloned with modifications.
+# They encapsulate the configuration needed to interact with an LLM including
+# instructions, tools, and potential handoff targets.
+#
+# @example Creating a basic agent
+#   agent = Agents::Agent.new(
+#     name: "Assistant",
+#     instructions: "You are a helpful assistant",
+#     model: "gpt-4",
+#     tools: [calculator_tool, weather_tool]
+#   )
+#
+# @example Creating an agent with dynamic instructions
+#   agent = Agents::Agent.new(
+#     name: "Support Agent",
+#     instructions: ->(context) {
+#       "You are supporting user #{context.context[:user_name]}"
+#     }
+#   )
+#
+# @example Cloning an agent with modifications
+#   specialized_agent = base_agent.clone(
+#     instructions: "You are a specialized assistant",
+#     tools: base_agent.tools + [new_tool]
+#   )
+module Agents
+  class Agent
+    attr_reader :name, :instructions, :model, :tools, :handoff_agents
+
+    # Initialize a new Agent instance
+    #
+    # @param name [String] The name of the agent
+    # @param instructions [String, Proc, nil] Static string or dynamic Proc that returns instructions
+    # @param model [String] The LLM model to use (default: "gpt-4.1-mini")
+    # @param tools [Array<Agents::Tool>] Array of tool instances the agent can use
+    # @param handoff_agents [Array<Agents::Agent>] Array of agents this agent can hand off to
+    def initialize(name:, instructions: nil, model: "gpt-4.1-mini", tools: [], handoff_agents: [])
+      @name = name
+      @instructions = instructions
+      @model = model
+      @tools = tools.dup
+      @handoff_agents = []
+
+      # Mutex for thread-safe handoff registration
+      # While agents are typically configured at startup, we want to ensure
+      # that concurrent handoff registrations don't result in lost data.
+      # For example, in a web server with multiple threads initializing
+      # different parts of the system, we might have:
+      #   Thread 1: triage.register_handoffs(billing)
+      #   Thread 2: triage.register_handoffs(support)
+      # Without synchronization, one registration could overwrite the other.
+      @mutex = Mutex.new
+
+      # Register initial handoff agents if provided
+      register_handoffs(*handoff_agents) unless handoff_agents.empty?
+    end
+
+    # Get all tools available to this agent, including any auto-generated handoff tools
+    #
+    # @return [Array<Agents::Tool>] All tools available to the agent
+    def all_tools
+      @mutex.synchronize do
+        # Compute handoff tools dynamically
+        handoff_tools = @handoff_agents.map { |agent| HandoffTool.new(agent) }
+        @tools + handoff_tools
+      end
+    end
+
+    # Register agents that this agent can hand off to.
+    # This method can be called after agent creation to set up handoff relationships.
+    # Thread-safe: Multiple threads can safely call this method concurrently.
+    #
+    # @param agents [Array<Agents::Agent>] Agents to register as handoff targets
+    # @return [self] Returns self for method chaining
+    # @example Setting up hub-and-spoke pattern
+    #   # Create agents
+    #   triage = Agent.new(name: "Triage", instructions: "Route to specialists")
+    #   billing = Agent.new(name: "Billing", instructions: "Handle payments")
+    #   support = Agent.new(name: "Support", instructions: "Fix technical issues")
+    #
+    #   # Wire up handoffs after creation - much cleaner than complex factories!
+    #   triage.register_handoffs(billing, support)
+    #   billing.register_handoffs(triage)  # Specialists only handoff back to triage
+    #   support.register_handoffs(triage)
+    def register_handoffs(*agents)
+      @mutex.synchronize do
+        @handoff_agents.concat(agents)
+        @handoff_agents.uniq! # Prevent duplicates
+      end
+      self
+    end
+
+    # Creates a new agent instance with modified attributes while preserving immutability.
+    # The clone method is used when you need to create variations of agents without mutating the original.
+    # This can be used for runtime agent modifications, say in a multi-tenant environment we can do something like the following:
+    #
+    # @example Multi-tenant agent customization
+    #   def agent_for_tenant(tenant)
+    #     @base_agent.clone(
+    #       instructions: "You work for #{tenant.company_name}",
+    #       tools: @base_agent.tools + tenant.custom_tools
+    #     )
+    #   end
+    #
+    # @example Creating specialized variants
+    #   finance_writer = @writer_agent.clone(
+    #     tools: @writer_agent.tools + [financial_research_tool]
+    #   )
+    #
+    #   marketing_writer = @writer_agent.clone(
+    #     tools: @writer_agent.tools + [marketing_research_tool]
+    #   )
+    #
+    # The key insight to note here is that clone ensures immutability - you never accidentally modify a shared agent
+    # instance that other requests might be using. This is critical for thread safety in concurrent
+    # environments.
+    #
+    # This also ensures we also get to leverage the syntax sugar defining a class provides us with.
+    #
+    # @param changes [Hash] Keyword arguments for attributes to change
+    # @option changes [String] :name New agent name
+    # @option changes [String, Proc] :instructions New instructions
+    # @option changes [String] :model New model identifier
+    # @option changes [Array<Agents::Tool>] :tools New tools array (replaces all tools)
+    # @option changes [Array<Agents::Agent>] :handoff_agents New handoff agents
+    # @return [Agents::Agent] A new frozen agent instance with the specified changes
+    def clone(**changes)
+      self.class.new(
+        name: changes.fetch(:name, @name),
+        instructions: changes.fetch(:instructions, @instructions),
+        model: changes.fetch(:model, @model),
+        tools: changes.fetch(:tools, @tools.dup),
+        handoff_agents: changes.fetch(:handoff_agents, @handoff_agents)
+      )
+    end
+
+    # Get the system prompt for the agent, potentially customized based on runtime context.
+    # We will allow setting up a Proc for instructions.
+    # This will allow us the inject context in runtime.
+    #
+    # @example Static instructions (most common)
+    #   agent = Agent.new(
+    #     name: "Support",
+    #     instructions: "You are a helpful support agent"
+    #   )
+    #
+    # @example Dynamic instructions based on context
+    #   agent = Agent.new(
+    #     name: "Support",
+    #     instructions: ->(context) {
+    #       user = context.context[:user]
+    #       "You are helping #{user.name}. They are a #{user.tier} customer with account #{user.id}"
+    #     }
+    #   )
+    #
+    # @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)
+      case instructions
+      when String
+        instructions
+      when Proc
+        instructions.call(context)
+      end
+    end
+  end
+end

data/lib/agents/handoff.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Agents
+  # A special tool that enables agents to transfer conversations to other specialized agents.
+  # Handoffs are implemented as tools (following OpenAI's pattern) because this allows
+  # the LLM to naturally decide when to transfer based on the conversation context.
+  #
+  # ## How Handoffs Work
+  # 1. Agent A is configured with handoff_agents: [Agent B, Agent C]
+  # 2. This automatically creates HandoffTool instances for B and C
+  # 3. The LLM can call these tools like any other tool
+  # 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
+  #
+  # ## Why Tools Instead of Instructions
+  # Using tools for handoffs has several advantages:
+  # - LLMs reliably use tools when appropriate
+  # - Clear schema tells the LLM when each handoff is suitable
+  # - No parsing of free text needed
+  # - Works consistently across different LLM providers
+  #
+  # @example Basic handoff setup
+  #   billing_agent = Agent.new(name: "Billing", instructions: "Handle payments")
+  #   support_agent = Agent.new(name: "Support", instructions: "Technical help")
+  #
+  #   triage = Agent.new(
+  #     name: "Triage",
+  #     instructions: "Route users to the right team",
+  #     handoff_agents: [billing_agent, support_agent]
+  #   )
+  #   # Creates tools: handoff_to_billing, handoff_to_support
+  #
+  # @example How the LLM sees it
+  #   # User: "I can't pay my bill"
+  #   # LLM thinks: "This is a payment issue, I should transfer to billing"
+  #   # LLM calls: handoff_to_billing()
+  #   # Runner switches to billing_agent for the next turn
+  #
+  # @example First-call-wins in action
+  #   # 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)
+  class HandoffTool < Tool
+    attr_reader :target_agent
+
+    def initialize(target_agent)
+      @target_agent = target_agent
+
+      # Set up the tool with a standardized name and description
+      @tool_name = "handoff_to_#{target_agent.name.downcase.gsub(/\s+/, "_")}"
+      @tool_description = "Transfer conversation to #{target_agent.name}"
+
+      super()
+    end
+
+    # Override the auto-generated name to use our specific name
+    def name
+      @tool_name
+    end
+
+    # Override the description
+    def description
+      @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
+      "I'll transfer you to #{@target_agent.name} who can better assist you with this."
+    end
+
+    # NOTE: RubyLLM will handle schema generation internally when needed
+    # Handoff tools have no parameters, which RubyLLM will detect automatically
+  end
+end

data/lib/agents/result.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Agents
+  RunResult = Struct.new(:output, :messages, :usage, :error, :context, keyword_init: true) do
+    def success?
+      error.nil? && !output.nil?
+    end
+
+    def failed?
+      !success?
+    end
+  end
+end

data/lib/agents/run_context.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# RunContext encapsulates the execution context and usage metrics for a single agent run.
+# It provides isolation between concurrent executions by giving each run its own context
+# copy and tracking token usage throughout the execution. This is a key component in
+# ensuring thread safety.
+#
+# @example Creating a RunContext for an agent execution
+#   context_data = { user_id: 123, session: "abc" }
+#   run_context = Agents::RunContext.new(context_data)
+#
+#   # Access context during execution
+#   user_id = run_context.context[:user_id]
+#
+#   # Track usage after LLM calls
+#   run_context.usage.add(llm_response.usage)
+#
+# @example Tracking token usage across multiple LLM calls
+#   run_context = Agents::RunContext.new({})
+#
+#   # First LLM call
+#   response1 = llm.complete(prompt1)
+#   run_context.usage.add(response1.usage)
+#
+#   # Second LLM call
+#   response2 = llm.complete(prompt2)
+#   run_context.usage.add(response2.usage)
+#
+#   # Total usage is automatically accumulated
+#   puts "Total tokens: #{run_context.usage.total_tokens}"
+#
+# @example Thread safety through context isolation
+#   # Shared configuration (never modified)
+#   base_context = { api_key: "secret", model: "gpt-4" }
+#
+#   # Concurrent agent runs using Async
+#   Async do
+#     5.times.map do |i|
+#       Async do
+#         # Each run gets its own context COPY
+#         run_context = Agents::RunContext.new(base_context.dup)
+#
+#         # Safe to modify - changes are isolated to this run
+#         run_context.context[:user_id] = i
+#         run_context.context[:session] = "session_#{i}"
+#
+#         # Other concurrent runs cannot see these changes
+#         puts "Run #{i}: user_id = #{run_context.context[:user_id]}"
+#       end
+#     end.map(&:wait)
+#   end
+#
+#   # Key points:
+#   # - base_context remains unmodified
+#   # - Each run has isolated context via .dup
+#   # - No race conditions or data leakage between runs
+module Agents
+  class RunContext
+    attr_reader :context, :usage
+
+    # 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)
+      @context = context
+      @usage = Usage.new
+    end
+
+    # Usage tracks token consumption across all LLM calls within a single run.
+    # This is very rudimentary usage reporting.
+    # We can use this further for billing purposes, but is not a replacement for tracing.
+    #
+    # @example Accumulating usage from multiple LLM calls
+    #   usage = Agents::RunContext::Usage.new
+    #
+    #   # Add usage from first call
+    #   usage.add(OpenStruct.new(input_tokens: 100, output_tokens: 50, total_tokens: 150))
+    #
+    #   # Add usage from second call
+    #   usage.add(OpenStruct.new(input_tokens: 200, output_tokens: 100, total_tokens: 300))
+    #
+    #   puts usage.total_tokens  # => 450
+    class Usage
+      attr_accessor :input_tokens, :output_tokens, :total_tokens
+
+      # Initialize a new Usage tracker with all counters at zero
+      def initialize
+        @input_tokens = 0
+        @output_tokens = 0
+        @total_tokens = 0
+      end
+
+      # Add usage metrics from an LLM response to the running totals.
+      # Safely handles nil values in the usage object.
+      #
+      # @param usage [Object] An object responding to input_tokens, output_tokens, and total_tokens
+      # @example Adding usage from an LLM response
+      #   usage.add(llm_response.usage)
+      def add(usage)
+        @input_tokens += usage.input_tokens || 0
+        @output_tokens += usage.output_tokens || 0
+        @total_tokens += usage.total_tokens || 0
+      end
+    end
+  end
+end