ai-agents 0.1.0

data/lib/agents/runner.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+module Agents
+  # The execution engine that orchestrates conversations between users and agents.
+  # Runner manages the conversation flow, handles tool execution through RubyLLM,
+  # coordinates handoffs between agents, and ensures thread-safe operation.
+  #
+  # The Runner follows a turn-based execution model where each turn consists of:
+  # 1. Sending a message to the LLM with current context
+  # 2. Receiving a response that may include tool calls
+  # 3. Executing tools and getting results (handled by RubyLLM)
+  # 4. Checking for agent handoffs
+  # 5. Continuing until no more tools are called
+  #
+  # ## Thread Safety
+  # The Runner ensures thread safety by:
+  # - Creating new context wrappers for each execution
+  # - Using tool wrappers that pass context through parameters
+  # - Never storing execution state in shared variables
+  #
+  # ## Integration with RubyLLM
+  # We leverage RubyLLM for LLM communication and tool execution while
+  # maintaining our own context management and handoff logic.
+  #
+  # @example Simple conversation
+  #   agent = Agents::Agent.new(
+  #     name: "Assistant",
+  #     instructions: "You are a helpful assistant",
+  #     tools: [weather_tool]
+  #   )
+  #
+  #   result = Agents::Runner.run(agent, "What's the weather?")
+  #   puts result.output
+  #   # => "Let me check the weather for you..."
+  #
+  # @example Conversation with context
+  #   result = Agents::Runner.run(
+  #     support_agent,
+  #     "I need help with my order",
+  #     context: { user_id: 123, order_id: 456 }
+  #   )
+  #
+  # @example Multi-agent handoff
+  #   triage = Agents::Agent.new(
+  #     name: "Triage",
+  #     instructions: "Route users to the right specialist",
+  #     handoff_agents: [billing_agent, tech_agent]
+  #   )
+  #
+  #   result = Agents::Runner.run(triage, "I can't pay my bill")
+  #   # Triage agent will handoff to billing_agent
+  class Runner
+    DEFAULT_MAX_TURNS = 10
+
+    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)
+    end
+
+    # Execute an agent with the given input and context
+    #
+    # @param starting_agent [Agents::Agent] The initial agent to run
+    # @param input [String] The user's input message
+    # @param context [Hash] Shared context data accessible to all tools
+    # @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
+
+      # Create context wrapper with deep copy for thread safety
+      context_copy = deep_copy_context(context)
+      context_wrapper = RunContext.new(context_copy)
+      current_turn = 0
+
+      # Create chat and restore conversation history
+      chat = create_chat(current_agent, context_wrapper)
+      restore_conversation_history(chat, context_wrapper)
+
+      loop do
+        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
+
+        # Update usage
+        context_wrapper.usage.add(response.usage) if response.respond_to?(:usage) && response.usage
+
+        # 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}"
+
+          # Save current conversation state before switching
+          save_conversation_state(chat, context_wrapper, current_agent)
+
+          # Switch to new agent
+          current_agent = next_agent
+          context_wrapper.context[:current_agent] = next_agent
+          context_wrapper.context.delete(:pending_handoff)
+
+          # Create new chat for new agent with restored history
+          chat = create_chat(current_agent, context_wrapper)
+          restore_conversation_history(chat, context_wrapper)
+          next
+        end
+
+        # If no tools were called, we have our final response
+        next if response.tool_call?
+
+        # Save final state before returning
+        save_conversation_state(chat, context_wrapper, current_agent)
+
+        return RunResult.new(
+          output: response.content,
+          messages: extract_messages(chat),
+          usage: context_wrapper.usage,
+          context: context_wrapper.context
+        )
+      end
+    rescue MaxTurnsExceeded => e
+      # Save state even on error
+      save_conversation_state(chat, context_wrapper, current_agent) if chat
+
+      RunResult.new(
+        output: "Conversation ended: #{e.message}",
+        messages: chat ? extract_messages(chat) : [],
+        usage: context_wrapper.usage,
+        error: e,
+        context: context_wrapper.context
+      )
+    rescue StandardError => e
+      # Save state even on error
+      save_conversation_state(chat, context_wrapper, current_agent) if chat
+
+      RunResult.new(
+        output: nil,
+        messages: chat ? extract_messages(chat) : [],
+        usage: context_wrapper.usage,
+        error: e,
+        context: context_wrapper.context
+      )
+    end
+
+    private
+
+    def deep_copy_context(context)
+      # Handle deep copying for thread safety
+      context.dup.tap do |copied|
+        copied[:conversation_history] = context[:conversation_history]&.map(&:dup) || []
+        # Don't copy agents - they're immutable
+        copied[:current_agent] = context[:current_agent]
+        copied[:turn_count] = context[:turn_count] || 0
+      end
+    end
+
+    def restore_conversation_history(chat, context_wrapper)
+      history = context_wrapper.context[:conversation_history] || []
+
+      history.each do |msg|
+        # Only restore user and assistant messages with content
+        next unless %i[user assistant].include?(msg[:role])
+        next unless msg[:content] && !msg[:content].strip.empty?
+
+        chat.add_message(
+          role: msg[:role].to_sym,
+          content: msg[:content]
+        )
+      rescue StandardError => e
+        # Continue with partial history on error
+        puts "[Agents] Failed to restore message: #{e.message}"
+      end
+    rescue StandardError => e
+      # If history restoration completely fails, continue with empty history
+      puts "[Agents] Failed to restore conversation history: #{e.message}"
+      context_wrapper.context[:conversation_history] = []
+    end
+
+    def save_conversation_state(chat, context_wrapper, current_agent)
+      # Extract messages from chat
+      messages = extract_messages(chat)
+
+      # Update context with latest state
+      context_wrapper.context[:conversation_history] = messages
+      context_wrapper.context[:current_agent] = current_agent
+      context_wrapper.context[:turn_count] = (context_wrapper.context[:turn_count] || 0) + 1
+      context_wrapper.context[:last_updated] = Time.now
+
+      # Clean up temporary handoff state
+      context_wrapper.context.delete(:pending_handoff)
+    rescue StandardError => e
+      puts "[Agents] Failed to save conversation state: #{e.message}"
+    end
+
+    def create_chat(agent, context_wrapper)
+      # 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
+
+      # 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
+    end
+
+    def extract_messages(chat)
+      return [] unless chat.respond_to?(:messages)
+
+      chat.messages.filter_map do |msg|
+        # Only include user and assistant messages with content
+        next unless %i[user assistant].include?(msg.role)
+        next unless msg.content && !msg.content.strip.empty?
+
+        {
+          role: msg.role,
+          content: msg.content
+        }
+      end
+    end
+  end
+end

data/lib/agents/tool.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+# Tool is the base class for all agent tools, providing a thread-safe interface for
+# agents to interact with external systems and perform actions. Tools extend RubyLLM::Tool
+# while adding critical thread-safety guarantees and enhanced error handling.
+#
+# ## Thread-Safe Design Principles
+# Tools extend RubyLLM::Tool but maintain thread safety by:
+# 1. **No execution state in instance variables** - Only configuration
+# 2. **All state passed through parameters** - ToolContext as first param
+# 3. **Immutable tool instances** - Create once, use everywhere
+# 4. **Stateless perform methods** - Pure functions with context input
+#
+# ## Why Thread Safety Matters
+# In a multi-agent system, the same tool instance may be used concurrently by different
+# agents running in separate threads or fibers. Storing execution state in instance
+# variables would cause race conditions and data corruption.
+#
+# @example Defining a thread-safe tool
+#   class WeatherTool < Agents::Tool
+#     name "get_weather"
+#     description "Get current weather for a location"
+#     param :location, type: "string", desc: "City name or coordinates"
+#
+#     def perform(tool_context, location:)
+#       # All state comes from parameters - no instance variables!
+#       api_key = tool_context.context[:weather_api_key]
+#       cache_duration = tool_context.context[:cache_duration] || 300
+#
+#       begin
+#         # Make API call...
+#         "Sunny, 72°F in #{location}"
+#       rescue => e
+#         "Weather service unavailable: #{e.message}"
+#       end
+#     end
+#   end
+#
+# @example Using the functional tool definition
+#   # Define a calculator tool
+#   calculator = Agents::Tool.tool(
+#     "calculate",
+#     description: "Perform mathematical calculations"
+#   ) do |tool_context, expression:|
+#     begin
+#       result = eval(expression)
+#       result.to_s
+#     rescue => e
+#       "Calculation error: #{e.message}"
+#     end
+#   end
+#
+#   # Use the tool in an agent
+#   agent = Agents::Agent.new(
+#     name: "Math Assistant",
+#     instructions: "You are a helpful math assistant",
+#     tools: [calculator]
+#   )
+#
+#   # During execution, the runner would call it like this:
+#   run_context = Agents::RunContext.new({ user_id: 123 })
+#   tool_context = Agents::ToolContext.new(run_context: run_context)
+#
+#   result = calculator.execute(tool_context, expression: "2 + 2 * 3")
+#   # => "8"
+module Agents
+  class Tool < RubyLLM::Tool
+    class << self
+      def param(name, type = String, desc = nil, required: true, **options)
+        # Convert Ruby types to JSON schema types
+        json_type = case type
+                    when String, "string" then "string"
+                    when Integer, "integer" then "integer"
+                    when Float, "number" then "number"
+                    when TrueClass, FalseClass, "boolean" then "boolean"
+                    when Array, "array" then "array"
+                    when Hash, "object" then "object"
+                    else "string"
+                    end
+
+        # Call parent param method
+        super(name, type: json_type, desc: desc, required: required, **options)
+      end
+    end
+    # Execute the tool with context injection.
+    # This method is called by the runner and handles the thread-safe
+    # execution pattern by passing all state through parameters.
+    #
+    # @param tool_context [Agents::ToolContext] The execution context containing shared state and usage tracking
+    # @param params [Hash] Tool-specific parameters as defined by the tool's param declarations
+    # @return [String] The tool's result
+    def execute(tool_context, **params)
+      perform(tool_context, **params)
+    end
+
+    # Perform the tool's action. Subclasses must implement this method.
+    # This is where the actual tool logic lives. The method receives all
+    # execution state through parameters, ensuring thread safety.
+    #
+    # @param tool_context [Agents::ToolContext] The execution context
+    # @param params [Hash] Tool-specific parameters
+    # @return [String] The tool's result
+    # @raise [NotImplementedError] If not implemented by subclass
+    # @example Implementing perform in a subclass
+    #   class SearchTool < Agents::Tool
+    #     def perform(tool_context, query:, max_results: 10)
+    #       api_key = tool_context.context[:search_api_key]
+    #       results = SearchAPI.search(query, api_key: api_key, limit: max_results)
+    #       results.map(&:title).join("\n")
+    #     end
+    #   end
+    def perform(tool_context, **params)
+      raise NotImplementedError, "Tools must implement #perform(tool_context, **params)"
+    end
+
+    # Create a tool instance using a functional style definition.
+    # This is an alternative to creating a full class for simple tools.
+    # The block becomes the tool's perform method.
+    #
+    # @param name [String] The tool's name (used in function calling)
+    # @param description [String] Brief description of what the tool does
+    # @yield [tool_context, **params] The block that implements the tool's logic
+    # @return [Agents::Tool] A new tool instance
+    # @example Creating a simple tool functionally
+    #   math_tool = Agents::Tool.tool(
+    #     "add_numbers",
+    #     description: "Add two numbers together"
+    #   ) do |tool_context, a:, b:|
+    #     (a + b).to_s
+    #   end
+    #
+    # @example Tool accessing context with error handling
+    #   greeting_tool = Agents::Tool.tool("greet", description: "Greet a user") do |tool_context, name:|
+    #     language = tool_context.context[:language] || "en"
+    #     case language
+    #     when "es" then "¡Hola, #{name}!"
+    #     when "fr" then "Bonjour, #{name}!"
+    #     else "Hello, #{name}!"
+    #     end
+    #   rescue => e
+    #     "Sorry, I couldn't greet you: #{e.message}"
+    #   end
+    def self.tool(name, description: "", &block)
+      # Create anonymous class that extends Tool
+      Class.new(Tool) do
+        self.name = name
+        self.description = description
+
+        define_method :perform, &block
+      end.new
+    end
+  end
+end

data/lib/agents/tool_context.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+# ToolContext provides tools with controlled access to execution state during their invocation.
+# It wraps the RunContext and adds tool-specific metadata like retry count. This is a critical
+# component of the thread-safe design - tools receive all their execution state through this
+# context object rather than storing it in instance variables.
+#
+# @example Tool receiving context during execution
+#   class CalculatorTool < Agents::Tool
+#     def perform(tool_context, expression:)
+#       # Access shared context data
+#       precision = tool_context.context[:precision] || 2
+#
+#       # Track retry attempts
+#       if tool_context.retry_count > 0
+#         logger.warn "Retrying calculation (attempt #{tool_context.retry_count + 1})"
+#       end
+#
+#       result = eval(expression)
+#       result.round(precision)
+#     end
+#   end
+#
+# @example Runner creating ToolContext for execution
+#   run_context = Agents::RunContext.new({ user: current_user })
+#   tool_context = Agents::ToolContext.new(
+#     run_context: run_context,
+#     retry_count: 0
+#   )
+#
+#   result = tool.execute(tool_context, expression: "2 + 2")
+#
+# ## How Thread Safety is Ensured
+#
+# ToolContext enables thread-safe tool execution by enforcing a critical principle:
+# all execution state must flow through method parameters, never through instance variables.
+#
+# Here's how it works:
+#
+# 1. **Tool instances are stateless** - They only store configuration (name, description),
+#    never execution data like current user, session, or request details.
+#
+# 2. **State flows through parameters** - When a tool is executed, it receives a ToolContext
+#    parameter that contains all the execution-specific state it needs.
+#
+# 3. **Each execution is isolated** - Multiple threads can call the same tool instance
+#    simultaneously, but each call gets its own ToolContext with its own state.
+#
+# This is similar to how web frameworks handle concurrent requests - the controller
+# instance might be shared, but each request gets its own params and session objects.
+# The ToolContext serves the same purpose, providing isolation without requiring
+# new object creation for each execution.
+module Agents
+  class ToolContext
+    attr_reader :run_context, :retry_count
+
+    # Initialize a new ToolContext wrapping a RunContext
+    #
+    # @param run_context [Agents::RunContext] The run context containing shared execution state
+    # @param retry_count [Integer] Number of times this tool execution has been retried (default: 0)
+    def initialize(run_context:, retry_count: 0)
+      @run_context = run_context
+      @retry_count = retry_count
+    end
+
+    # Convenient access to the shared context hash from the RunContext.
+    # This delegation makes it easier for tools to access context data without
+    # having to navigate through run_context.context.
+    #
+    # @return [Hash] The shared context hash from the RunContext
+    # @example Accessing context data in a tool
+    #   def perform(tool_context, **params)
+    #     user_id = tool_context.context[:user_id]
+    #     session = tool_context.context[:session]
+    #     # ...
+    #   end
+    def context
+      @run_context.context
+    end
+
+    # Convenient access to the usage tracking object from the RunContext.
+    # Tools can use this to add their own usage metrics if they make
+    # additional LLM calls.
+    #
+    # @return [Agents::RunContext::Usage] The usage tracking object
+    # @example Tool tracking additional LLM usage
+    #   def perform(tool_context, **params)
+    #     # Tool makes its own LLM call
+    #     response = llm.complete("Analyze: #{params[:data]}")
+    #     tool_context.usage.add(response.usage)
+    #
+    #     response.content
+    #   end
+    def usage
+      @run_context.usage
+    end
+  end
+end

data/lib/agents/tool_wrapper.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Agents
+  # A thread-safe wrapper that bridges RubyLLM's tool execution with our context injection pattern.
+  # This wrapper solves a critical problem: RubyLLM calls tools with just the LLM-provided
+  # parameters, but our tools need access to the execution context for shared state.
+  #
+  # ## The Thread Safety Problem
+  # Without this wrapper, we'd need to store context in tool instance variables, which would
+  # cause race conditions when the same tool is used by multiple concurrent requests:
+  #
+  #   # UNSAFE - Don't do this!
+  #   class BadTool < Agents::Tool
+  #     def set_context(ctx)
+  #       @context = ctx  # Race condition!
+  #     end
+  #   end
+  #
+  # ## The Solution
+  # Each Runner creates new wrapper instances for each execution, capturing the context
+  # in the wrapper's closure. When RubyLLM calls execute(), the wrapper injects the
+  # context before calling the actual tool:
+  #
+  #   # Runner creates wrapper
+  #   wrapped = ToolWrapper.new(my_tool, context_wrapper)
+  #
+  #   # RubyLLM calls wrapper
+  #   wrapped.execute(city: "NYC")  # No context parameter
+  #
+  #   # Wrapper injects context
+  #   tool_context = ToolContext.new(run_context: context_wrapper)
+  #   my_tool.execute(tool_context, city: "NYC")  # Context injected!
+  #
+  # This ensures each execution has its own context without any shared mutable state.
+  class ToolWrapper
+    def initialize(tool, context_wrapper)
+      @tool = tool
+      @context_wrapper = context_wrapper
+
+      # Copy tool metadata for RubyLLM
+      @name = tool.name
+      @description = tool.description
+      @params = tool.class.params if tool.class.respond_to?(:params)
+    end
+
+    # RubyLLM calls this method (follows RubyLLM::Tool pattern)
+    def call(args)
+      tool_context = ToolContext.new(run_context: @context_wrapper)
+      @tool.execute(tool_context, **args.transform_keys(&:to_sym))
+    end
+
+    # Delegate metadata methods to the tool
+    def name
+      @name || @tool.name
+    end
+
+    def description
+      @description || @tool.description
+    end
+
+    # RubyLLM calls this to get parameter definitions
+    def parameters
+      @tool.parameters
+    end
+
+    # Make this work with RubyLLM's tool calling
+    def to_s
+      name
+    end
+  end
+end

data/lib/agents/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Agents
+  VERSION = "0.1.0"
+end

data/lib/agents.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Main entry point for the Ruby AI Agents SDK
+# This file sets up the core Agents module namespace and provides global configuration
+# for the multi-agent system including LLM provider setup, API keys, and system defaults.
+# It serves as the central configuration hub that other components depend on.
+
+require "ruby_llm"
+require_relative "agents/version"
+
+module Agents
+  class Error < StandardError; end
+
+  class << self
+    # Logger for debugging (can be set by users)
+    attr_accessor :logger
+
+    # Configure both Agents and RubyLLM in one block
+    def configure
+      yield(configuration) if block_given?
+      configure_ruby_llm!
+      configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    private
+
+    def configure_ruby_llm!
+      RubyLLM.configure do |config|
+        config.openai_api_key = configuration.openai_api_key if configuration.openai_api_key
+        config.anthropic_api_key = configuration.anthropic_api_key if configuration.anthropic_api_key
+        config.gemini_api_key = configuration.gemini_api_key if configuration.gemini_api_key
+        config.default_model = configuration.default_model
+        config.log_level = configuration.debug == true ? :debug : :info
+        config.request_timeout = configuration.request_timeout if configuration.request_timeout
+      end
+    end
+  end
+
+  class Configuration
+    attr_accessor :openai_api_key, :anthropic_api_key, :gemini_api_key, :request_timeout, :default_model, :debug
+
+    def initialize
+      @default_model = "gpt-4o-mini"
+      @request_timeout = 120
+      @debug = false
+    end
+
+    # Check if at least one provider is configured
+    # @return [Boolean] True if any provider has an API key
+    def configured?
+      @openai_api_key || @anthropic_api_key || @gemini_api_key
+    end
+  end
+end
+
+# Core components
+require_relative "agents/result"
+require_relative "agents/run_context"
+require_relative "agents/tool_context"
+require_relative "agents/tool"
+require_relative "agents/handoff"
+require_relative "agents/agent"
+
+# Execution components
+require_relative "agents/tool_wrapper"
+require_relative "agents/runner"

data/sig/ruby/agents.rbs

@@ -0,0 +1,6 @@
+module Ruby
+  module Agents
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end