ai-agents 0.1.1 → 0.1.3

data/examples/collaborative-copilot/data/knowledge_base.json

@@ -0,0 +1,58 @@
+{
+  "articles": {
+    "ART-001": {
+      "id": "ART-001",
+      "title": "How to Clear Browser Cache",
+      "category": "troubleshooting",
+      "content": "To clear your browser cache:\n\n**Chrome:**\n1. Press Ctrl+Shift+Delete (Cmd+Shift+Delete on Mac)\n2. Select 'All time' from the time range\n3. Check 'Cached images and files'\n4. Click 'Clear data'\n\n**Firefox:**\n1. Press Ctrl+Shift+Delete (Cmd+Shift+Delete on Mac)\n2. Select 'Everything' from time range\n3. Check 'Cache'\n4. Click 'Clear Now'\n\n**Safari:**\n1. Go to Safari menu > Clear History\n2. Select 'All History'\n3. Click 'Clear History'",
+      "tags": ["browser", "cache", "troubleshooting", "login-issues"],
+      "created_at": "2023-08-15T10:00:00Z",
+      "updated_at": "2024-01-10T14:30:00Z"
+    },
+    "ART-002": {
+      "id": "ART-002", 
+      "title": "Password Reset Instructions",
+      "category": "account",
+      "content": "If you're unable to log in, try resetting your password:\n\n1. Go to the login page\n2. Click 'Forgot Password?'\n3. Enter your email address\n4. Check your email for reset instructions\n5. Click the reset link (valid for 24 hours)\n6. Create a new strong password\n\n**Password Requirements:**\n- At least 8 characters\n- One uppercase letter\n- One lowercase letter  \n- One number\n- One special character\n\nIf you don't receive the reset email, check your spam folder or contact support.",
+      "tags": ["password", "reset", "login", "account"],
+      "created_at": "2023-08-15T10:15:00Z",
+      "updated_at": "2024-01-05T09:20:00Z"
+    },
+    "ART-003": {
+      "id": "ART-003",
+      "title": "API Rate Limits and Error Handling",
+      "category": "development",
+      "content": "Our API has the following rate limits:\n\n**Standard Plan:** 1,000 requests/hour\n**Pro Plan:** 5,000 requests/hour  \n**Enterprise Plan:** 50,000 requests/hour\n\n**Common Error Codes:**\n- 429: Rate limit exceeded\n- 500: Internal server error\n- 503: Service temporarily unavailable\n\n**Best Practices:**\n- Implement exponential backoff for 5xx errors\n- Cache responses when possible\n- Use pagination for large datasets\n- Monitor your usage in the dashboard\n\nIf you're experiencing consistent 500 errors, please contact our engineering team.",
+      "tags": ["api", "rate-limits", "errors", "development"],
+      "created_at": "2023-09-01T11:00:00Z",
+      "updated_at": "2024-01-12T16:45:00Z"
+    },
+    "ART-004": {
+      "id": "ART-004",
+      "title": "Billing and Refund Policy",
+      "category": "billing",
+      "content": "**Billing Cycle:**\nAll plans are billed monthly on the date you signed up.\n\n**Refund Policy:**\n- Full refund within 30 days of signup\n- Partial refunds for downgrades (prorated)\n- No refunds for accounts terminated for policy violations\n\n**Common Billing Issues:**\n- Duplicate charges: Usually resolved within 24 hours\n- Failed payments: Update payment method in settings\n- Upgrade/downgrade: Changes take effect immediately\n\n**Contacting Billing:**\nFor billing questions, include your account email and approximate charge date.",
+      "tags": ["billing", "refunds", "charges", "payment"],
+      "created_at": "2023-08-20T14:00:00Z",
+      "updated_at": "2024-01-08T10:30:00Z"
+    }
+  },
+  "categories": [
+    {
+      "name": "troubleshooting",
+      "description": "Technical issues and problem resolution"
+    },
+    {
+      "name": "account", 
+      "description": "Account management and login issues"
+    },
+    {
+      "name": "development",
+      "description": "API documentation and developer resources"
+    },
+    {
+      "name": "billing",
+      "description": "Billing, payments, and subscription management"
+    }
+  ]
+}

data/examples/collaborative-copilot/data/linear_issues.json

@@ -0,0 +1,83 @@
+{
+  "issues": {
+    "ENG-445": {
+      "id": "ENG-445",
+      "title": "API /users endpoint returning 500 errors intermittently",
+      "status": "in_progress",
+      "priority": "high",
+      "assignee": "alex.dev@company.com",
+      "labels": ["bug", "api", "production"],
+      "created_at": "2024-01-12T11:15:00Z",
+      "updated_at": "2024-01-12T15:30:00Z",
+      "description": "Customer reports 20% failure rate on /users endpoint with 500 errors. Investigation shows database connection pool exhaustion during peak traffic.",
+      "comments": [
+        {
+          "author": "alex.dev@company.com",
+          "content": "Reproduced locally. Issue appears to be connection pool size too small for current load.",
+          "timestamp": "2024-01-12T13:20:00Z"
+        },
+        {
+          "author": "sarah.lead@company.com", 
+          "content": "Increasing pool size from 10 to 25 connections. Testing in staging.",
+          "timestamp": "2024-01-12T15:30:00Z"
+        }
+      ]
+    },
+    "ENG-442": {
+      "id": "ENG-442",
+      "title": "Add dark mode support to web application",
+      "status": "backlog",
+      "priority": "medium", 
+      "assignee": null,
+      "labels": ["feature", "ui", "accessibility"],
+      "created_at": "2024-01-05T10:00:00Z",
+      "updated_at": "2024-01-08T14:15:00Z",
+      "description": "Multiple customers have requested dark mode. This would improve accessibility and user experience, especially for users who work in low-light environments.",
+      "comments": [
+        {
+          "author": "product.manager@company.com",
+          "content": "Added to Q1 roadmap. Design team will create mockups first.",
+          "timestamp": "2024-01-08T14:15:00Z"
+        }
+      ]
+    },
+    "ENG-440": {
+      "id": "ENG-440",
+      "title": "Login page occasionally shows white screen",
+      "status": "resolved",
+      "priority": "medium",
+      "assignee": "mike.frontend@company.com",
+      "labels": ["bug", "frontend", "login"],
+      "created_at": "2024-01-03T09:30:00Z",
+      "updated_at": "2024-01-10T16:00:00Z",
+      "description": "Some users report seeing a white screen when navigating to login page. Appears to be related to JavaScript bundle loading issues.",
+      "resolution": "Fixed race condition in bundle loading. Deployed fix in v2.1.3",
+      "comments": [
+        {
+          "author": "mike.frontend@company.com",
+          "content": "Issue was caused by missing error boundary. Added proper loading states.",
+          "timestamp": "2024-01-10T16:00:00Z"
+        }
+      ]
+    },
+    "ENG-438": {
+      "id": "ENG-438",
+      "title": "Implement password strength indicator", 
+      "status": "completed",
+      "priority": "low",
+      "assignee": "jane.security@company.com",
+      "labels": ["security", "enhancement", "password"],
+      "created_at": "2024-01-01T11:00:00Z",
+      "updated_at": "2024-01-07T13:45:00Z",
+      "description": "Add real-time password strength indicator to signup and password reset forms to help users create secure passwords.",
+      "resolution": "Implemented using zxcvbn library. Shows strength meter and helpful suggestions.",
+      "comments": [
+        {
+          "author": "jane.security@company.com",
+          "content": "Added strength meter with color coding and actionable feedback.",
+          "timestamp": "2024-01-07T13:45:00Z"
+        }
+      ]
+    }
+  }
+}

data/examples/collaborative-copilot/data/stripe_billing.json

@@ -0,0 +1,71 @@
+{
+  "john.smith@example.com": {
+    "customer_id": "cus_123abc",
+    "subscription_status": "active",
+    "current_plan": "Pro Plan",
+    "monthly_amount": 2999,
+    "currency": "usd",
+    "next_billing_date": "2024-02-15",
+    "payment_method": "card_ending_4242",
+    "recent_charges": [
+      {
+        "date": "2024-01-15",
+        "amount": 2999,
+        "status": "succeeded",
+        "description": "Pro Plan subscription"
+      },
+      {
+        "date": "2024-01-10", 
+        "amount": 2999,
+        "status": "failed",
+        "description": "Pro Plan subscription - duplicate charge refunded"
+      }
+    ],
+    "total_paid": 89970,
+    "customer_since": "2023-12-01"
+  },
+  "sarah.j@startup.io": {
+    "customer_id": "cus_456def",
+    "subscription_status": "active",
+    "current_plan": "Basic Plan", 
+    "monthly_amount": 999,
+    "currency": "usd",
+    "next_billing_date": "2024-02-01",
+    "payment_method": "card_ending_1234",
+    "recent_charges": [
+      {
+        "date": "2024-01-01",
+        "amount": 999,
+        "status": "succeeded", 
+        "description": "Basic Plan subscription"
+      }
+    ],
+    "total_paid": 999,
+    "customer_since": "2024-01-01"
+  },
+  "mike.chen@techfirm.com": {
+    "customer_id": "cus_789ghi",
+    "subscription_status": "active",
+    "current_plan": "Enterprise Plan",
+    "monthly_amount": 9999,
+    "currency": "usd", 
+    "next_billing_date": "2024-02-15",
+    "payment_method": "card_ending_5678",
+    "recent_charges": [
+      {
+        "date": "2024-01-15",
+        "amount": 9999,
+        "status": "succeeded",
+        "description": "Enterprise Plan subscription"
+      },
+      {
+        "date": "2023-12-15",
+        "amount": 9999,
+        "status": "succeeded", 
+        "description": "Enterprise Plan subscription"
+      }
+    ],
+    "total_paid": 79992,
+    "customer_since": "2023-06-15"
+  }
+}

data/examples/collaborative-copilot/interactive.rb

@@ -0,0 +1,90 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../../lib/agents"
+require_relative "agents/copilot_orchestrator"
+
+# Configure the agents SDK
+Agents.configure do |config|
+  config.openai_api_key = ENV["OPENAI_API_KEY"]
+  config.default_model = "gpt-4o-mini"
+  config.debug = false
+end
+
+puts "=== Support Copilot Demo ==="
+puts "This demonstrates agent-as-tool collaboration where specialist agents work behind the scenes."
+puts
+
+# Create the main copilot
+copilot = Copilot::CopilotOrchestrator.create
+runner = Agents::Runner.with_agents(copilot)
+context = {}
+
+# Demo scenarios
+# scenarios = [
+#   {
+#     title: "API Errors - Enterprise Customer",
+#     query: "mike.chen@techfirm.com reporting API 500 errors (CONV-004). Help?"
+#   },
+#   {
+#     title: "Angry Customer - Login + Billing",
+#     query: "john.smith@example.com can't login AND has billing issues (CONV-001). Threatening to cancel. What do I do?"
+#   },
+#   {
+#     title: "Dark Mode Feature Request",
+#     query: "Customer asking about dark mode. Is this being worked on? Should I create a ticket?"
+#   },
+#   {
+#     title: "Enterprise Integration Issues",
+#     query: "CONTACT-789 can't get API integration working. Need help with response."
+#   }
+# ]
+
+# scenarios.each_with_index do |scenario, i|
+#   puts("-" * 60)
+#   puts "Scenario #{i + 1}: #{scenario[:title]}"
+#   puts("-" * 60)
+#   puts "Support Agent Query: #{scenario[:query]}"
+#   puts
+#   puts "Copilot Response:"
+#   puts
+
+#   begin
+#     result = runner.run(scenario[:query])
+#     puts result.output
+#   rescue StandardError => e
+#     puts "Error: #{e.message}"
+#   end
+
+#   puts
+#   puts "Press Enter to continue to next scenario..."
+#   gets
+#   puts
+# end
+
+puts "=== Interactive Mode ==="
+puts "Now you can ask the copilot questions directly."
+puts "Type 'exit' to quit."
+puts
+
+loop do
+  print "Support Agent: "
+  input = gets.chomp
+  break if input.downcase == "exit"
+
+  puts
+  puts "Copilot:"
+  begin
+    result = runner.run(input, context: context)
+
+    # Update context with the returned context from Runner
+    context = result.context if result.respond_to?(:context) && result.context
+
+    puts result.output
+  rescue StandardError => e
+    puts "Error: #{e.message}"
+  end
+  puts
+end
+
+puts "Thanks for trying the Support Copilot demo!"

data/examples/collaborative-copilot/tools/create_linear_ticket_tool.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Copilot
+  # Tool for creating Linear tickets for engineering issues
+  class CreateLinearTicketTool < Agents::Tool
+    description "Create a Linear ticket for engineering issues or feature requests"
+    param :title, type: "string", desc: "Title of the issue"
+    param :description, type: "string", desc: "Detailed description of the issue"
+    param :priority, type: "string", desc: "Priority level (low, medium, high)"
+    param :assignee, type: "string", desc: "Optional: email of person to assign to", required: false
+    param :labels, type: "string", desc: "Comma-separated labels (e.g., bug,api,production)"
+
+    def perform(tool_context, title:, description:, priority: "medium", assignee: nil, labels: "")
+      # Generate a ticket ID
+      ticket_id = "ENG-#{rand(100..999)}"
+
+      # Parse labels
+      label_array = labels.split(",").map(&:strip).reject(&:empty?)
+      label_array = ["support-request"] if label_array.empty?
+
+      # Create ticket data
+      {
+        id: ticket_id,
+        title: title,
+        description: description,
+        status: "backlog",
+        priority: priority.downcase,
+        assignee: assignee,
+        labels: label_array,
+        created_at: Time.now.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        reporter: "support-agent"
+      }
+
+      # Store ticket info in shared state
+      tool_context.state[:created_ticket_id] = ticket_id
+      tool_context.state[:ticket_priority] = priority
+      tool_context.state[:ticket_assignee] = assignee
+
+      response = {
+        success: true,
+        ticket_id: ticket_id,
+        title: title,
+        status: "backlog",
+        priority: priority,
+        assignee: assignee,
+        labels: label_array,
+        url: "https://linear.app/company/issue/#{ticket_id}",
+        message: "Successfully created Linear ticket #{ticket_id}"
+      }
+
+      JSON.pretty_generate(response)
+    rescue StandardError => e
+      "Error creating Linear ticket: #{e.message}"
+    end
+  end
+end

data/examples/collaborative-copilot/tools/get_article_tool.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Copilot
+  # Tool for retrieving specific knowledge base articles by ID
+  class GetArticleTool < Agents::Tool
+    description "Get the full content of a specific knowledge base article"
+    param :article_id, type: "string", desc: "ID of the article to retrieve (e.g., ART-001)"
+
+    def perform(tool_context, article_id:)
+      data_file = File.join(__dir__, "../data/knowledge_base.json")
+      return "Knowledge base unavailable" unless File.exist?(data_file)
+
+      begin
+        kb_data = JSON.parse(File.read(data_file))
+        article = kb_data["articles"][article_id.upcase]
+
+        return "Article not found" unless article
+
+        # Store article data in shared state for reference
+        tool_context.state[:last_article_id] = article_id.upcase
+        tool_context.state[:last_article_category] = article["category"]
+
+        response = {
+          id: article_id.upcase,
+          title: article["title"],
+          category: article["category"],
+          content: article["content"],
+          tags: article["tags"],
+          created_at: article["created_at"],
+          updated_at: article["updated_at"]
+        }
+
+        JSON.pretty_generate(response)
+      rescue StandardError => e
+        "Error retrieving article: #{e.message}"
+      end
+    end
+  end
+end

data/examples/collaborative-copilot/tools/get_contact_tool.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Copilot
+  # Tool for retrieving contact/customer information
+  class GetContactTool < Agents::Tool
+    description "Get customer profile and contact information"
+    param :contact_id, type: "string", desc: "ID of the contact to retrieve"
+
+    def perform(tool_context, contact_id:)
+      data_file = File.join(__dir__, "../data/contacts.json")
+      return "Contacts database unavailable" unless File.exist?(data_file)
+
+      begin
+        contacts = JSON.parse(File.read(data_file))
+        contact = contacts[contact_id.upcase]
+
+        return "Contact not found" unless contact
+
+        # Store contact data in shared state for other agents
+        tool_context.state[:contact_name] = contact["name"]
+        tool_context.state[:contact_email] = contact["email"]
+        tool_context.state[:contact_company] = contact["company"]
+        tool_context.state[:contact_plan] = contact["plan"]
+        tool_context.state[:contact_satisfaction] = contact["satisfaction_score"]
+
+        # Format contact information
+        response = {
+          id: contact["id"],
+          name: contact["name"],
+          email: contact["email"],
+          phone: contact["phone"],
+          company: contact["company"],
+          plan: contact["plan"],
+          account_status: contact["account_status"],
+          created_at: contact["created_at"],
+          last_login: contact["last_login"],
+          total_conversations: contact["total_conversations"],
+          satisfaction_score: contact["satisfaction_score"],
+          tags: contact["tags"],
+          notes: contact["notes"]
+        }
+
+        JSON.pretty_generate(response)
+      rescue StandardError => e
+        "Error retrieving contact: #{e.message}"
+      end
+    end
+  end
+end

data/examples/collaborative-copilot/tools/get_conversation_tool.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Copilot
+  # Tool for retrieving conversation details and context
+  class GetConversationTool < Agents::Tool
+    description "Get conversation details, messages, and context for analysis"
+    param :conversation_id, type: "string", desc: "ID of the conversation to retrieve"
+
+    def perform(tool_context, conversation_id:)
+      data_file = File.join(__dir__, "../data/conversations.json")
+      return "Conversations database unavailable" unless File.exist?(data_file)
+
+      begin
+        conversations = JSON.parse(File.read(data_file))
+        conversation = conversations[conversation_id.upcase]
+
+        return "Conversation not found" unless conversation
+
+        # Store conversation data in shared state for other agents
+        tool_context.state[:current_conversation_id] = conversation_id.upcase
+        tool_context.state[:conversation_status] = conversation["status"]
+        tool_context.state[:conversation_subject] = conversation["subject"]
+        tool_context.state[:contact_id] = conversation["contact_id"]
+
+        # Format conversation for analysis
+        formatted_messages = conversation["messages"].map do |msg|
+          "#{msg["role"].upcase} (#{msg["timestamp"]}): #{msg["content"]}"
+        end
+
+        response = {
+          id: conversation["id"],
+          subject: conversation["subject"],
+          status: conversation["status"],
+          contact_id: conversation["contact_id"],
+          created_at: conversation["created_at"],
+          message_count: conversation["messages"].length,
+          tags: conversation["tags"],
+          messages: formatted_messages
+        }
+
+        # Add resolution if available
+        response[:resolution] = conversation["resolution"] if conversation["resolution"]
+        response[:escalation_ticket] = conversation["escalation_ticket"] if conversation["escalation_ticket"]
+
+        JSON.pretty_generate(response)
+      rescue StandardError => e
+        "Error retrieving conversation: #{e.message}"
+      end
+    end
+  end
+end

data/examples/collaborative-copilot/tools/get_stripe_billing_tool.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Copilot
+  # Tool for retrieving Stripe billing information
+  class GetStripeBillingTool < Agents::Tool
+    description "Get customer billing information and payment history from Stripe"
+    param :customer_email, type: "string", desc: "Customer email to look up billing info"
+
+    def perform(tool_context, customer_email:)
+      data_file = File.join(__dir__, "../data/stripe_billing.json")
+      return "Stripe billing data unavailable" unless File.exist?(data_file)
+
+      begin
+        billing_data = JSON.parse(File.read(data_file))
+        customer_data = billing_data[customer_email.downcase]
+
+        return "No billing information found for #{customer_email}" unless customer_data
+
+        # Store billing info in shared state
+        tool_context.state[:stripe_customer_id] = customer_data["customer_id"]
+        tool_context.state[:subscription_status] = customer_data["subscription_status"]
+        tool_context.state[:current_plan] = customer_data["current_plan"]
+
+        formatted_data = {
+          customer_email: customer_email,
+          stripe_customer_id: customer_data["customer_id"],
+          subscription_status: customer_data["subscription_status"],
+          current_plan: customer_data["current_plan"],
+          monthly_amount: "$#{customer_data["monthly_amount"] / 100}",
+          next_billing_date: customer_data["next_billing_date"],
+          payment_method: customer_data["payment_method"],
+          total_paid: "$#{customer_data["total_paid"] / 100}",
+          recent_charges: customer_data["recent_charges"]
+        }
+
+        JSON.pretty_generate(formatted_data)
+      rescue StandardError => e
+        "Error retrieving billing information: #{e.message}"
+      end
+    end
+  end
+end

data/examples/collaborative-copilot/tools/search_contacts_tool.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Copilot
+  # Tool for searching contacts to find patterns and related customers
+  class SearchContactsTool < Agents::Tool
+    description "Search contacts to find patterns, related customers, or specific profiles"
+    param :query, type: "string", desc: "Search terms (name, email, company, or tags)"
+    param :plan, type: "string", desc: "Optional: filter by plan type (Basic, Pro, Enterprise)", required: false
+
+    def perform(_tool_context, query:, plan: nil)
+      data_file = File.join(__dir__, "../data/contacts.json")
+      return "Contacts database unavailable" unless File.exist?(data_file)
+
+      begin
+        contacts = JSON.parse(File.read(data_file))
+        query_text = query.downcase
+        matches = []
+
+        contacts.each do |contact_id, contact|
+          # Skip if plan filter is specified and doesn't match
+          next if plan && contact["plan"].downcase != plan.downcase
+
+          # Simple keyword matching
+          text_to_search = [
+            contact["name"],
+            contact["email"],
+            contact["company"],
+            contact["tags"].join(" "),
+            contact["notes"]
+          ].join(" ").downcase
+
+          next unless text_to_search.include?(query_text)
+
+          matches << {
+            contact_id: contact_id,
+            name: contact["name"],
+            email: contact["email"],
+            company: contact["company"],
+            plan: contact["plan"],
+            tags: contact["tags"],
+            satisfaction_score: contact["satisfaction_score"]
+          }
+        end
+
+        if matches.empty?
+          "No contacts found for: #{query}"
+        else
+          JSON.pretty_generate({ query: query, contacts: matches })
+        end
+      rescue StandardError => e
+        "Error searching contacts: #{e.message}"
+      end
+    end
+  end
+end

data/examples/collaborative-copilot/tools/search_conversations_tool.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Copilot
+  # Tool for searching through conversation history to find similar cases
+  class SearchConversationsTool < Agents::Tool
+    description "Search past conversations for similar cases and resolutions"
+    param :query, type: "string", desc: "Search terms (keywords, tags, or issue description)"
+    param :contact_id, type: "string", desc: "Optional: limit search to specific contact", required: false
+
+    def perform(_tool_context, query:, contact_id: nil)
+      data_file = File.join(__dir__, "../data/conversations.json")
+      return "Conversations database unavailable" unless File.exist?(data_file)
+
+      begin
+        conversations = JSON.parse(File.read(data_file))
+        query_text = query.downcase
+        matches = []
+
+        conversations.each do |conv_id, conversation|
+          # Skip if contact_id filter is specified and doesn't match
+          next if contact_id && conversation["contact_id"] != contact_id.upcase
+
+          # Simple keyword matching
+          text_to_search = [
+            conversation["subject"],
+            conversation["tags"].join(" "),
+            conversation["messages"].map { |m| m["content"] }.join(" "),
+            conversation["resolution"]
+          ].compact.join(" ").downcase
+
+          next unless text_to_search.include?(query_text)
+
+          matches << {
+            conversation_id: conv_id,
+            subject: conversation["subject"],
+            status: conversation["status"],
+            tags: conversation["tags"],
+            resolution: conversation["resolution"]
+          }
+        end
+
+        if matches.empty?
+          "No similar conversations found for: #{query}"
+        else
+          JSON.pretty_generate({ query: query, conversations: matches })
+        end
+      rescue StandardError => e
+        "Error searching conversations: #{e.message}"
+      end
+    end
+  end
+end