ai-agents 0.1.1 → 0.1.3

data/docs/guides/multi-agent-systems.md

@@ -0,0 +1,261 @@
+---
+layout: default
+title: Building Multi-Agent Systems
+parent: Guides
+nav_order: 1
+---
+
+# Building Multi-Agent Systems
+
+Multi-agent systems allow you to decompose complex problems into specialized agents that collaborate to provide comprehensive solutions. This guide covers patterns and best practices for designing effective multi-agent workflows.
+
+## Core Patterns
+
+### Hub-and-Spoke Architecture
+
+The most common and stable pattern is hub-and-spoke, where a central triage agent routes conversations to specialized agents:
+
+```ruby
+# Specialized agents
+billing_agent = Agents::Agent.new(
+  name: "Billing",
+  instructions: "Handle billing inquiries, payment processing, and account issues."
+)
+
+support_agent = Agents::Agent.new(
+  name: "Support", 
+  instructions: "Provide technical troubleshooting and product support."
+)
+
+# Central hub agent
+triage_agent = Agents::Agent.new(
+  name: "Triage",
+  instructions: "Route users to the appropriate specialist. Only hand off, don't solve problems yourself."
+)
+
+# Register handoffs (one-way: triage -> specialists)
+triage_agent.register_handoffs(billing_agent, support_agent)
+
+# Create runner with triage as entry point
+runner = Agents::AgentRunner.with_agents(triage_agent, billing_agent, support_agent)
+```
+
+### Dynamic Instructions
+
+Use Proc-based instructions to create context-aware agents:
+
+```ruby
+support_agent = Agents::Agent.new(
+  name: "Support",
+  instructions: ->(context) {
+    customer_tier = context[:customer_tier] || "standard"
+    <<~INSTRUCTIONS
+      You are a technical support specialist for #{customer_tier} tier customers.
+      #{customer_tier == "premium" ? "Provide priority white-glove service." : ""}
+      
+      Available tools: diagnostics, escalation
+    INSTRUCTIONS
+  }
+)
+```
+
+## Agent Design Principles
+
+### Clear Boundaries
+
+Each agent should have a distinct, non-overlapping responsibility:
+
+```ruby
+# GOOD: Clear specialization
+sales_agent = Agents::Agent.new(
+  name: "Sales",
+  instructions: "Handle product inquiries, pricing, and purchase decisions. Transfer technical questions to support."
+)
+
+support_agent = Agents::Agent.new(
+  name: "Support", 
+  instructions: "Handle technical issues and product troubleshooting. Transfer sales questions to sales team."
+)
+```
+
+### Avoiding Handoff Loops
+
+Design instructions to prevent infinite handoffs:
+
+```ruby
+# BAD: Conflicting handoff criteria
+agent_a = Agents::Agent.new(
+  instructions: "Handle X. If you need Y info, hand off to Agent B."
+)
+agent_b = Agents::Agent.new(
+  instructions: "Handle Y. If you need X context, hand off to Agent A."
+)
+
+# GOOD: Clear escalation hierarchy
+specialist = Agents::Agent.new(
+  instructions: "Handle specialized requests. Ask users for needed info directly."
+)
+triage = Agents::Agent.new(
+  instructions: "Route users to specialists. Don't solve problems yourself."
+)
+```
+
+## Conversation Flow Management
+
+### Entry Points
+
+The first agent in `AgentRunner.with_agents()` becomes the default entry point:
+
+```ruby
+# Triage agent handles all initial conversations
+runner = Agents::AgentRunner.with_agents(triage_agent, billing_agent, support_agent)
+
+# Start conversation
+result = runner.run("I need help with my account")
+# -> Automatically starts with triage_agent
+```
+
+### Context Preservation
+
+The AgentRunner automatically maintains conversation history across handoffs:
+
+```ruby
+# First interaction
+result1 = runner.run("My name is John and I have a billing question")
+# -> Triage agent hands off to billing agent
+
+# Continue conversation
+result2 = runner.run("What payment methods do you accept?", context: result1.context)
+# -> Billing agent remembers John's name and previous context
+```
+
+### Handoff Detection
+
+The system automatically determines the current agent from conversation history:
+
+```ruby
+# No need to manually specify which agent to use
+result = runner.run("Follow up question", context: previous_result.context)
+# -> AgentRunner automatically selects correct agent based on conversation state
+```
+
+## Advanced Patterns
+
+### Tool-Specific Agents
+
+Create agents specialized for particular tool categories:
+
+```ruby
+data_agent = Agents::Agent.new(
+  name: "DataAnalyst",
+  instructions: "Analyze data and generate reports using available analytics tools.",
+  tools: [DatabaseTool.new, ChartGeneratorTool.new, ReportTool.new]
+)
+
+communication_agent = Agents::Agent.new(
+  name: "Communications",
+  instructions: "Handle notifications and external communications.",
+  tools: [EmailTool.new, SlackTool.new, SMSTool.new]
+)
+```
+
+### Conditional Handoffs
+
+Use dynamic instructions to control handoff behavior:
+
+```ruby
+triage_agent = Agents::Agent.new(
+  name: "Triage",
+  instructions: ->(context) {
+    business_hours = context[:business_hours] || false
+    
+    base_instructions = "Route users to appropriate departments."
+    
+    if business_hours
+      base_instructions + " All departments are available."
+    else
+      base_instructions + " Only hand off urgent technical issues to support. Others should wait for business hours."
+    end
+  }
+)
+```
+
+## Testing Multi-Agent Systems
+
+### Unit Testing Individual Agents
+
+Test each agent in isolation:
+
+```ruby
+RSpec.describe "BillingAgent" do
+  let(:agent) { create_billing_agent }
+  let(:runner) { Agents::AgentRunner.with_agents(agent) }
+  
+  it "handles payment inquiries" do
+    result = runner.run("What payment methods do you accept?")
+    expect(result.output).to include("credit card", "bank transfer")
+  end
+end
+```
+
+### Integration Testing Handoffs
+
+Test complete workflows:
+
+```ruby
+RSpec.describe "Customer Support Workflow" do
+  let(:runner) { create_support_runner } # Creates triage + specialists
+  
+  it "routes billing questions correctly" do
+    result = runner.run("I have a billing question")
+    
+    # Verify handoff occurred
+    expect(result.context.current_agent_name).to eq("Billing")
+    
+    # Test continued conversation
+    followup = runner.run("What are your payment terms?", context: result.context)
+    expect(followup.output).to include("payment terms")
+  end
+end
+```
+
+## Common Pitfalls
+
+### Over-Specialization
+Don't create too many narrow agents - it increases handoff complexity and latency.
+
+### Under-Specified Instructions
+Vague instructions lead to inappropriate handoffs. Be explicit about what each agent should and shouldn't handle.
+
+### Circular Dependencies
+Avoid mutual handoffs between agents. Use hub-and-spoke or clear hierarchical patterns instead.
+
+### Context Leakage
+Don't rely on shared mutable state. Use the context hash for inter-agent communication.
+
+## Performance Considerations
+
+### Handoff Overhead
+Each handoff adds latency. Design agents to minimize unnecessary transfers.
+
+### Context Size
+Large contexts increase token usage. Clean up irrelevant data periodically:
+
+```ruby
+# Remove old conversation history
+cleaned_context = result.context.dup
+cleaned_context[:conversation_history] = cleaned_context[:conversation_history].last(10)
+```
+
+### Concurrent Execution
+AgentRunner is thread-safe, allowing multiple conversations simultaneously:
+
+```ruby
+# Safe to use same runner across threads
+threads = users.map do |user|
+  Thread.new do
+    user_result = runner.run(user.message, context: user.context)
+    # Handle result...
+  end
+end
+```

data/docs/guides/rails-integration.md

@@ -0,0 +1,440 @@
+---
+layout: default
+title: Rails Integration
+parent: Guides
+nav_order: 2
+---
+
+# Rails Integration
+
+This guide covers integrating the AI Agents library with Ruby on Rails applications, including conversation persistence with ActiveRecord and session management.
+
+## Setup
+
+Add the gem to your Rails application:
+
+```ruby
+# Gemfile
+gem 'ai-agents'
+```
+
+Configure your LLM providers in an initializer:
+
+```ruby
+# config/initializers/ai_agents.rb
+Agents.configure do |config|
+  config.openai_api_key = Rails.application.credentials.openai_api_key
+  config.anthropic_api_key = Rails.application.credentials.anthropic_api_key
+  config.default_model = 'gpt-4o-mini'
+  config.debug = Rails.env.development?
+end
+```
+
+## ActiveRecord Integration
+
+### Conversation Persistence
+
+Create a model to store conversation contexts:
+
+```ruby
+# Generate migration
+rails generate model Conversation user:references context:text current_agent:string
+
+# db/migrate/xxx_create_conversations.rb
+class CreateConversations < ActiveRecord::Migration[7.0]
+  def change
+    create_table :conversations do |t|
+      t.references :user, null: false, foreign_key: true
+      t.text :context, null: false
+      t.string :current_agent
+      t.timestamps
+    end
+    
+    add_index :conversations, [:user_id, :created_at]
+  end
+end
+```
+
+Define the Conversation model:
+
+```ruby
+# app/models/conversation.rb
+class Conversation < ApplicationRecord
+  belongs_to :user
+  
+  # Serialize context as JSON
+  serialize :context, JSON
+  
+  validates :context, presence: true
+  
+  def self.for_user(user)
+    where(user: user).order(:created_at)
+  end
+  
+  def self.latest_for_user(user)
+    for_user(user).last
+  end
+  
+  # Convert to agent context hash
+  def to_agent_context
+    context.deep_symbolize_keys
+  end
+  
+  # Create from agent result
+  def self.from_agent_result(user, result)
+    create!(
+      user: user,
+      context: result.context.to_h,
+      current_agent: result.context.current_agent_name
+    )
+  end
+end
+```
+
+### Session Management
+
+Create a service to manage agent conversations:
+
+```ruby
+# app/services/agent_conversation_service.rb
+class AgentConversationService
+  def initialize(user)
+    @user = user
+    @runner = create_agent_runner
+  end
+  
+  def send_message(message)
+    # Get existing conversation context
+    context = load_conversation_context
+    
+    # Run agent with message
+    result = @runner.run(message, context: context)
+    
+    # Persist updated conversation
+    save_conversation(result)
+    
+    result
+  end
+  
+  def reset_conversation
+    Conversation.where(user: @user).destroy_all
+  end
+  
+  private
+  
+  def create_agent_runner
+    # Create your agents here
+    triage_agent = Agents::Agent.new(
+      name: "Triage",
+      instructions: build_triage_instructions,
+      tools: [CustomerLookupTool.new]
+    )
+    
+    billing_agent = Agents::Agent.new(
+      name: "Billing",
+      instructions: "Handle billing and payment inquiries.",
+      tools: [BillingTool.new, PaymentTool.new]
+    )
+    
+    support_agent = Agents::Agent.new(
+      name: "Support",
+      instructions: "Provide technical support and troubleshooting.",
+      tools: [TechnicalTool.new]
+    )
+    
+    triage_agent.register_handoffs(billing_agent, support_agent)
+    
+    Agents::AgentRunner.with_agents(triage_agent, billing_agent, support_agent)
+  end
+  
+  def build_triage_instructions
+    ->(context) {
+      user_info = context[:user_info] || {}
+      
+      <<~INSTRUCTIONS
+        You are a customer service triage agent for #{@user.name}.
+        
+        Customer Details:
+        - Name: #{@user.name}
+        - Email: #{@user.email}
+        - Account Type: #{user_info[:account_type] || 'standard'}
+        
+        Route customers to the appropriate department:
+        - Billing: Payment issues, account billing, refunds
+        - Support: Technical problems, product questions
+        
+        Always be professional and helpful.
+      INSTRUCTIONS
+    }
+  end
+  
+  def load_conversation_context
+    latest_conversation = Conversation.latest_for_user(@user)
+    return initial_context unless latest_conversation
+    
+    latest_conversation.to_agent_context
+  end
+  
+  def initial_context
+    {
+      user_id: @user.id,
+      user_info: {
+        name: @user.name,
+        email: @user.email,
+        account_type: @user.account_type
+      }
+    }
+  end
+  
+  def save_conversation(result)
+    Conversation.from_agent_result(@user, result)
+  end
+end
+```
+
+## Controller Integration
+
+Create a controller for handling agent conversations:
+
+```ruby
+# app/controllers/agent_conversations_controller.rb
+class AgentConversationsController < ApplicationController
+  before_action :authenticate_user!
+  
+  def create
+    service = AgentConversationService.new(current_user)
+    
+    begin
+      result = service.send_message(params[:message])
+      
+      render json: {
+        response: result.output,
+        agent: result.context.current_agent_name,
+        conversation_id: result.context[:conversation_id]
+      }
+    rescue => e
+      Rails.logger.error "Agent conversation error: #{e.message}"
+      render json: { error: "Unable to process your request" }, status: 500
+    end
+  end
+  
+  def reset
+    service = AgentConversationService.new(current_user)
+    service.reset_conversation
+    
+    render json: { message: "Conversation reset successfully" }
+  end
+  
+  def history
+    conversations = Conversation.for_user(current_user)
+                               .includes(:user)
+                               .limit(50)
+    
+    render json: conversations.map do |conv|
+      {
+        id: conv.id,
+        agent: conv.current_agent,
+        timestamp: conv.created_at,
+        context_keys: conv.context.keys
+      }
+    end
+  end
+end
+```
+
+## Custom Rails Tools
+
+Create Rails-specific tools for database operations:
+
+```ruby
+# app/tools/customer_lookup_tool.rb
+class CustomerLookupTool < Agents::Tool
+  name "lookup_customer"
+  description "Look up customer information by email or ID"
+  param :identifier, type: "string", desc: "Email address or customer ID"
+  
+  def perform(tool_context, identifier:)
+    # Access Rails models safely
+    customer = User.find_by(email: identifier) || User.find_by(id: identifier)
+    
+    return "Customer not found" unless customer
+    
+    {
+      name: customer.name,
+      email: customer.email,
+      account_type: customer.account_type,
+      created_at: customer.created_at,
+      last_login: customer.last_sign_in_at
+    }
+  end
+end
+
+# app/tools/billing_tool.rb
+class BillingTool < Agents::Tool
+  name "get_billing_info"
+  description "Retrieve billing information for a customer"
+  param :user_id, type: "integer", desc: "Customer user ID"
+  
+  def perform(tool_context, user_id:)
+    user = User.find(user_id)
+    billing_info = user.billing_profile
+    
+    return "No billing information found" unless billing_info
+    
+    {
+      plan: billing_info.plan_name,
+      status: billing_info.status,
+      next_billing_date: billing_info.next_billing_date,
+      amount: billing_info.monthly_amount
+    }
+  rescue ActiveRecord::RecordNotFound
+    "Customer not found"
+  end
+end
+```
+
+## Background Processing
+
+For longer conversations, use background jobs:
+
+```ruby
+# app/jobs/agent_conversation_job.rb
+class AgentConversationJob < ApplicationJob
+  queue_as :default
+  
+  def perform(user_id, message, conversation_id = nil)
+    user = User.find(user_id)
+    service = AgentConversationService.new(user)
+    
+    result = service.send_message(message)
+    
+    # Broadcast result via ActionCable
+    ActionCable.server.broadcast(
+      "agent_conversation_#{user_id}",
+      {
+        response: result.output,
+        agent: result.context.current_agent_name,
+        conversation_id: conversation_id
+      }
+    )
+  end
+end
+
+# Enqueue job from controller
+def create_async
+  job_id = AgentConversationJob.perform_later(
+    current_user.id,
+    params[:message],
+    params[:conversation_id]
+  )
+  
+  render json: { job_id: job_id }
+end
+```
+
+## Error Handling
+
+Implement comprehensive error handling:
+
+```ruby
+# app/services/agent_conversation_service.rb
+class AgentConversationService
+  class AgentError < StandardError; end
+  class ContextError < StandardError; end
+  
+  def send_message(message)
+    validate_message(message)
+    
+    context = load_conversation_context
+    
+    begin
+      result = @runner.run(message, context: context)
+      save_conversation(result)
+      result
+    rescue RubyLLM::Error => e
+      Rails.logger.error "LLM Error: #{e.message}"
+      raise AgentError, "AI service temporarily unavailable"
+    rescue JSON::ParserError => e
+      Rails.logger.error "Context parsing error: #{e.message}"
+      raise ContextError, "Conversation context corrupted"
+    end
+  end
+  
+  private
+  
+  def validate_message(message)
+    raise ArgumentError, "Message cannot be blank" if message.blank?
+    raise ArgumentError, "Message too long" if message.length > 5000
+  end
+end
+```
+
+## Testing
+
+Test Rails integration with RSpec:
+
+```ruby
+# spec/services/agent_conversation_service_spec.rb
+RSpec.describe AgentConversationService do
+  let(:user) { create(:user) }
+  let(:service) { described_class.new(user) }
+  
+  describe '#send_message' do
+    it 'creates a conversation record' do
+      expect {
+        service.send_message("Hello")
+      }.to change(Conversation, :count).by(1)
+    end
+    
+    it 'persists context correctly' do
+      result = service.send_message("Hello")
+      conversation = Conversation.last
+      
+      expect(conversation.user).to eq(user)
+      expect(conversation.context).to include('user_id' => user.id)
+    end
+  end
+  
+  describe '#reset_conversation' do
+    before { service.send_message("Hello") }
+    
+    it 'destroys all conversations for user' do
+      expect {
+        service.reset_conversation
+      }.to change(Conversation, :count).by(-1)
+    end
+  end
+end
+```
+
+## Deployment Considerations
+
+### Environment Variables
+
+```ruby
+# config/credentials.yml.enc
+openai_api_key: your_openai_key
+anthropic_api_key: your_anthropic_key
+
+# Or use environment variables
+ENV['OPENAI_API_KEY']
+ENV['ANTHROPIC_API_KEY']
+```
+
+### Database Indexing
+
+```ruby
+# Add indexes for better query performance
+add_index :conversations, [:user_id, :current_agent]
+add_index :conversations, :created_at
+```
+
+### Memory Management
+
+```ruby
+# Cleanup old conversations
+# config/schedule.rb (whenever gem)
+every 1.day, at: '2:00 am' do
+  runner "Conversation.where('created_at < ?', 30.days.ago).destroy_all"
+end
+```