ai-agents 0.4.3 → 0.6.0

data/examples/isp-support/agents_factory.rb

@@ -6,6 +6,7 @@ require_relative "tools/create_lead_tool"
 require_relative "tools/create_checkout_tool"
 require_relative "tools/search_docs_tool"
 require_relative "tools/escalate_to_human_tool"
+require "ruby_llm/schema"
 
 module ISPSupport
   # Factory for creating all ISP support agents with proper handoff relationships.
@@ -56,7 +57,8 @@ module ISPSupport
         instructions: sales_instructions_with_state,
         model: "gpt-4.1-mini",
         tools: [ISPSupport::CreateLeadTool.new, ISPSupport::CreateCheckoutTool.new],
-        temperature: 0.8  # Higher temperature for more persuasive, varied sales language
+        temperature: 0.8, # Higher temperature for more persuasive, varied sales language
+        response_schema: sales_response_schema
       )
     end
 
@@ -70,7 +72,8 @@ module ISPSupport
           ISPSupport::SearchDocsTool.new,
           ISPSupport::EscalateToHumanTool.new
         ],
-        temperature: 0.5  # Balanced temperature for helpful but consistent technical support
+        temperature: 0.5, # Balanced temperature for helpful but consistent technical support
+        response_schema: triage_response_schema
       )
     end
 
@@ -90,40 +93,38 @@ module ISPSupport
 
         Keep responses brief and professional. Use handoff tools to transfer to specialists.
 
-        Your response MUST be in the required JSON format with greeting, intent_category, needs_clarification, clarifying_question, and recommended_agent fields.
+        Your response MUST be in the required JSON format with response, clarifying_question, needs_clarification, and intent fields.
       INSTRUCTIONS
     end
 
     def triage_response_schema
-      {
-        type: "object",
-        properties: {
-          greeting: {
-            type: "string",
-            description: "A brief, friendly greeting acknowledging the customer's inquiry"
-          },
-          intent_category: {
-            type: "string",
-            enum: %w[sales support unclear],
-            description: "The detected category of the customer's intent"
-          },
-          needs_clarification: {
-            type: "boolean",
-            description: "Whether the intent is unclear and needs clarification"
-          },
-          clarifying_question: {
-            type: ["string", "null"],
-            description: "A question to ask if the intent is unclear (null if clear)"
-          },
-          recommended_agent: {
-            type: ["string", "null"],
-            enum: ["Sales Agent", "Support Agent", null],
-            description: "The recommended specialist agent to route to (null if unclear)"
-          }
-        },
-        required: %w[greeting intent_category needs_clarification],
-        additionalProperties: false
-      }
+      RubyLLM::Schema.create do
+        string :response, description: "Your response to the customer"
+        string :intent, enum: %w[sales support unclear], description: "The detected intent category"
+        array :sentiment, description: "Customer sentiment indicators" do
+          string enum: %w[positive neutral negative frustrated urgent confused satisfied]
+        end
+      end
+    end
+
+    def support_response_schema
+      RubyLLM::Schema.create do
+        string :response, description: "Your response to the customer"
+        string :intent, enum: %w[support], description: "The intent category (always support)"
+        array :sentiment, description: "Customer sentiment indicators" do
+          string enum: %w[positive neutral negative frustrated urgent confused satisfied]
+        end
+      end
+    end
+
+    def sales_response_schema
+      RubyLLM::Schema.create do
+        string :response, description: "Your response to the customer"
+        string :intent, enum: %w[sales], description: "The intent category (always sales)"
+        array :sentiment, description: "Customer sentiment indicators" do
+          string enum: %w[positive neutral negative frustrated urgent confused satisfied]
+        end
+      end
     end
 
     def sales_instructions

data/examples/isp-support/interactive.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "readline"
 require_relative "../../lib/agents"
 require_relative "agents_factory"
 
@@ -29,78 +30,96 @@ class ISPSupportDemo
     @context = {}
     @current_status = ""
 
-    puts "🏢 Welcome to ISP Customer Support!"
-    puts "Type '/help' for commands or 'exit' to quit."
+    puts green("🏢 Welcome to ISP Customer Support!")
+    puts dim_text("Type '/help' for commands or 'exit' to quit.")
     puts
   end
 
   def start
     loop do
-      print "💬 You: "
-      user_input = gets.chomp.strip
+      user_input = Readline.readline(cyan("\u{1F4AC} You: "), true)
+      next unless user_input # Handle Ctrl+D
 
+      user_input = user_input.strip
       command_result = handle_command(user_input)
       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..."
+      print yellow("🤖 Processing...")
 
-      # Use the runner - it automatically determines the right agent from context
-      result = @runner.run(user_input, context: @context)
+      begin
+        # 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
+        # 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
+        # Clear status and show response with callback history
+        clear_status_line
+
+        # Display callback messages if any
+        if @callback_messages.any?
+          puts dim_text(@callback_messages.join("\n"))
+          @callback_messages.clear
+        end
 
-      # Handle structured output from triage agent
-      output = result.output || "[No output]"
-      if @context[:current_agent] == "Triage Agent" && output.start_with?("{")
-        begin
-          structured = JSON.parse(output)
-          # Display the greeting from structured response
-          puts "🤖 #{structured["greeting"]}"
-          if structured["intent_category"]
-            puts "   [Intent: #{structured["intent_category"]}, Routing to: #{structured["recommended_agent"] || "TBD"}]"
-          end
-        rescue JSON::ParserError
-          # Fall back to regular output if not valid JSON
+        # Handle structured output from agents
+        output = result.output || "[No output]"
+
+        if output.is_a?(Hash) && output.key?("response")
+          # Display the response from structured response
+          puts "🤖 #{output["response"]}"
+          puts dim_text("   [Intent]: #{output["intent"]}") if output["intent"]
+          puts dim_text("   [Sentiment]: #{output["sentiment"].join(", ")}") if output["sentiment"]&.any?
+        else
           puts "🤖 #{output}"
         end
-      else
-        puts "🤖 #{output}"
-      end
 
-      puts
+        puts # Add blank line after agent response
+      rescue StandardError => e
+        clear_status_line
+        puts red("❌ Error: #{e.message}")
+        puts dim_text("Please try again or type '/help' for assistance.")
+        puts # Add blank line after error message
+      end
     end
   end
 
   private
 
   def setup_callbacks
+    @callback_messages = []
+
     @runner.on_agent_thinking do |agent_name, _input|
-      update_status("🧠 #{agent_name} is thinking...")
+      message = "🧠 #{agent_name} is thinking..."
+      update_status(message)
+      @callback_messages << message
     end
 
     @runner.on_tool_start do |tool_name, _args|
-      update_status("🔧 Using #{tool_name}...")
+      message = "🔧 Using #{tool_name}..."
+      update_status(message)
+      @callback_messages << message
     end
 
     @runner.on_tool_complete do |tool_name, _result|
-      update_status("✅ #{tool_name} completed")
+      message = "✅ #{tool_name} completed"
+      update_status(message)
+      @callback_messages << message
     end
 
     @runner.on_agent_handoff do |from_agent, to_agent, _reason|
-      update_status("🔄 Handoff: #{from_agent} → #{to_agent}")
+      message = "🔄 Handoff: #{from_agent} → #{to_agent}"
+      update_status(message)
+      @callback_messages << message
     end
   end
 
   def update_status(message)
     clear_status_line
-    print message
+    print dim_text(message)
     $stdout.flush
   end
 
@@ -207,6 +226,27 @@ class ISPSupportDemo
     else "Unknown agent"
     end
   end
+
+  # ANSI color helper methods
+  def dim_text(text)
+    "\e[90m#{text}\e[0m"
+  end
+
+  def green(text)
+    "\e[32m#{text}\e[0m"
+  end
+
+  def yellow(text)
+    "\e[33m#{text}\e[0m"
+  end
+
+  def red(text)
+    "\e[31m#{text}\e[0m"
+  end
+
+  def cyan(text)
+    "\e[36m#{text}\e[0m"
+  end
 end
 
 # Run the demo

data/lib/agents/agent.rb

@@ -4,7 +4,7 @@
 # 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.
-#
+require_relative "helpers/headers"
 # @example Creating a basic agent
 #   agent = Agents::Agent.new(
 #     name: "Assistant",
@@ -50,7 +50,7 @@
 #   )
 module Agents
   class Agent
-    attr_reader :name, :instructions, :model, :tools, :handoff_agents, :temperature, :response_schema
+    attr_reader :name, :instructions, :model, :tools, :handoff_agents, :temperature, :response_schema, :headers
 
     # Initialize a new Agent instance
     #
@@ -61,8 +61,9 @@ module Agents
     # @param handoff_agents [Array<Agents::Agent>] Array of agents this agent can hand off to
     # @param temperature [Float] Controls randomness in responses (0.0 = deterministic, 1.0 = very random, default: 0.7)
     # @param response_schema [Hash, nil] JSON schema for structured output responses
+    # @param headers [Hash, nil] Default HTTP headers applied to LLM requests
     def initialize(name:, instructions: nil, model: "gpt-4.1-mini", tools: [], handoff_agents: [], temperature: 0.7,
-                   response_schema: nil)
+                   response_schema: nil, headers: nil)
       @name = name
       @instructions = instructions
       @model = model
@@ -70,6 +71,7 @@ module Agents
       @handoff_agents = []
       @temperature = temperature
       @response_schema = response_schema
+      @headers = Helpers::Headers.normalize(headers, freeze_result: true)
 
       # Mutex for thread-safe handoff registration
       # While agents are typically configured at startup, we want to ensure
@@ -164,7 +166,8 @@ module Agents
         tools: changes.fetch(:tools, @tools.dup),
         handoff_agents: changes.fetch(:handoff_agents, @handoff_agents),
         temperature: changes.fetch(:temperature, @temperature),
-        response_schema: changes.fetch(:response_schema, @response_schema)
+        response_schema: changes.fetch(:response_schema, @response_schema),
+        headers: changes.fetch(:headers, @headers)
       )
     end
 

data/lib/agents/agent_runner.rb

@@ -58,12 +58,12 @@ module Agents
     # @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)
+    # @param headers [Hash, nil] Custom HTTP headers to pass through to the underlying LLM provider
     # @return [RunResult] Execution result with output, messages, and updated context
-    def run(input, context: {}, max_turns: Runner::DEFAULT_MAX_TURNS)
+    def run(input, context: {}, max_turns: Runner::DEFAULT_MAX_TURNS, headers: nil)
       # 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
       # Pass callbacks to enable real-time event notifications
       Runner.new.run(
@@ -72,6 +72,7 @@ module Agents
         context: context,
         registry: @registry,
         max_turns: max_turns,
+        headers: headers,
         callbacks: @callbacks
       )
     end

data/lib/agents/handoff.rb

@@ -69,11 +69,19 @@ module Agents
       @tool_description
     end
 
-    # 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."
+    # Use RubyLLM's halt mechanism to stop continuation after handoff
+    # Store handoff info in context for Runner to detect and process
+    def perform(tool_context)
+      # Store handoff information in context for Runner to detect
+      # TODO: The following is a race condition that needs to be addressed in future versions
+      # If multiple handoff tools execute concurrently, they overwrite each other's pending_handoff data.
+      tool_context.run_context.context[:pending_handoff] = {
+        target_agent: @target_agent,
+        timestamp: Time.now
+      }
+
+      # Return halt to stop LLM continuation
+      halt("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

data/lib/agents/helpers/headers.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Agents::Helpers::Headers
+  module_function
+
+  def normalize(headers, freeze_result: false)
+    return freeze_result ? {}.freeze : {} if headers.nil? || (headers.respond_to?(:empty?) && headers.empty?)
+
+    hash = headers.respond_to?(:to_h) ? headers.to_h : headers
+    raise ArgumentError, "headers must be a Hash or respond to #to_h" unless hash.is_a?(Hash)
+
+    result = symbolize_keys(hash)
+    freeze_result ? result.freeze : result
+  end
+
+  def merge(agent_headers, runtime_headers)
+    return runtime_headers if agent_headers.empty?
+    return agent_headers if runtime_headers.empty?
+
+    agent_headers.merge(runtime_headers) { |_key, _agent_value, runtime_value| runtime_value }
+  end
+
+  def symbolize_keys(hash)
+    hash.each_with_object({}) do |(key, value), memo|
+      memo[key.is_a?(Symbol) ? key : key.to_sym] = value
+    end
+  end
+  private_class_method :symbolize_keys
+end

data/lib/agents/helpers/message_extractor.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# 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 = Agents::Helpers::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" }
+#   ]
+module Agents::Helpers::MessageExtractor
+  module_function
+
+  # Check if content is considered empty (handles both String and Hash content)
+  #
+  # @param content [String, Hash, nil] The content to check
+  # @return [Boolean] true if content is empty, false otherwise
+  def content_empty?(content)
+    case content
+    when String
+      content.strip.empty?
+    when Hash
+      content.empty?
+    else
+      content.nil?
+    end
+  end
+
+  # 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 extract_messages(chat, current_agent)
+    return [] unless chat.respond_to?(:messages)
+
+    chat.messages.filter_map do |msg|
+      case msg.role
+      when :user, :assistant
+        extract_user_or_assistant_message(msg, current_agent)
+      when :tool
+        extract_tool_message(msg)
+      end
+    end
+  end
+
+  def extract_user_or_assistant_message(msg, current_agent)
+    return nil unless msg.content && !content_empty?(msg.content)
+
+    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
+  private_class_method :extract_user_or_assistant_message
+
+  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
+  private_class_method :extract_tool_message
+end

data/lib/agents/helpers.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Agents
+  module Helpers
+  end
+end
+
+require_relative "helpers/headers"
+require_relative "helpers/message_extractor"