Eve library

Multi-Agent Architecture Guide

Guide

Revision 1

On this page

This guide covers the multi-agent system architecture for autonomous content generation and task orchestration.

Overview#

The platform uses a multi-agent architecture where specialized agents collaborate to accomplish complex tasks. This enables:

  • Autonomous Operation: Agents work independently with minimal supervision
  • Specialization: Each agent excels at specific tasks
  • Collaboration: Agents coordinate through workflows
  • Scalability: Add new agents without changing existing code
  • Reliability: Built-in error handling and recovery

Architecture Components#

text
┌─────────────────────────────────────────────────────────────────┐
│                    Multi-Agent System                            │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ ContentAgent │  │ SessionAgent │  │AnalyticsAgent│  ...     │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘          │
│         │                 │                 │                   │
│         └────────────────┬┴─────────────────┘                   │
│                          │                                      │
│               ┌──────────▼──────────┐                          │
│               │  Agent Coordinator  │                          │
│               └──────────┬──────────┘                          │
│                          │                                      │
│               ┌──────────▼──────────┐                          │
│               │   Workflow Engine   │                          │
│               └──────────┬──────────┘                          │
│                          │                                      │
│               ┌──────────▼──────────┐                          │
│               │   Agent Executor    │                          │
│               └─────────────────────┘                          │
└─────────────────────────────────────────────────────────────────┘

Core Agents#

System Agents#

Agent Capabilities Purpose
ContentAgent content-creation, content-discovery, content-organization Generate and manage content
SessionAgent session-management, progress-tracking Manage user sessions
AnalyticsAgent analytics, user-analysis Analyze user behavior
RecommendationAgent recommendation-engine, learning-path-design Personalize content
QualityAgent quality-assurance, validation, verification Ensure content quality
VersionControlAgent version-control Manage content versions
ErrorHandlingAgent error-handling Handle failures gracefully

Domain Agents#

Agent Role Expertise
Librarian Knowledge discovery Cataloging, information retrieval
Curator Content curation Selection, organization
Scholar Research Academic analysis, citations
SocraticCoach Teaching Dialogue, questioning
PersonaEngine Character creation Voice, personality
SafetyModerator Content safety Filtering, moderation
Narrator Storytelling Narrative, pacing

Academic Research Agents#

Agent Specialization
Historian Historical analysis
Theologian Religious studies
Philosopher Philosophical inquiry
Linguist Language analysis
Indologist Hindu/Buddhist traditions
IslamicStudies Islamic traditions
Sinologist Chinese traditions
Classicist Greek/Roman traditions
Mysticism Mystical traditions

Agent Configuration#

Basic Agent Structure#

typescript
interface AgentConfig {
  name: string;
  capabilities: string[];
  autonomyLevel: 'full' | 'supervised' | 'restricted';
  status: 'ready' | 'busy' | 'error' | 'offline';
  taskQueue: Task[];
  completedTasks: Task[];
  metrics: {
    tasksCompleted: number;
    successRate: number;
    averageResponseTime: number;
  };
}

Domain Agent Structure#

typescript
interface DomainAgent {
  id: string;
  role: AgentRole;
  name: string;
  description: string;
  capabilities: string[];
  toolAccess: AgentToolAccess[];
  personality: {
    tone: string;      // 'helpful', 'scholarly', 'warm'
    style: string;     // 'precise', 'conversational', 'narrative'
    expertise: string[];
  };
  status: 'idle' | 'busy' | 'error';
  metrics: AgentMetrics;
}

Tool Access Configuration#

typescript
interface AgentToolAccess {
  toolName: ToolCapability;
  permissions: string[];
  rateLimit?: {
    calls: number;
    period: 'minute' | 'hour' | 'day';
  };
}

type ToolCapability =
  | 'search'      // Knowledge search
  | 'kg_query'    // Knowledge graph queries
  | 'calc'        // Calculations
  | 'tts'         // Text-to-speech
  | 'stt'         // Speech-to-text
  | 'scheduler';  // Task scheduling

Workflow System#

Workflow Definition#

typescript
interface Workflow {
  name: string;
  steps: WorkflowStep[];
  status: 'pending' | 'running' | 'completed' | 'failed';
  startTime: number;
  endTime?: number;
  duration?: number;
  results: StepResult[];
}

interface WorkflowStep {
  name: string;
  capabilities: string[];  // Required agent capabilities
  action: string;
  params?: Record<string, unknown>;
  timeout?: number;
  retries?: number;
}

Creating a Workflow#

typescript
const meditationWorkflow: WorkflowStep[] = [
  {
    name: 'plan-structure',
    capabilities: ['content-creation'],
    action: 'plan_meditation_structure',
    params: { tradition: 'buddhist', duration: 600 }
  },
  {
    name: 'write-script',
    capabilities: ['content-creation'],
    action: 'generate_script_content',
    params: { includeAudioTags: true }
  },
  {
    name: 'validate-tradition',
    capabilities: ['quality-assurance', 'validation'],
    action: 'validate_tradition_accuracy',
    params: { minScore: 0.85 }
  },
  {
    name: 'quality-review',
    capabilities: ['quality-assurance'],
    action: 'review_content_quality',
    params: { checkReadability: true }
  }
];

const result = await system.executeWorkflow('meditation-generation', meditationWorkflow);

Workflow Execution#

typescript
class MultiAgentSystem {
  async executeWorkflow(name: string, steps: WorkflowStep[]): Promise<Workflow> {
    const workflow: Workflow = {
      name,
      steps,
      status: 'running',
      startTime: Date.now(),
      results: []
    };

    for (const step of steps) {
      // Select best agent for this step
      const agent = this.selectAgent(step.capabilities);

      if (!agent) {
        throw new Error(`No agent available for: ${step.name}`);
      }

      // Execute step with selected agent
      const result = await this.executeStep(agent, step);
      workflow.results.push(result);

      if (!result.success) {
        workflow.status = 'failed';
        break;
      }
    }

    workflow.status = workflow.status === 'running' ? 'completed' : workflow.status;
    workflow.endTime = Date.now();
    workflow.duration = workflow.endTime - workflow.startTime;

    return workflow;
  }
}

Agent Coordination#

Agent Selection#

typescript
class AgentCoordinator {
  selectAgent(requiredCapabilities: string[]): AgentConfig | null {
    // Find agent with all required capabilities
    for (const [name, agent] of this.agents) {
      if (this.hasCapabilities(agent, requiredCapabilities)) {
        if (agent.status === 'ready') {
          return agent;
        }
      }
    }

    return null;
  }

  private hasCapabilities(agent: AgentConfig, required: string[]): boolean {
    return required.every(cap => agent.capabilities.includes(cap));
  }
}

Load Balancing#

typescript
class AgentCoordinator {
  selectBestAgent(capabilities: string[]): AgentConfig | null {
    const candidates = this.findAgentsWithCapabilities(capabilities);

    if (candidates.length === 0) return null;

    // Sort by availability and performance
    candidates.sort((a, b) => {
      // Prefer ready agents
      if (a.status !== b.status) {
        return a.status === 'ready' ? -1 : 1;
      }

      // Then by success rate
      if (a.metrics.successRate !== b.metrics.successRate) {
        return b.metrics.successRate - a.metrics.successRate;
      }

      // Then by response time
      return a.metrics.averageResponseTime - b.metrics.averageResponseTime;
    });

    return candidates[0];
  }
}

Task Distribution#

typescript
class AgentCoordinator {
  async distributeTask(task: AgentTask): Promise<void> {
    const agent = this.selectBestAgent(task.requiredCapabilities);

    if (!agent) {
      await this.queueTask(task);
      return;
    }

    agent.status = 'busy';
    agent.taskQueue.push(task);

    try {
      const result = await this.executor.execute(agent, task);
      task.result = result;
      task.status = 'completed';
      agent.completedTasks.push(task);
      agent.metrics.tasksCompleted++;
    } catch (error) {
      task.status = 'failed';
      task.error = error.message;
    } finally {
      agent.status = 'ready';
    }
  }
}

Agent Executor#

Task Execution#

typescript
class AgentExecutor {
  private orchestrator: LLMOrchestrator | null = null;

  setOrchestrator(orchestrator: LLMOrchestrator): void {
    this.orchestrator = orchestrator;
  }

  async execute(agent: DomainAgent, task: AgentTask): Promise<TaskExecutionResult> {
    if (!this.orchestrator) {
      return this.simulateExecution(agent, task);
    }

    const prompt = this.buildPrompt(agent, task);
    const response = await this.orchestrator.complete({
      system_prompt: this.buildSystemPrompt(agent),
      user_prompt: prompt,
      temperature: this.getTemperature(task.type)
    });

    return this.parseResponse(response, task);
  }

  private buildSystemPrompt(agent: DomainAgent): string {
    return `You are ${agent.name}, a ${agent.description}.

Your expertise includes: ${agent.personality.expertise.join(', ')}.
Your communication style is ${agent.personality.style} with a ${agent.personality.tone} tone.

Available tools: ${agent.toolAccess.map(t => t.toolName).join(', ')}.`;
  }
}

Tool Execution#

typescript
class AgentExecutor {
  async executeTool(
    agent: DomainAgent,
    tool: ToolCapability,
    params: Record<string, unknown>
  ): Promise<ToolExecutionResult> {
    // Check permissions
    const access = agent.toolAccess.find(t => t.toolName === tool);
    if (!access) {
      throw new Error(`Agent ${agent.name} does not have access to ${tool}`);
    }

    // Check rate limit
    if (access.rateLimit && this.isRateLimited(agent.id, tool)) {
      throw new Error(`Rate limit exceeded for ${tool}`);
    }

    // Execute tool
    const startTime = Date.now();
    const result = await this.tools[tool].execute(params);

    // Record execution
    this.recordToolExecution({
      agentId: agent.id,
      toolName: tool,
      input: params,
      output: result,
      success: true,
      duration: Date.now() - startTime,
      timestamp: new Date()
    });

    return result;
  }
}

Content Generation Pipeline#

Meditation Script Pipeline#

typescript
const meditationPipeline = {
  name: 'meditation-script-generation',
  agents: [
    {
      role: 'architect',
      agent: 'ContentAgent',
      task: 'Plan meditation structure',
      output: 'structure'
    },
    {
      role: 'writer',
      agent: 'ContentAgent',
      task: 'Generate script content',
      input: 'structure',
      output: 'draft'
    },
    {
      role: 'tradition_expert',
      agent: 'Scholar',
      task: 'Validate tradition accuracy',
      input: 'draft',
      output: 'validated'
    },
    {
      role: 'reviewer',
      agent: 'QualityAgent',
      task: 'Quality review',
      input: 'validated',
      output: 'final'
    }
  ]
};

Pipeline Execution#

typescript
class ContentPipeline {
  async execute(request: GenerationRequest): Promise<GenerationResult> {
    let context = { request };

    for (const stage of this.stages) {
      const agent = this.coordinator.getAgent(stage.agent);
      const task = this.createTask(stage, context);

      const result = await this.executor.execute(agent, task);

      if (!result.success) {
        return { success: false, error: result.error };
      }

      context[stage.output] = result.data;

      this.emit('stage-complete', { stage: stage.role, result });
    }

    return { success: true, data: context.final };
  }
}

Error Handling#

Retry Strategy#

typescript
class AgentExecutor {
  async executeWithRetry(
    agent: DomainAgent,
    task: AgentTask,
    maxRetries: number = 3
  ): Promise<TaskExecutionResult> {
    let lastError: Error | null = null;

    for (let attempt = 1; attempt <= maxRetries; attempt++) {
      try {
        return await this.execute(agent, task);
      } catch (error) {
        lastError = error;
        console.warn(`Attempt ${attempt} failed: ${error.message}`);

        if (attempt < maxRetries) {
          await this.delay(Math.pow(2, attempt) * 1000);
        }
      }
    }

    throw lastError;
  }
}

Fallback Agents#

typescript
class AgentCoordinator {
  async executeWithFallback(
    task: AgentTask,
    primaryCapabilities: string[],
    fallbackCapabilities: string[]
  ): Promise<TaskExecutionResult> {
    // Try primary agent
    const primary = this.selectAgent(primaryCapabilities);
    if (primary) {
      try {
        return await this.executor.execute(primary, task);
      } catch {
        console.warn('Primary agent failed, trying fallback');
      }
    }

    // Try fallback agent
    const fallback = this.selectAgent(fallbackCapabilities);
    if (fallback) {
      return await this.executor.execute(fallback, task);
    }

    throw new Error('No agents available for task');
  }
}

Monitoring & Metrics#

Agent Metrics#

typescript
interface AgentMetrics {
  tasksCompleted: number;
  tasksFailed: number;
  successRate: number;
  averageResponseTime: number;
  toolsUsed: number;
  lastActive: Date;
}

class MetricsCollector {
  getAgentMetrics(agentId: string): AgentMetrics {
    const agent = this.registry.getAgent(agentId);
    const tasks = this.getAgentTasks(agentId);

    const completed = tasks.filter(t => t.status === 'completed');
    const failed = tasks.filter(t => t.status === 'failed');

    return {
      tasksCompleted: completed.length,
      tasksFailed: failed.length,
      successRate: completed.length / (completed.length + failed.length),
      averageResponseTime: this.calculateAverageTime(completed),
      toolsUsed: this.countToolUsage(agentId),
      lastActive: agent.lastActive
    };
  }
}

System Health#

typescript
class SystemMonitor {
  getSystemHealth(): SystemHealth {
    const agents = this.registry.getAllAgents();

    return {
      totalAgents: agents.length,
      activeAgents: agents.filter(a => a.status === 'busy').length,
      idleAgents: agents.filter(a => a.status === 'idle').length,
      errorAgents: agents.filter(a => a.status === 'error').length,
      activeWorkflows: this.workflowEngine.getActiveCount(),
      queuedTasks: this.taskQueue.length,
      systemLoad: this.calculateLoad()
    };
  }
}

Best Practices#

1. Define Clear Capabilities#

typescript
// Good: Specific, composable capabilities
capabilities: ['content-creation', 'meditation-scripts', 'audio-tags']

// Avoid: Vague, overlapping capabilities
capabilities: ['general-purpose', 'anything']

2. Use Appropriate Autonomy Levels#

typescript
// Full autonomy for low-risk tasks
{ autonomyLevel: 'full', capabilities: ['content-discovery'] }

// Supervised for quality-critical tasks
{ autonomyLevel: 'supervised', capabilities: ['content-publishing'] }

// Restricted for sensitive operations
{ autonomyLevel: 'restricted', capabilities: ['user-data-access'] }

3. Implement Graceful Degradation#

typescript
async function generateContent(request) {
  try {
    // Try multi-agent pipeline
    return await multiAgentPipeline.execute(request);
  } catch {
    // Fall back to single agent
    return await singleAgentGeneration(request);
  }
}

4. Monitor Agent Performance#

typescript
// Track metrics for optimization
setInterval(() => {
  const metrics = collector.getAllAgentMetrics();

  for (const [agentId, metric] of metrics) {
    if (metric.successRate < 0.8) {
      console.warn(`Agent ${agentId} success rate low: ${metric.successRate}`);
    }
    if (metric.averageResponseTime > 5000) {
      console.warn(`Agent ${agentId} slow: ${metric.averageResponseTime}ms`);
    }
  }
}, 60000);