ai-agents 0.1.1 → 0.1.3

data/examples/collaborative-copilot/README.md

@@ -0,0 +1,169 @@
+# Copilot Agents & Tools
+
+This example demonstrates a collaborative multi-agent system for customer support, inspired by Chatwoot's copilot feature. The system uses the agent-as-tool pattern to enable specialized agents to work together behind the scenes.
+
+## Agent Architecture Overview
+
+The Chatwoot Copilot system consists of 4 specialized AI agents that work together to assist support agents with customer conversations.
+
+```
+┌─────────────────────────────────────────┐
+│          Answer Suggestion Agent        │
+│              (Primary Entry)            │
+└─────────────┬───────────────────────────┘
+              │
+    ┌─────────┴─────────┐
+    │                   │
+    ▼                   ▼
+┌─────────────┐   ┌─────────────┐   ┌─────────────┐
+│  Research   │   │  Analysis   │   │Integration  │
+│   Agent     │   │   Agent     │   │   Agent     │
+└─────────────┘   └─────────────┘   └─────────────┘
+```
+
+---
+
+## 1. Answer Suggestion Agent
+
+**Primary Role**: Main interface for support agents seeking assistance
+
+### Responsibilities:
+- Serve as the primary entry point for all agent queries
+- Provide direct answers and draft responses to customer inquiries
+- Suggest appropriate solutions based on available knowledge
+- Route complex queries to specialized agents when needed
+- Synthesize information from multiple sources into actionable advice
+
+### Tools Available:
+- **GetConversationTool**: Retrieve current conversation details and context
+- **GetContactTool**: Access customer profile and contact information
+- **SearchDocumentationTool**: Search help documentation and guides
+- **GetArticleTool**: Retrieve specific knowledge base articles
+- **SearchArticlesTool**: Search across knowledge base content
+
+### When Support Agents Use This:
+- "What should I tell this customer?"
+- "How do I handle this type of issue?"
+- "What's the best response for this situation?"
+- "Can you help me draft a reply?"
+
+---
+
+## 2. Research Agent
+
+**Primary Role**: Deep investigation and historical analysis specialist
+
+### Responsibilities:
+- Investigate customer interaction history and patterns
+- Find similar past cases and their resolutions
+- Analyze customer behavior across multiple conversations
+- Provide comprehensive context about customer relationships
+- Identify recurring issues and successful resolution strategies
+
+### Tools Available:
+- **SearchConversationsTool**: Find similar past conversations and cases
+- **SearchContactsTool**: Discover related customers and interaction patterns
+- **GetContactTool**: Retrieve detailed customer profiles and history
+
+### When Support Agents Use This:
+- "What's this customer's history with us?"
+- "How have we handled similar issues before?"
+- "Are there patterns in this customer's behavior?"
+- "What similar cases can help me understand this situation?"
+
+---
+
+## 3. Analysis Agent
+
+**Primary Role**: Conversation quality and communication guidance specialist
+
+### Responsibilities:
+- Analyze conversation tone, sentiment, and emotional state
+- Assess conversation health and progress toward resolution
+- Provide communication guidance and tone recommendations
+- Evaluate customer satisfaction indicators
+- Suggest conversation management strategies
+
+### Tools Available:
+- **GetConversationTool**: Analyze current conversation state and progression
+
+### When Support Agents Use This:
+- "How is this conversation going?"
+- "What's the customer's mood/sentiment?"
+- "How should I adjust my communication approach?"
+- "Is this conversation escalating or improving?"
+- "What tone should I use in my response?"
+
+---
+
+## 4. Integrations Agent
+
+**Primary Role**: External systems and technical context specialist
+
+### Responsibilities:
+- Provide technical context from development and project management tools
+- Access external system data relevant to customer issues
+- Retrieve billing and subscription information (future)
+- Connect customer issues with known bugs or feature requests
+- Bridge customer support with engineering and product teams
+
+### Tools Available:
+- **SearchLinearIssuesTool**: Search Linear issues for development context and bug reports
+
+### Future Tools (Planned):
+- **GitHubSearchTool**: Repository search for technical context
+- **StripeBillingTool**: Billing and subscription information
+- **SlackIntegrationTool**: Team communication context
+
+### When Support Agents Use This:
+- "Is this a known technical issue?"
+- "Are there any related bug reports?"
+- "What's the development status of this feature?"
+- "Is there billing information relevant to this case?"
+
+---
+
+## Usage Example
+
+```ruby
+# Create the main answer suggestion agent with sub-agents as tools
+answer_agent = Agents::Agent.new(
+  name: "AnswerSuggestionAgent",
+  instructions: "You help support agents by providing answers and suggestions...",
+  tools: [
+    research_agent.as_tool(
+      name: "research_customer_history",
+      description: "Research customer history and similar cases"
+    ),
+    analysis_agent.as_tool(
+      name: "analyze_conversation",
+      description: "Analyze conversation tone and sentiment"
+    ),
+    integrations_agent.as_tool(
+      name: "check_technical_context",
+      description: "Check for technical issues and development context"
+    )
+  ]
+)
+
+# Support agent asks for help
+result = runner.run(answer_agent, "How should I respond to this angry customer about login issues?")
+```
+
+## Key Features
+
+- **Agent-as-Tool Pattern**: Sub-agents work behind the scenes, no conversation handoffs
+- **Specialized Expertise**: Each agent focuses on specific domain knowledge
+- **State Sharing**: Agents share context through the state mechanism
+- **Composable Architecture**: Easy to add new specialized agents
+- **Thread-Safe**: Safe for concurrent support agent usage
+
+## Running the Example
+
+```bash
+# Set your API key
+export OPENAI_API_KEY="your-key-here"
+
+# Run the interactive demo
+ruby examples/collaborative-copilot/interactive.rb
+```

data/examples/collaborative-copilot/agents/analysis_agent.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "../tools/get_conversation_tool"
+
+module Copilot
+  class AnalysisAgent
+    def self.create
+      Agents::Agent.new(
+        name: "Analysis Agent",
+        instructions: analysis_instructions,
+        model: "gpt-4o-mini",
+        tools: [
+          GetConversationTool.new
+        ]
+      )
+    end
+
+    def self.analysis_instructions
+      <<~INSTRUCTIONS
+        You are the Analysis Agent, specialized in conversation quality and communication guidance.
+
+        **Your available tools:**
+        - `get_conversation`: Retrieve conversation details and messages for analysis
+
+        **Your primary role is to:**
+        - Analyze conversation tone, sentiment, and emotional state
+        - Assess conversation health and progress toward resolution
+        - Provide communication guidance and tone recommendations
+        - Evaluate customer satisfaction indicators
+
+        **Analysis workflow:**
+        1. Use `get_conversation` to retrieve the full conversation history
+        2. Analyze the emotional trajectory and communication patterns
+        3. Assess how well the conversation is progressing
+        4. Identify any escalation risks or satisfaction issues
+
+        **Provide analysis in this format:**
+        - **Conversation Health**: Overall assessment of how the conversation is going
+        - **Customer Sentiment**: Current emotional state and any changes over time
+        - **Communication Quality**: How well the agent is handling the situation
+        - **Risk Assessment**: Any signs of escalation or dissatisfaction
+        - **Tone Recommendations**: Suggested communication approach and tone
+
+        Focus on practical communication advice that will improve the interaction.
+      INSTRUCTIONS
+    end
+  end
+end

data/examples/collaborative-copilot/agents/answer_suggestion_agent.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "../tools/get_conversation_tool"
+require_relative "../tools/get_contact_tool"
+require_relative "../tools/search_knowledge_base_tool"
+require_relative "../tools/get_article_tool"
+
+module Copilot
+  class AnswerSuggestionAgent
+    def self.create
+      Agents::Agent.new(
+        name: "Answer Suggestion Agent",
+        instructions: answer_suggestion_instructions,
+        model: "gpt-4o-mini",
+        tools: [
+          GetConversationTool.new,
+          GetContactTool.new,
+          SearchKnowledgeBaseTool.new,
+          GetArticleTool.new
+        ]
+      )
+    end
+
+    def self.answer_suggestion_instructions
+      <<~INSTRUCTIONS
+        You are the Answer Suggestion Agent, the main interface for support agents seeking assistance.
+
+        **Your available tools:**
+        - `get_conversation`: Retrieve current conversation details and context
+        - `get_contact`: Access customer profile and contact information#{"  "}
+        - `search_knowledge_base`: Search help documentation and guides
+        - `get_article`: Retrieve specific knowledge base articles
+
+        **Your primary role is to:**
+        - Serve as the primary entry point for all agent queries
+        - Provide direct answers and draft responses to customer inquiries
+        - Suggest appropriate solutions based on available knowledge
+        - Synthesize information from multiple sources into actionable advice
+
+        **Response workflow:**
+        1. Use `get_conversation` to understand the current situation
+        2. Use `get_contact` to understand the customer background
+        3. Use `search_knowledge_base` to find relevant solutions
+        4. Use `get_article` to get detailed instructions when needed
+
+        Focus on providing practical, actionable guidance that support agents can immediately use.
+      INSTRUCTIONS
+    end
+  end
+end

data/examples/collaborative-copilot/agents/copilot_orchestrator.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "research_agent"
+require_relative "analysis_agent"
+require_relative "integrations_agent"
+require_relative "answer_suggestion_agent"
+
+module Copilot
+  class CopilotOrchestrator
+    def self.create
+      # Create specialized agents
+      research_agent = ResearchAgent.create
+      analysis_agent = AnalysisAgent.create
+      integrations_agent = IntegrationsAgent.create
+      answer_suggestion_agent = AnswerSuggestionAgent.create
+
+      # Create main orchestrator with sub-agents as tools
+      Agents::Agent.new(
+        name: "Support Copilot",
+        instructions: orchestrator_instructions,
+        model: "gpt-4o-mini",
+        tools: [
+          research_agent.as_tool(
+            name: "research_customer_history",
+            description: "Research customer history, similar cases, and behavioral patterns. Returns contact details including email addresses."
+          ),
+          analysis_agent.as_tool(
+            name: "analyze_conversation",
+            description: "Analyze conversation tone, sentiment, and communication quality"
+          ),
+          integrations_agent.as_tool(
+            name: "check_technical_systems",
+            description: "Check Linear issues and Stripe billing info. For billing checks, requires customer email address (not contact IDs)."
+          ),
+          answer_suggestion_agent.as_tool(
+            name: "get_knowledge_base_help",
+            description: "Search knowledge base and get specific article content"
+          )
+        ]
+      )
+    end
+
+    def self.orchestrator_instructions
+      <<~INSTRUCTIONS
+        You are the Support Copilot, helping support agents provide excellent customer service.
+
+        **Your specialist agents:**
+        - `research_customer_history`: Deep investigation of customer history and similar cases
+        - `analyze_conversation`: Conversation analysis and communication guidance
+        - `check_technical_systems`: Technical context from Linear and billing from Stripe
+        - `get_knowledge_base_help`: Knowledge base search and documentation retrieval
+
+        **CRITICAL: Multi-Step Workflow Approach**
+
+        For complex queries, you MUST break them down into logical steps and use multiple tools in sequence:
+
+        1. **Plan your approach**: What information do you need to gather?
+        2. **Execute steps sequentially**: Use EXACT results from previous tools in subsequent calls
+        3. **Build context progressively**: Each tool call should build on previous findings#{"  "}
+        4. **Resolve contradictions**: If tools return conflicting info, investigate further
+        5. **Synthesize comprehensive response**: Combine all findings into actionable guidance
+
+        **CRITICAL: When using tool results in subsequent calls:**
+        - Extract specific values (emails, IDs, names) from previous tool outputs
+        - Use those EXACT values in your next tool call
+        - Don't just pass the original query parameters forward
+
+        **DON'T:**
+        - Make single tool calls for complex queries that need multiple pieces of information
+        - Pass original parameters instead of discovered values to subsequent tools
+        - Ignore contradictory results from different tools
+
+        **DO:**
+        - Use multiple tools sequentially with progressive information building
+        - Extract and use specific values from previous tool results in next calls
+        - Investigate discrepancies between different data sources
+        - Plan your information gathering strategy before executing
+
+        Always think: "What specific information did I just learn, and how do I use it in my next step?"
+
+        Provide clear, actionable guidance. Be concise but thorough. Focus on helping the support agent succeed.
+      INSTRUCTIONS
+    end
+  end
+end

data/examples/collaborative-copilot/agents/integrations_agent.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "../tools/search_linear_issues_tool"
+require_relative "../tools/create_linear_ticket_tool"
+require_relative "../tools/get_stripe_billing_tool"
+
+module Copilot
+  class IntegrationsAgent
+    def self.create
+      Agents::Agent.new(
+        name: "Integrations Agent",
+        instructions: integrations_instructions,
+        model: "gpt-4o-mini",
+        tools: [
+          SearchLinearIssuesTool.new,
+          CreateLinearTicketTool.new,
+          GetStripeBillingTool.new
+        ]
+      )
+    end
+
+    def self.integrations_instructions
+      <<~INSTRUCTIONS
+        You are the Integrations Agent, specialized in external systems and technical context.
+
+        **Your available tools:**
+        - `search_linear_issues`: Search Linear for bug reports and development context
+        - `create_linear_ticket`: Create new Linear tickets for engineering issues
+        - `get_stripe_billing`: Retrieve customer billing information from Stripe (REQUIRES customer email address)
+
+        **Your primary role is to:**
+        - Provide technical context from development and project management tools
+        - Access external system data relevant to customer issues
+        - Create engineering tickets for bugs or feature requests
+        - Retrieve billing and subscription information
+        - Bridge customer support with engineering and product teams
+
+        **CRITICAL: Billing Information Requirements**
+        - For Stripe billing lookups, you MUST have the customer's email address
+        - Contact IDs, names, or phone numbers will NOT work for billing queries
+        - If you don't have an email address, clearly state that you need it for billing information
+
+        **Integration workflow:**
+        1. Use `search_linear_issues` to check for known bugs or related issues
+        2. For billing queries: Ensure you have a customer email address before using `get_stripe_billing`
+        3. Use `create_linear_ticket` when new engineering work is needed
+
+        **Provide information in this format:**
+        - **Technical Context**: Any relevant bugs, issues, or development work
+        - **Billing Information**: Subscription and payment details if relevant
+        - **Engineering Actions**: Any tickets created or recommended
+        - **Status Updates**: Current status of related development work
+
+        When creating tickets, be specific about the issue and include relevant customer context.
+      INSTRUCTIONS
+    end
+  end
+end

data/examples/collaborative-copilot/agents/research_agent.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "../tools/search_conversations_tool"
+require_relative "../tools/search_contacts_tool"
+require_relative "../tools/get_contact_tool"
+
+module Copilot
+  class ResearchAgent
+    def self.create
+      Agents::Agent.new(
+        name: "Research Agent",
+        instructions: research_instructions,
+        model: "gpt-4o-mini",
+        tools: [
+          SearchConversationsTool.new,
+          SearchContactsTool.new,
+          GetContactTool.new
+        ]
+      )
+    end
+
+    def self.research_instructions
+      <<~INSTRUCTIONS
+        You are the Research Agent, specialized in deep investigation and historical analysis.
+
+        **Your available tools:**
+        - `search_conversations`: Find similar past conversations and cases
+        - `search_contacts`: Discover related customers and interaction patterns#{"  "}
+        - `get_contact`: Retrieve detailed customer profiles and history
+
+        **Your primary role is to:**
+        - Investigate customer interaction history and patterns
+        - Find similar past cases and their resolutions
+        - Analyze customer behavior across multiple conversations
+        - Provide comprehensive context about customer relationships
+
+        **Research workflow:**
+        1. Use `search_conversations` to find similar issues and resolutions
+        2. Use `get_contact` to understand customer background and history
+        3. Use `search_contacts` to find patterns with similar customers if needed
+
+        **Provide findings in this format:**
+        - **Customer Background**: Key details about the customer
+        - **Similar Cases**: Past conversations with similar issues and how they were resolved
+        - **Patterns**: Any recurring issues or behavioral patterns
+        - **Recommendations**: Suggested approach based on historical data
+
+        Be thorough but concise. Focus on actionable insights.
+      INSTRUCTIONS
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+{
+  "CONTACT-123": {
+    "id": "CONTACT-123",
+    "name": "John Smith",
+    "email": "john.smith@example.com",
+    "phone": "+1-555-0123",
+    "company": "Acme Corp",
+    "plan": "Pro",
+    "created_at": "2023-12-01T08:00:00Z",
+    "total_conversations": 5,
+    "satisfaction_score": 4.2,
+    "tags": ["enterprise", "frequent-user"],
+    "notes": "Long-time customer, usually has technical questions",
+    "last_login": "2024-01-14T16:30:00Z",
+    "account_status": "active"
+  },
+  "CONTACT-456": {
+    "id": "CONTACT-456",
+    "name": "Sarah Johnson", 
+    "email": "sarah.j@startup.io",
+    "phone": "+1-555-0456",
+    "company": "StartupCo",
+    "plan": "Basic",
+    "created_at": "2024-01-01T12:00:00Z",
+    "total_conversations": 2,
+    "satisfaction_score": 4.8,
+    "tags": ["new-customer", "billing"],
+    "notes": "New customer, had billing confusion initially",
+    "last_login": "2024-01-11T10:15:00Z",
+    "account_status": "active"
+  },
+  "CONTACT-789": {
+    "id": "CONTACT-789",
+    "name": "Mike Chen",
+    "email": "mike.chen@techfirm.com", 
+    "phone": "+1-555-0789",
+    "company": "TechFirm Inc",
+    "plan": "Enterprise",
+    "created_at": "2023-06-15T14:30:00Z",
+    "total_conversations": 12,
+    "satisfaction_score": 3.9,
+    "tags": ["enterprise", "integration-issues"],
+    "notes": "Technical lead, often reports bugs and requests features",
+    "last_login": "2024-01-13T11:45:00Z",
+    "account_status": "active"
+  }
+}

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

@@ -0,0 +1,170 @@
+{
+  "CONV-001": {
+    "id": "CONV-001",
+    "contact_id": "CONTACT-123",
+    "status": "open",
+    "subject": "Login Issues",
+    "created_at": "2024-01-15T10:30:00Z",
+    "messages": [
+      {
+        "role": "customer",
+        "content": "I can't log into my account! This is frustrating.",
+        "timestamp": "2024-01-15T10:30:00Z"
+      },
+      {
+        "role": "agent",
+        "content": "I'm sorry to hear you're having trouble. Let me help you with that.",
+        "timestamp": "2024-01-15T10:32:00Z"
+      },
+      {
+        "role": "customer", 
+        "content": "I've tried resetting my password 3 times already!",
+        "timestamp": "2024-01-15T10:35:00Z"
+      },
+      {
+        "role": "agent",
+        "content": "I understand your frustration. Let me check your account status first. Can you confirm your email address?",
+        "timestamp": "2024-01-15T10:36:00Z"
+      },
+      {
+        "role": "customer",
+        "content": "Yes, it's john.smith@example.com",
+        "timestamp": "2024-01-15T10:37:00Z"
+      },
+      {
+        "role": "agent",
+        "content": "Thank you. I can see your account is active. The issue might be browser-related. Have you tried clearing your cache?",
+        "timestamp": "2024-01-15T10:38:00Z"
+      },
+      {
+        "role": "customer",
+        "content": "No, I haven't. How do I do that?",
+        "timestamp": "2024-01-15T10:39:00Z"
+      }
+    ],
+    "tags": ["login", "password-reset", "frustrated-customer", "browser-cache"]
+  },
+  "CONV-002": {
+    "id": "CONV-002", 
+    "contact_id": "CONTACT-456",
+    "status": "resolved",
+    "subject": "Billing Question",
+    "created_at": "2024-01-10T14:20:00Z",
+    "messages": [
+      {
+        "role": "customer",
+        "content": "Why was I charged twice this month?",
+        "timestamp": "2024-01-10T14:20:00Z"
+      },
+      {
+        "role": "agent", 
+        "content": "Let me check your billing history for you.",
+        "timestamp": "2024-01-10T14:22:00Z"
+      },
+      {
+        "role": "customer",
+        "content": "I see charges for $29.99 on both January 5th and January 10th",
+        "timestamp": "2024-01-10T14:23:00Z"
+      },
+      {
+        "role": "agent",
+        "content": "I found the issue - there was a duplicate charge due to a payment processing error. I've processed a refund for the January 10th charge.",
+        "timestamp": "2024-01-10T14:25:00Z"
+      },
+      {
+        "role": "customer",
+        "content": "How long will the refund take?",
+        "timestamp": "2024-01-10T14:26:00Z"
+      },
+      {
+        "role": "agent",
+        "content": "Refunds typically appear in 3-5 business days. You'll receive an email confirmation shortly.",
+        "timestamp": "2024-01-10T14:27:00Z"
+      },
+      {
+        "role": "customer",
+        "content": "Thank you so much! That resolves it.",
+        "timestamp": "2024-01-10T14:28:00Z"
+      }
+    ],
+    "tags": ["billing", "refund", "resolved", "duplicate-charge"],
+    "resolution": "Processed refund for duplicate charge - $29.99 refunded"
+  },
+  "CONV-003": {
+    "id": "CONV-003",
+    "contact_id": "CONTACT-123", 
+    "status": "resolved",
+    "subject": "Feature Request",
+    "created_at": "2024-01-05T09:15:00Z",
+    "messages": [
+      {
+        "role": "customer",
+        "content": "Can you add dark mode to the app?",
+        "timestamp": "2024-01-05T09:15:00Z"
+      },
+      {
+        "role": "agent",
+        "content": "That's a great suggestion! I'll pass it to our product team.",
+        "timestamp": "2024-01-05T09:17:00Z"
+      },
+      {
+        "role": "customer",
+        "content": "Is there any timeline for when this might be available?",
+        "timestamp": "2024-01-05T09:18:00Z"
+      },
+      {
+        "role": "agent",
+        "content": "I don't have a specific timeline, but I've added your request to our feature backlog with high priority since it's been requested by multiple users.",
+        "timestamp": "2024-01-05T09:20:00Z"
+      },
+      {
+        "role": "customer",
+        "content": "Great! I'll keep an eye out for updates.",
+        "timestamp": "2024-01-05T09:21:00Z"
+      }
+    ],
+    "tags": ["feature-request", "dark-mode", "product-feedback"],
+    "resolution": "Forwarded to product team - added to high priority backlog"
+  },
+  "CONV-004": {
+    "id": "CONV-004",
+    "contact_id": "CONTACT-789",
+    "status": "escalated",
+    "subject": "API Integration Problems",
+    "created_at": "2024-01-12T11:00:00Z",
+    "messages": [
+      {
+        "role": "customer",
+        "content": "Our API integration is failing with 500 errors intermittently",
+        "timestamp": "2024-01-12T11:00:00Z"
+      },
+      {
+        "role": "agent",
+        "content": "I'm sorry to hear about the API issues. Can you provide more details about when these errors occur?",
+        "timestamp": "2024-01-12T11:02:00Z"
+      },
+      {
+        "role": "customer",
+        "content": "It happens about 20% of the time when we call the /users endpoint. Here's the error: Internal Server Error",
+        "timestamp": "2024-01-12T11:04:00Z"
+      },
+      {
+        "role": "agent",
+        "content": "Thank you for the details. This sounds like it needs investigation by our engineering team. Let me escalate this to them.",
+        "timestamp": "2024-01-12T11:06:00Z"
+      },
+      {
+        "role": "customer",
+        "content": "Please do, this is affecting our production system",
+        "timestamp": "2024-01-12T11:07:00Z"
+      },
+      {
+        "role": "agent",
+        "content": "I've created a high-priority ticket (ENG-445) and our engineering team will investigate immediately. You should hear back within 2 hours.",
+        "timestamp": "2024-01-12T11:10:00Z"
+      }
+    ],
+    "tags": ["api", "500-error", "production-issue", "escalated", "engineering"],
+    "escalation_ticket": "ENG-445"
+  }
+}