ai-agents 0.1.0

data/examples/isp-support/README.md

@@ -0,0 +1,121 @@
+# ISP Customer Support Demo
+
+This example demonstrates a multi-agent customer support system for an Internet Service Provider (ISP). It showcases how specialized agents can work together to handle various customer requests through intelligent routing and handoffs.
+
+## Architecture
+
+The system uses a **hub-and-spoke pattern** with a triage agent that routes customers to appropriate specialists:
+
+### Agents
+
+1. **Triage Agent** - Entry point that greets customers and routes them to specialists
+2. **Sales Agent** - Handles new customer acquisition, upgrades, plan changes, and billing questions
+3. **Support Agent** - Provides technical support, troubleshooting, and account information lookups
+
+### Tools
+
+Each agent has access to specialized tools:
+
+- **CRM Lookup** - Query customer account information by ID (Support Agent)
+- **Create Lead** - Generate sales leads with customer information (Sales Agent)
+- **Create Checkout** - Generate secure payment links for purchases (Sales Agent)
+- **Search Docs** - Find troubleshooting steps in the knowledge base (Support Agent)
+- **Escalate to Human** - Transfer complex issues to human agents (Support Agent)
+
+## Workflow Examples
+
+### Account Information + Technical Issue
+```
+User: "My account shows active but internet isn't working"
+Triage Agent → Support Agent
+Support Agent: 
+  1. Asks for account ID and looks up account info
+  2. Provides technical troubleshooting steps
+  3. Handles complete conversation without handoffs
+```
+
+### Sales Inquiry
+```
+User: "I want to upgrade my plan"
+Triage Agent → Sales Agent
+Sales Agent: Creates lead and checkout link
+```
+
+### Technical Support Only
+```
+User: "My internet is slow"
+Triage Agent → Support Agent  
+Support Agent: Provides troubleshooting steps from docs
+```
+
+## Key Features
+
+- **Intelligent Routing**: Triage agent analyzes customer requests and routes to appropriate specialists
+- **Unified Support**: Support agent handles both technical issues and account lookups in one conversation
+- **Task-Focused Design**: Each agent has clear, focused responsibilities to avoid handoff loops
+- **Tool Integration**: Agents have access to all tools needed for their responsibilities
+- **Conversation Continuity**: Full conversation history is maintained across agent handoffs
+- **Flexible Architecture**: Easy to add new agents or modify routing logic
+
+## Design Principles
+
+This example demonstrates **task-focused agent design** to avoid handoff loops:
+
+- **Support Agent** can handle both account lookups AND technical support
+- **Sales Agent** focuses on sales, upgrades, and billing
+- **Clear boundaries** prevent agents from bouncing requests back and forth
+- **Comprehensive tooling** ensures agents can complete customer requests
+
+## Data
+
+The example includes sample data for:
+- Customer accounts with service details  
+- Knowledge base articles for troubleshooting
+- Service plans and pricing information
+
+## Usage
+
+Run the interactive demo:
+
+```bash
+ruby examples/isp-support/interactive.rb
+```
+
+Try different types of requests:
+- "I need info on my account" (account ID: CUST001, CUST002, or CUST003)
+- "My account is active but internet isn't working" 
+- "I want to upgrade my plan"
+- "How much does fiber cost?"
+
+The system will demonstrate intelligent routing and show how agents handle complex requests without unnecessary handoffs.
+
+## File Structure
+
+```
+examples/isp-support/
+├── README.md                    # This documentation
+├── interactive.rb               # Interactive CLI demo
+├── agents_factory.rb            # Agent creation and configuration
+├── tools/
+│   ├── crm_lookup_tool.rb      # Customer data retrieval
+│   ├── create_lead_tool.rb     # Sales lead generation
+│   ├── create_checkout_tool.rb # Payment link generation
+│   ├── search_docs_tool.rb     # Knowledge base search
+│   └── escalate_to_human_tool.rb # Human handoff
+└── data/
+    ├── customers.json          # Dummy customer database
+    ├── plans.json             # Available service plans
+    └── docs.json              # Troubleshooting knowledge base
+```
+
+## Learning Objectives
+
+This example teaches you how to:
+
+1. **Design Multi-Agent Systems**: Structure agents with clear responsibilities and communication patterns
+2. **Avoid Handoff Loops**: Create task-focused agents that can handle complete customer requests
+3. **Implement Context Sharing**: Pass information between agents while maintaining thread safety
+4. **Create Domain-Specific Tools**: Build tools that integrate with external systems and business logic
+5. **Handle Complex Workflows**: Route requests efficiently without unnecessary agent bouncing
+
+This ISP support system demonstrates effective multi-agent architecture using the Ruby Agents SDK.

data/examples/isp-support/agents_factory.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require_relative "../../lib/agents"
+require_relative "tools/crm_lookup_tool"
+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"
+
+module ISPSupport
+  # Factory for creating all ISP support agents with proper handoff relationships.
+  # This solves the circular dependency problem where agents need to reference each other.
+  class AgentsFactory
+    def self.create_agents
+      new.create_agents
+    end
+
+    def create_agents
+      # Step 1: Create all agents
+      triage = create_triage_agent
+      sales = create_sales_agent
+      support = create_support_agent
+
+      # Step 2: Wire up handoff relationships using register_handoffs
+      # Triage can handoff to specialists
+      triage.register_handoffs(sales, support)
+
+      # Specialists can hand back to triage if needed
+      sales.register_handoffs(triage)
+      support.register_handoffs(triage)
+
+      # Return the configured agents
+      {
+        triage: triage,
+        sales: sales,
+        support: support
+      }
+    end
+
+    private
+
+    def create_triage_agent
+      Agents::Agent.new(
+        name: "Triage Agent",
+        instructions: triage_instructions,
+        model: "gpt-4.1-mini",
+        tools: []
+      )
+    end
+
+
+    def create_sales_agent
+      Agents::Agent.new(
+        name: "Sales Agent",
+        instructions: sales_instructions,
+        model: "gpt-4.1-mini",
+        tools: [ISPSupport::CreateLeadTool.new, ISPSupport::CreateCheckoutTool.new]
+      )
+    end
+
+    def create_support_agent
+      Agents::Agent.new(
+        name: "Support Agent",
+        instructions: support_instructions,
+        model: "gpt-4.1-mini",
+        tools: [
+          ISPSupport::CrmLookupTool.new,
+          ISPSupport::SearchDocsTool.new, 
+          ISPSupport::EscalateToHumanTool.new
+        ]
+      )
+    end
+
+    def triage_instructions
+      <<~INSTRUCTIONS
+        You are the Triage Agent for an ISP customer support system. Your role is to greet customers#{" "}
+        and route them to the appropriate specialist agent based on their needs.
+
+        **Available specialist agents:**
+        - **Sales Agent**: New service, upgrades, plan changes, purchasing, billing questions
+        - **Support Agent**: Technical issues, troubleshooting, outages, account lookups, service problems
+
+        **Routing guidelines:**
+        - Want to buy/upgrade/change plans or billing questions → Sales Agent
+        - Technical problems, outages, account info, or service issues → Support Agent
+        - If unclear, ask one clarifying question before routing
+
+        Keep responses brief and professional. Use handoff tools to transfer to specialists.
+      INSTRUCTIONS
+    end
+
+
+    def sales_instructions
+      <<~INSTRUCTIONS
+        You are the Sales Agent for an ISP. You handle new customer acquisition, service upgrades,
+        and plan changes.
+
+        **Your tools:**
+        - `create_lead`: Create sales leads with customer information
+        - `create_checkout`: Generate secure checkout links for purchases
+        - Handoff tools: Route back to triage when needed
+
+        **When to hand off:**
+        - Need account verification or billing info → Triage Agent for re-routing
+        - Technical questions → Triage Agent for re-routing
+        - Non-sales requests → Triage Agent
+
+        **Instructions:**
+        - Be enthusiastic but not pushy
+        - Gather required info: name, email, desired plan for leads
+        - For existing customers wanting upgrades, ask them to verify account first
+        - Create checkout links for confirmed purchases
+        - Always explain next steps after creating leads or checkout links
+      INSTRUCTIONS
+    end
+
+    def support_instructions
+      <<~INSTRUCTIONS
+        You are the Support Agent for an ISP. You handle technical support, troubleshooting,
+        and account information for customers.
+
+        **Your tools:**
+        - `crm_lookup`: Look up customer account details by account ID
+        - `search_docs`: Find troubleshooting steps in knowledge base
+        - `escalate_to_human`: Transfer complex issues to human agents
+        - Handoff tools: Route back to triage when needed
+
+        **When to hand off:**
+        - Customer wants to buy/upgrade plans → Triage Agent to route to Sales
+        - Non-support requests (new purchases) → Triage Agent
+
+        **Instructions:**
+        - For account questions: Always ask for account ID and use crm_lookup
+        - For technical issues: Start with basic troubleshooting from docs search
+        - You can handle both account lookups AND technical support in the same conversation
+        - Be patient and provide step-by-step guidance
+        - If customer gets frustrated or issue persists, escalate to human
+        - Present account information clearly and protect sensitive data
+      INSTRUCTIONS
+    end
+  end
+end

data/examples/isp-support/data/customers.json

@@ -0,0 +1,133 @@
+{
+  "CUST001": {
+    "id": "CUST001",
+    "name": "John Smith",
+    "email": "john.smith@email.com",
+    "phone": "+1-555-0123",
+    "address": "123 Main St, Anytown, ST 12345",
+    "account_status": "active",
+    "plan": {
+      "name": "Premium Fiber",
+      "speed_down": "1000 Mbps",
+      "speed_up": "500 Mbps",
+      "price": 79.99,
+      "data_limit": "unlimited"
+    },
+    "billing": {
+      "next_bill_date": "2025-07-15",
+      "last_payment": "2025-06-15",
+      "payment_method": "Auto-pay (Credit Card)",
+      "balance": 0.0
+    },
+    "service_history": [
+      {
+        "date": "2025-01-15",
+        "action": "Upgraded to Premium Fiber",
+        "agent": "Sales"
+      },
+      {
+        "date": "2025-03-22",
+        "action": "Support ticket: Intermittent connection",
+        "agent": "Support",
+        "status": "resolved"
+      }
+    ]
+  },
+  "CUST002": {
+    "id": "CUST002",
+    "name": "Sarah Johnson",
+    "email": "sarah.j@email.com",
+    "phone": "+1-555-0456",
+    "address": "456 Oak Ave, Springfield, ST 67890",
+    "account_status": "active",
+    "plan": {
+      "name": "Basic Cable",
+      "speed_down": "100 Mbps",
+      "speed_up": "10 Mbps",
+      "price": 39.99,
+      "data_limit": "1TB"
+    },
+    "billing": {
+      "next_bill_date": "2025-07-20",
+      "last_payment": "2025-06-20",
+      "payment_method": "Monthly Invoice",
+      "balance": 39.99
+    },
+    "service_history": [
+      {
+        "date": "2024-08-10",
+        "action": "New customer signup",
+        "agent": "Sales"
+      }
+    ]
+  },
+  "CUST003": {
+    "id": "CUST003",
+    "name": "Mike Rodriguez",
+    "email": "m.rodriguez@company.com",
+    "phone": "+1-555-0789",
+    "address": "789 Business Blvd, Metro City, ST 13579",
+    "account_status": "active",
+    "plan": {
+      "name": "Business Pro",
+      "speed_down": "500 Mbps",
+      "speed_up": "500 Mbps",
+      "price": 129.99,
+      "data_limit": "unlimited",
+      "sla": "99.9% uptime guarantee"
+    },
+    "billing": {
+      "next_bill_date": "2025-07-01",
+      "last_payment": "2025-06-01",
+      "payment_method": "Corporate Account",
+      "balance": 0.0
+    },
+    "service_history": [
+      {
+        "date": "2024-12-01",
+        "action": "Business account setup",
+        "agent": "Sales"
+      },
+      {
+        "date": "2025-05-15",
+        "action": "Static IP configuration",
+        "agent": "Support",
+        "status": "completed"
+      }
+    ]
+  },
+  "CUST004": {
+    "id": "CUST004",
+    "name": "Lisa Chen",
+    "email": "lisa.chen@email.com",
+    "phone": "+1-555-0321",
+    "address": "321 Pine St, Riverside, ST 24680",
+    "account_status": "suspended",
+    "plan": {
+      "name": "Standard Internet",
+      "speed_down": "200 Mbps",
+      "speed_up": "20 Mbps",
+      "price": 59.99,
+      "data_limit": "unlimited"
+    },
+    "billing": {
+      "next_bill_date": "2025-07-10",
+      "last_payment": "2025-05-10",
+      "payment_method": "Credit Card",
+      "balance": 119.98,
+      "past_due": true
+    },
+    "service_history": [
+      {
+        "date": "2025-06-10",
+        "action": "Service suspended - payment overdue",
+        "agent": "Billing"
+      },
+      {
+        "date": "2025-04-18",
+        "action": "Payment failed notification sent",
+        "agent": "Billing"
+      }
+    ]
+  }
+}

data/examples/isp-support/data/docs.json

@@ -0,0 +1,133 @@
+{
+  "troubleshooting": [
+    {
+      "id": "internet-slow",
+      "title": "Internet Connection is Slow",
+      "category": "connectivity",
+      "keywords": ["slow", "speed", "performance", "bandwidth"],
+      "steps": [
+        "Check if multiple devices are using the internet simultaneously",
+        "Run a speed test at speedtest.net to measure current speeds",
+        "Restart your modem by unplugging for 30 seconds, then plug back in",
+        "Restart your router by unplugging for 30 seconds, then plug back in",
+        "Check for background downloads or streaming on connected devices",
+        "Move closer to your router if using WiFi",
+        "Try connecting directly to modem with ethernet cable",
+        "If speeds are still below plan specifications, contact support"
+      ],
+      "expected_resolution_time": "15 minutes"
+    },
+    {
+      "id": "no-internet",
+      "title": "No Internet Connection",
+      "category": "connectivity",
+      "keywords": ["no internet", "down", "offline", "disconnected", "outage"],
+      "steps": [
+        "Check if modem power light is solid green (not blinking)",
+        "Check if router power light is solid (color varies by model)",
+        "Look for service outage notifications at status.isp.com",
+        "Unplug modem power cord for 30 seconds, then plug back in",
+        "Wait 2-3 minutes for modem to fully restart",
+        "Unplug router power cord for 30 seconds, then plug back in",
+        "Wait 2-3 minutes for router to fully restart",
+        "Check ethernet cable connections are secure",
+        "Try connecting device directly to modem with ethernet",
+        "If still no connection, check for local outages or contact support"
+      ],
+      "expected_resolution_time": "10 minutes"
+    },
+    {
+      "id": "wifi-not-working",
+      "title": "WiFi Not Working",
+      "category": "wifi",
+      "keywords": ["wifi", "wireless", "password", "network", "connection"],
+      "steps": [
+        "Check if WiFi is enabled on your device",
+        "Look for your network name in available networks list",
+        "Verify you're using the correct WiFi password (check router label)",
+        "Move closer to the router to ensure strong signal",
+        "Restart your device's WiFi by turning off and on",
+        "Forget and reconnect to the WiFi network",
+        "Restart your router by unplugging for 30 seconds",
+        "Check if ethernet connection works (isolates WiFi vs internet issue)",
+        "Try connecting a different device to verify WiFi functionality"
+      ],
+      "expected_resolution_time": "10 minutes"
+    },
+    {
+      "id": "intermittent-connection",
+      "title": "Intermittent Connection Issues",
+      "category": "connectivity",
+      "keywords": [
+        "intermittent",
+        "drops",
+        "disconnects",
+        "unstable",
+        "cutting out"
+      ],
+      "steps": [
+        "Note the frequency and timing of disconnections",
+        "Check all cable connections for loose fittings",
+        "Look for damaged coaxial or ethernet cables",
+        "Check if the issue affects all devices or just one",
+        "Monitor modem lights during disconnections",
+        "Check for interference from other electronics",
+        "Update network drivers on affected devices",
+        "Power cycle both modem and router",
+        "Document exact symptoms and contact support if persists"
+      ],
+      "expected_resolution_time": "20 minutes"
+    },
+    {
+      "id": "email-setup",
+      "title": "Email Setup and Configuration",
+      "category": "email",
+      "keywords": ["email", "setup", "configuration", "smtp", "imap", "pop"],
+      "steps": [
+        "Use these settings for email configuration:",
+        "Incoming Mail Server (IMAP): mail.isp.com, Port 993, SSL enabled",
+        "Outgoing Mail Server (SMTP): smtp.isp.com, Port 587, TLS enabled",
+        "Username: your full email address",
+        "Password: your email password",
+        "For mobile devices, enable 'Use SSL' for both incoming and outgoing",
+        "For Outlook, choose 'More settings' and verify port numbers",
+        "Test sending and receiving after setup"
+      ],
+      "expected_resolution_time": "15 minutes"
+    },
+    {
+      "id": "tv-no-signal",
+      "title": "TV Shows No Signal",
+      "category": "tv",
+      "keywords": ["tv", "signal", "cable", "channels", "black screen"],
+      "steps": [
+        "Check that TV is on correct input (Cable/HDMI)",
+        "Ensure cable box is powered on",
+        "Check all coaxial cable connections are tight",
+        "Unplug cable box for 30 seconds, then plug back in",
+        "Wait 3-5 minutes for cable box to fully restart",
+        "Press 'Guide' button to verify signal reception",
+        "Try changing channels to test multiple frequencies",
+        "Check for service outages in your area",
+        "Verify account is current and not suspended"
+      ],
+      "expected_resolution_time": "10 minutes"
+    }
+  ],
+  "billing": [
+    {
+      "id": "payment-methods",
+      "title": "Available Payment Methods",
+      "category": "billing",
+      "keywords": ["payment", "billing", "autopay", "credit card"],
+      "content": "We accept: Credit/Debit Cards (Visa, MasterCard, American Express), Bank Transfer/ACH, Online Banking, Phone payments, Mail-in checks. AutoPay available with 5% discount."
+    },
+    {
+      "id": "billing-cycle",
+      "title": "Understanding Your Billing Cycle",
+      "category": "billing",
+      "keywords": ["billing cycle", "bill date", "due date"],
+      "content": "Bills are generated monthly on your billing date. Payment is due 15 days after bill date. Late fees apply after 30 days. Service may be suspended after 45 days past due."
+    }
+  ]
+}

data/examples/isp-support/data/plans.json

@@ -0,0 +1,86 @@
+{
+  "residential": [
+    {
+      "id": "basic-cable",
+      "name": "Basic Cable",
+      "speed_down": "100 Mbps",
+      "speed_up": "10 Mbps",
+      "price": 39.99,
+      "data_limit": "1TB",
+      "features": ["Cable TV included", "Basic support"],
+      "available": true
+    },
+    {
+      "id": "standard-internet",
+      "name": "Standard Internet",
+      "speed_down": "200 Mbps",
+      "speed_up": "20 Mbps",
+      "price": 59.99,
+      "data_limit": "unlimited",
+      "features": ["No data caps", "24/7 support"],
+      "available": true
+    },
+    {
+      "id": "premium-fiber",
+      "name": "Premium Fiber",
+      "speed_down": "1000 Mbps",
+      "speed_up": "500 Mbps",
+      "price": 79.99,
+      "data_limit": "unlimited",
+      "features": ["Fiber optic", "Priority support", "Static IP option"],
+      "available": true
+    },
+    {
+      "id": "ultra-fiber",
+      "name": "Ultra Fiber",
+      "speed_down": "2000 Mbps",
+      "speed_up": "1000 Mbps",
+      "price": 99.99,
+      "data_limit": "unlimited",
+      "features": ["Ultra-fast fiber", "Premium support", "Free installation"],
+      "available": true
+    }
+  ],
+  "business": [
+    {
+      "id": "business-starter",
+      "name": "Business Starter",
+      "speed_down": "200 Mbps",
+      "speed_up": "50 Mbps",
+      "price": 89.99,
+      "data_limit": "unlimited",
+      "features": ["Business support", "Static IP", "99.5% SLA"],
+      "available": true
+    },
+    {
+      "id": "business-pro",
+      "name": "Business Pro",
+      "speed_down": "500 Mbps",
+      "speed_up": "500 Mbps",
+      "price": 129.99,
+      "data_limit": "unlimited",
+      "features": [
+        "Symmetric speeds",
+        "Priority support",
+        "99.9% SLA",
+        "Dedicated account manager"
+      ],
+      "available": true
+    },
+    {
+      "id": "enterprise",
+      "name": "Enterprise",
+      "speed_down": "1000 Mbps",
+      "speed_up": "1000 Mbps",
+      "price": 199.99,
+      "data_limit": "unlimited",
+      "features": [
+        "Enterprise-grade",
+        "24/7 premium support",
+        "99.99% SLA",
+        "Custom solutions"
+      ],
+      "available": true
+    }
+  ]
+}