Skip to main content

🚲 "Hey Bike" Agent Setup Guide

🎯 Goal: Global Help Agent in 45 Minutes​

Create "Bike" - the friendly, globally accessible Bike4Mind assistant that anyone can chat with using "Hey Bike" or "@bike".

📋 Prerequisites​

Required Information​

  • Admin access to create agents
  • Access to agent creation API/UI
  • Documentation files uploaded to knowledge base
  • Understanding of existing isPublic agent feature

Verify Existing Infrastructure ✅​

# Check that public agent infrastructure exists
# These should all return results:

# 1. Agent model supports isPublic
grep -r "isPublic" b4m-core/packages/core/common/types/entities/AgentTypes.ts

# 2. Repository supports public agent search  
grep -r "searchAccessible" b4m-core/packages/core/database/src/models/AgentModel.ts

# 3. Permission system supports public agents
grep -r "isPublic" packages/client/server/auth/ability.ts

🚀 Implementation Steps​

Step 1: Create the Global "Bike" Agent (15 minutes)​

Using Agent Creation API​

// POST /api/agents
const bikeAgent = {
  "name": "Bike",
  "description": "I'm Bike4Mind's official assistant! I know everything about our platform - from Mementos and Questmaster to voice agents and file sharing. I'm here to help everyone succeed with Bike4Mind. Ask me anything about features, troubleshooting, best practices, or just say 'Hey Bike!' to get started.",
  
  // 🔑 CRITICAL: Make it globally accessible
  "isPublic": true,
  "isGlobalRead": true,
  "isGlobalWrite": false,
  
  // 🎯 Enhanced trigger words for natural interaction
  "triggerWords": [
    "@bike", "@help", "@assistant", "@support", 
    "hey bike", "bike help", "help bike"
  ],
  
  // 🤖 Friendly, official personality
  "personality": {
    "majorMotivation": "Being the helpful face of Bike4Mind and ensuring every user can master the platform",
    "minorMotivation": "Connecting users with the perfect features for their workflow",
    "quirk": "I get genuinely excited when I can show users powerful feature combinations they didn't know existed",
    "flaw": "Sometimes my enthusiasm means I share more details than you asked for - just let me know if you want me to be more concise!",
    "description": "Friendly, knowledgeable, and endlessly patient. I'm like having a Bike4Mind expert friend who's always available to help."
  },
  
  // 🎛️ Capabilities and behavior
  "capabilities": [JSON.stringify({
    "responseStyle": "Friendly, comprehensive, and action-oriented with clear next steps",
    "specialBehaviors": [
      "global-help-expert",
      "feature-connector", 
      "workflow-advisor",
      "friendly-troubleshooter",
      "onboarding-guide"
    ],
    "knowledgeDomains": [
      "all-features", "troubleshooting", "best-practices", 
      "integrations", "workflows", "getting-started"
    ],
    "responsePatterns": {
      "greeting": "Hey there! I'm Bike, your Bike4Mind assistant. What can I help you with today?",
      "clarification": "I want to make sure I give you exactly what you need - could you tell me a bit more about...",
      "followUp": "Is there anything else about [topic] you'd like to explore? I love helping users discover new possibilities!"
    }
  })],
  
  // 🎨 Visual identity
  "visual": {
    "avatar": "🚲",
    "color": "#0066cc",
    "style": "official-assistant"
  },
  
  // 🏷️ System identification
  "tags": ["official", "system-agent", "global-help", "public", "bike4mind-assistant"],
  
  // 👤 Identity (friendly, helpful persona)
  "identity": {
    "gender": "non-binary",
    "pronouns": {
      "subject": "they",
      "object": "them"
    }
  },
  
  // 📊 Metadata
  "metadata": {
    "isOfficial": true,
    "createdBy": "system",
    "globalAccessLevel": "public",
    "version": "1.0"
  }
};

// Create the agent
const response = await fetch('/api/agents', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(bikeAgent)
});

const createdAgent = await response.json();
console.log('Bike agent created:', createdAgent.id);

Using Admin UI (Alternative)​

# Navigate to agent creation interface
# Fill in the form with the values above
# CRITICAL: Enable "Public Agent" checkbox
# CRITICAL: Add all trigger words including "hey bike"
# Save and verify agent appears in public agent list

Step 2: Enhance Agent Detection for Global Patterns (20 minutes)​

Modify AgentDetectionFeature.ts​

// Add to: /b4m-core/packages/core/services/llm/features/AgentDetectionFeature.ts

// Enhance the detectMentions method to handle natural language patterns
async detectMentions(message: string): Promise<string[]> {
  const mentions: string[] = [];
  
  // Existing @mention detection
  const atMentions = message.match(/@(\w+)/g)?.map(m => m.slice(1)) || [];
  mentions.push(...atMentions);
  
  // NEW: Natural language patterns for Bike agent
  const naturalPatterns = [
    /\bhey bike\b/i,
    /\bbike help\b/i, 
    /\bhelp bike\b/i,
    /\bbike4mind help\b/i,
    /\bhelp me bike\b/i
  ];
  
  const hasNaturalTrigger = naturalPatterns.some(pattern => pattern.test(message));
  if (hasNaturalTrigger) {
    mentions.push('bike'); // This will match the @bike trigger word
  }
  
  this.service.logger.log(`🔍 Detected mentions: ${JSON.stringify(mentions)}`);
  return mentions;
}

// Enhance beforeDataGathering to prioritize global agents
async beforeDataGathering(args: any): Promise<{ shouldContinue: boolean }> {
  const { message, quest, session } = args;
  
  let agentsToProcess: IAgent[] = [];
  
  // Check for attached agents first
  const attachedAgentIds = quest.agentIds || session.agentIds || [];
  if (attachedAgentIds.length > 0) {
    const attachedAgents = await Promise.all(
      attachedAgentIds.map(agentId => this.service.db.agents.findById(agentId))
    );
    agentsToProcess = attachedAgents.filter(agent => agent !== null);
  }
  
  // If no attached agents, check for mentions (including natural language)
  if (agentsToProcess.length === 0) {
    const mentions = await this.detectMentions(message);
    
    if (mentions.length > 0) {
      const triggerWordsToSearch = mentions.map(mention => `@${mention}`);
      
      // Search for both private and public agents
      const mentionedAgents = await this.service.db.agents.findByTriggerWords(
        triggerWordsToSearch,
        this.service.user.id
      );
      
      // ENHANCEMENT: Also search public agents if no private agents found
      if (mentionedAgents.length === 0) {
        const publicAgents = await this.service.db.agents.searchAccessible(
          this.service.user.id,
          '',
          { 
            isPublic: true,
            triggerWords: { $in: triggerWordsToSearch }
          }
        );
        agentsToProcess = publicAgents;
      } else {
        agentsToProcess = mentionedAgents;
      }
    }
  }
  
  if (agentsToProcess.length > 0) {
    (quest as any)._agentsToProcess = agentsToProcess;
    this.service.logger.log(`🔍 Will process ${agentsToProcess.length} agents (${agentsToProcess.map(a => a.name).join(', ')})`);
  }
  
  return { shouldContinue: true };
}

Step 3: Test the Implementation (10 minutes)​

Basic Functionality Tests​

# Test 1: @mention pattern
"@bike what are Mementos?"

# Test 2: Natural language pattern  
"Hey Bike, how do I use Questmaster?"

# Test 3: Help pattern
"Hey Bike, I need help with file sharing"

# Test 4: Casual conversation
"Hey Bike! What's the best way to get started?"

# Test 5: Troubleshooting
"@bike troubleshoot voice agents not working"

Verification Checklist​

  • Agent responds to @bike mentions
  • Agent responds to "Hey Bike" natural language
  • Agent has access to documentation via vector search
  • Agent maintains friendly "Bike" personality
  • All users can interact with the agent (test with different accounts)
  • Agent appears in public agent lists
  • No errors in server logs during interactions

🔧 Advanced Configuration​

Customize Response Behavior​

// Adjust agent personality for different use cases
const responseStyles = {
  beginner: {
    responseStyle: "Patient, step-by-step with lots of encouragement",
    maxComplexity: "simple"
  },
  
  expert: {
    responseStyle: "Efficient, technical, with advanced tips",
    includeAdvancedFeatures: true
  },
  
  troubleshooting: {
    responseStyle: "Systematic problem-solving with diagnostic questions",
    includeLogAnalysis: true
  }
};

Enhanced Trigger Patterns​

// Add more natural language patterns
const extendedTriggers = [
  // Formal patterns
  "@bike", "@help", "@assistant", "@support",
  
  // Conversational patterns  
  "hey bike", "hi bike", "bike help", "help bike",
  
  // Question patterns
  "can bike4mind", "does bike4mind", "how does bike4mind",
  
  // Contextual patterns
  "I need help", "can you help", "show me how",
  "what is", "how do I", "where can I find"
];

Documentation Categories​

// Tag documentation for smart routing
const docCategories = {
  "getting-started": ["quick-start.md", "onboarding.md"],
  "features": ["mementos.md", "quest-master.md", "knowledge-management.md"],
  "troubleshooting": ["voice-bug-fixes.md", "troubleshooting.md"],
  "advanced": ["technical_docs/**", "api-reference.md"],
  "security": ["security/**"]
};

🎨 User Experience Enhancements​

Smart Greeting Detection​

// Detect when users are just saying hello
const greetingPatterns = [
  /^hey bike!?$/i,
  /^hi bike!?$/i, 
  /^hello bike!?$/i
];

// Respond with friendly, helpful greeting
if (greetingPatterns.some(pattern => pattern.test(message))) {
  // Include context-aware suggestions
  return "Hey there! I'm Bike, your Bike4Mind assistant. I'm here to help with anything - features, troubleshooting, or just exploring what's possible. What would you like to know about?";
}

Context-Aware Responses​

// Detect user's current context for better help
const contextDetection = {
  currentPage: "Detect from browser URL/referrer",
  userLevel: "Infer from usage patterns", 
  recentActions: "Track recent feature usage",
  previousQuestions: "Remember session history"
};

Follow-up Suggestions​

// Suggest related topics based on the query
const followUpSuggestions = {
  mementos: ["knowledge-management", "file-organization", "tagging"],
  questmaster: ["automation", "workflows", "task-management"], 
  "voice-agents": ["real-time-features", "model-selection", "troubleshooting"]
};

🔍 Monitoring & Analytics​

Track Usage Patterns​

// Monitor global agent effectiveness
const analytics = {
  queryTypes: "Track what users ask about most",
  responseQuality: "Monitor user satisfaction/feedback",
  documentationGaps: "Identify topics without good docs",
  popularFeatures: "See which features generate most questions"
};

Performance Metrics​

const metrics = {
  responseTime: "< 2 seconds for most queries",
  documentationCoverage: "> 90% of queries answerable from docs", 
  userSatisfaction: "> 4.5/5 average rating",
  globalUsage: "Track adoption across user base"
};

🚨 Troubleshooting​

Common Issues​

"Bike agent not responding to 'Hey Bike'"​

# Check agent trigger words
db.agents.findOne({name: "Bike"}, {triggerWords: 1})

# Verify detectMentions enhancement
# Look for logs: "Detected mentions: ['bike']"

"Agent not accessible to all users"​

# Verify public flag
db.agents.findOne({name: "Bike"}, {isPublic: 1, isGlobalRead: 1})

# Should return: {isPublic: true, isGlobalRead: true}

"No documentation in responses"​

# Verify documentation was uploaded with correct tags
db.fabfilechunks.find({"fabFile.tags": "help-system"}).count()

# Check vector search is working
# Look for logs in getContextMessages method

🎉 Success Metrics​

Immediate Success (Day 1)​

  • "Hey Bike" triggers the agent
  • Agent responds with documentation context
  • All users can interact with the agent
  • Agent maintains friendly personality

Short-term Success (Week 1)​

  • Users naturally discover and use "Hey Bike"
  • Response quality meets user expectations
  • No performance degradation
  • Positive user feedback

Long-term Success (Month 1)​

  • Reduced support ticket volume
  • Increased feature adoption through guidance
  • Users report feeling more confident with platform
  • Agent becomes integral to user experience

🚀 Ready to Launch!​

The "Hey Bike" agent leverages your existing public agent infrastructure perfectly:

  • ✅ Uses proven isPublic sharing system
  • ✅ Enhances existing natural language detection
  • ✅ Integrates with existing documentation search
  • ✅ Maintains all existing security and permissions

Total implementation time: 45 minutes using your battle-tested infrastructure! 🚲