Multi-Agent Chat System

A sophisticated system that manages multiple AI agents with specialized capabilities, handles multiple concurrent conversations, and routes queries to appropriate databases intelligently.

Key Concepts

Conversations

Each conversation is isolated with its own:

Context: Topics, sentiment, engagement level
Message history: Full conversation thread
Category: Research, betting, technical, general
Cost tracking: Token usage and API costs

Agents

Specialized workers that handle specific tasks:

Agent	Role	Expertise
Router Agent	Decides which agent to use	Query classification
League Agent	League-specific analysis	Sports data, partnerships
Betting Agent	Betting market analysis	Odds, value betting
Code Agent	Technical assistance	Debugging, implementation
Data Agent	Data collection	Database queries
Analysis Agent	Processing and insights	Statistics, trends
Report Agent	Output formatting	Reports, summaries

Database Contexts

Smart routing to data sources:

const DATABASE_CONTEXTS = {
  all: 'Intelligent cross-database routing',
  leagues: 'League entity data',
  players: 'Player statistics and info',
  teams: 'Team information',
  games: 'Game schedules and results',
  markets: 'Betting markets and odds',
  redshift: 'Analytics warehouse',
  supabase: 'Operational database',
  neo4j: 'Graph relationships',
  vectordb: 'Semantic search'
}

Flow Steps

Multi-step processes with progress tracking:

interface FlowStep {
  id: number;
  name: string;
  agentName: string;
  description: string;
  status: 'pending' | 'processing' | 'completed' | 'error';
  startTime?: string;
  endTime?: string;
  durationMs?: number;
  progress?: number;
}

System Architecture

User Input
    ↓
Conversation Intelligence (analyzes)
    ↓
Router Agent (decides)
    ↓
Specialized Agent (executes)
    ↓
Worker Agents (data, analysis, insights, report)
    ↓
Database Context Router (queries)
    ↓
Flow Execution (multi-step)
    ↓
Response Generation (format)
    ↓
Learning & Reflection (improve)

Common Use Cases

// User asks: "Analyze Premier Lacrosse League partnerships"
 
// System automatically:
// 1. Detects: Topic = sports, analytics, business
// 2. Routes to: LeagueAnalysisAgent + Database Context "leagues"
// 3. Executes flow:
//    - Data Collection (fetch from Redshift/Neo4j)
//    - Analysis (process partnerships)
//    - Insights (generate recommendations)
//    - Report (format results)
// 4. Learns: User prefers detailed analysis

Result: Comprehensive partnership analysis with visualizations

Developer Guide

Creating a New Conversation

import { useChatStore } from '@/store/chat-store'
 
const { createConversation, setCurrentConversation } = useChatStore()
 
// Create conversation
const convId = createConversation(
  'League Research', // title
  'research'         // category
)
 
setCurrentConversation(convId)

Sending a Message

import { useChatStore } from '@/store/chat-store'
import { analyzeUserMessage } from '@/lib/conversation-intelligence'
 
const { addMessage, getCurrentConversation } = useChatStore()
const conversation = getCurrentConversation()
 
// Add user message
addMessage(conversation.id, {
  role: 'user',
  content: 'Analyze Premier Lacrosse League',
  cost: 0
})
 
// Analyze with intelligence layer
const context = analyzeUserMessage(
  conversation.id,
  'Analyze Premier Lacrosse League'
)
// context now contains: topics, intent, sentiment, etc.

Executing a Multi-Step Flow

import { useChatStore } from '@/store/chat-store'
import type { FlowStep } from '@/store/chat-store'
 
// Define flow steps
const steps: FlowStep[] = [
  {
    id: 1,
    name: 'Data Collection',
    agentName: 'Data Agent',
    description: 'Fetching league data',
    status: 'pending'
  },
  {
    id: 2,
    name: 'Analysis',
    agentName: 'Analysis Agent',
    description: 'Processing partnerships',
    status: 'pending'
  },
  {
    id: 3,
    name: 'Report',
    agentName: 'Report Agent',
    description: 'Formatting results',
    status: 'pending'
  }
]
 
// Add assistant message with flow steps
addMessage(conversation.id, {
  role: 'assistant',
  content: '🔍 Analyzing...',
  flowSteps: steps,
  cost: 2.5
})

Using Database Context Routing

import { useGrokStore, DATABASE_CONTEXTS } from '@/store/grok-store'
 
const { setDatabaseContext, databaseContext } = useGrokStore()
 
// Manual context selection
setDatabaseContext('leagues')  // Focus on league data
setDatabaseContext('markets')  // Focus on betting markets
setDatabaseContext('all')      // Let system route intelligently
 
// Get context info
const contextInfo = DATABASE_CONTEXTS[databaseContext]
console.log(contextInfo.endpoint)  // '/api/entities/leagues'

Accessing Conversation Intelligence

import { getConversationInsights } from '@/lib/conversation-intelligence'
 
const intelligence = getConversationInsights(conversation.id)
 
console.log(intelligence.context.topic)           // 'sports'
console.log(intelligence.context.sentiment)       // 'positive'
console.log(intelligence.context.engagement)      // 'high'
console.log(intelligence.suggestions)             // Smart response suggestions
console.log(intelligence.personalization.preferredTopics)

UI Components

Flow Steps Display

import type { FlowStep } from '@/store/chat-store'
 
function FlowStepsDisplay({ steps }: { steps: FlowStep[] }) {
  return (
    <div className="space-y-2">
      {steps.map(step => (
        <div key={step.id} className="border rounded p-2">
          <div className="flex items-center justify-between">
            <span className="font-medium">{step.name}</span>
            <StatusBadge status={step.status} />
          </div>
          {step.agentName && (
            <div className="text-sm text-gray-500">
              Agent: {step.agentName}
            </div>
          )}
          {step.status === 'processing' && step.progress && (
            <ProgressBar progress={step.progress} />
          )}
          {step.durationMs && (
            <div className="text-xs text-gray-400">
              {(step.durationMs / 1000).toFixed(1)}s
            </div>
          )}
        </div>
      ))}
    </div>
  )
}

Intelligence Panel

import { getConversationInsights } from '@/lib/conversation-intelligence'
 
function IntelligencePanel({ conversationId }: { conversationId: string }) {
  const intelligence = getConversationInsights(conversationId)
  
  if (!intelligence) return null
  
  return (
    <div className="p-4 border rounded">
      <h3>Conversation Intelligence</h3>
      <div><strong>Topics:</strong> {intelligence.context.topic}</div>
      <div><strong>Sentiment:</strong> {intelligence.context.sentiment}</div>
      <div><strong>Engagement:</strong> {intelligence.context.engagement}</div>
      <div>
        <strong>Suggestions:</strong>
        <ul>
          {intelligence.suggestions.map((s, i) => (
            <li key={i}>{s.text}</li>
          ))}
        </ul>
      </div>
    </div>
  )
}

State Machine

IDLE → User action → ACTIVE EDIT
ACTIVE EDIT → Error → DIAGNOSTIC MODE
ACTIVE EDIT → Build → TEST MODE
DIAGNOSTIC MODE → Fixed → TEST MODE
TEST MODE → Success → REVIEW MODE
TEST MODE → Failure → DIAGNOSTIC MODE
REVIEW MODE → Approved → REFLECTIVE MODE
REFLECTIVE MODE → Learn → IDLE

Agent Selection Logic

Query Pattern	Agent	Database Context
"Analyze [league]"	LeagueAnalysisAgent	leagues
"Betting on [event]"	BettingAgent	markets
"Fix [code error]"	CodeAgent	internal
"Similar to [entity]"	-	vectordb
"Relationships"	-	neo4j

Pro Tips

Use Projects to Organize

const { createProject, moveToProject } = useChatStore()
 
const projectId = createProject(
  'PLL Research 2025',
  'Comprehensive analysis of Premier Lacrosse League',
  'blue'
)
 
moveToProject(conversationId, projectId)

Track Costs

const { getTotalCost, conversations } = useChatStore()
 
const totalCost = getTotalCost()
const avgCostPerConversation = totalCost / conversations.length

Use Chat-First Actions

import { useChatFirstAction } from '@/hooks/use-chat-first-action'
 
const { executeChatAction } = useChatFirstAction()
 
await executeChatAction({
  userMessage: '🔄 Refresh league data',
  action: async () => await refreshData(),
  steps: [
    { name: 'Connecting', description: 'Connecting to database' },
    { name: 'Syncing', description: 'Downloading data' }
  ],
  successMessage: '✓ Data refreshed!',
  category: 'research',
  cost: 1.0
})

Troubleshooting

Issue	Solution
Conversation not persisting	Ensure `zustand` persistence is enabled with `name: 'chat-storage'`
Intelligence not detecting topics	Add keywords to topic detection in `conversation-intelligence.ts`
Flow steps not updating	Ensure messages are updated, not just steps - trigger Zustand update