Agent System Architecture | Bootspring Docs

How Bootspring's AI expert agents work.

Overview#

The agent system provides specialized AI personas for different development tasks. Each agent has expertise in a specific domain and collaborates with others.

Agent Architecture#

┌─────────────────────────────────────────────────────────────────────┐
│                        AGENT SYSTEM                                 │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐             │
│  │   Agent     │    │   Context   │    │    LLM      │             │
│  │  Registry   │───▶│   Builder   │───▶│  Provider   │             │
│  └─────────────┘    └─────────────┘    └─────────────┘             │
│         │                  │                  │                     │
│         ▼                  ▼                  ▼                     │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐             │
│  │   Profile   │    │   Project   │    │  Response   │             │
│  │   Loader    │    │   Context   │    │  Processor  │             │
│  └─────────────┘    └─────────────┘    └─────────────┘             │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Agent Profile#

Profile Structure#

interface AgentProfile {
  // Identity
  name: string;
  displayName: string;
  description: string;
  avatar?: string;

  // Classification
  category: AgentCategory;
  tier: Tier;
  tags: string[];

  // Behavior
  systemPrompt: string;
  capabilities: string[];
  limitations: string[];

  // Collaboration
  collaborates: string[];
  delegates: DelegationRule[];

  // Configuration
  model?: string;
  temperature?: number;
  maxTokens?: number;

  // Extensions
  tools?: Tool[];
  examples?: Example[];
}

type AgentCategory =
  | 'development'
  | 'quality'
  | 'architecture'
  | 'business'
  | 'design';

type Tier = 'free' | 'pro' | 'team' | 'enterprise';

Example Profile#

# agents/frontend-expert.yaml

name: frontend-expert
displayName: Frontend Expert
description: Expert in React, Next.js, and modern frontend development

category: development
tier: free
tags: [react, nextjs, typescript, css, tailwind]

systemPrompt: |
  You are a senior frontend developer with deep expertise in:
  - React 18+ with Server Components
  - Next.js 14+ App Router
  - TypeScript best practices
  - Tailwind CSS and modern styling
  - Performance optimization
  - Accessibility (WCAG 2.1)

  When helping users:
  1. Prefer Server Components when possible
  2. Use TypeScript with strict mode
  3. Follow React best practices (hooks, composition)
  4. Consider performance and accessibility
  5. Provide complete, working code examples

capabilities:
  - React component development
  - Next.js App Router patterns
  - Tailwind CSS styling
  - Form handling and validation
  - State management
  - API integration
  - Performance optimization
  - Accessibility implementation

limitations:
  - Backend/database design (delegate to backend-expert)
  - Infrastructure/DevOps (delegate to devops-expert)
  - Security audits (delegate to security-expert)

collaborates:
  - ui-ux-expert
  - testing-expert
  - performance-expert
  - backend-expert

delegates:
  - pattern: "database|schema|prisma"
    to: database-expert
  - pattern: "api|endpoint|route"
    to: api-expert
  - pattern: "security|auth|permission"
    to: security-expert

examples:
  - prompt: "Create a data table component"
    response: |
      Here's a reusable data table component...

Agent Registry#

Registry Implementation#

// core/agents/registry.ts

export class AgentRegistry {
  private agents: Map<string, AgentProfile> = new Map();
  private categories: Map<AgentCategory, string[]> = new Map();

  async loadAll(agentsPath: string): Promise<void> {
    const files = await glob('*.yaml', { cwd: agentsPath });

    for (const file of files) {
      const content = await readFile(join(agentsPath, file), 'utf-8');
      const profile = parseYaml<AgentProfile>(content);

      this.register(profile);
    }
  }

  register(profile: AgentProfile): void {
    // Validate profile
    this.validate(profile);

    // Store in registry
    this.agents.set(profile.name, profile);

    // Index by category
    const categoryAgents = this.categories.get(profile.category) || [];
    categoryAgents.push(profile.name);
    this.categories.set(profile.category, categoryAgents);
  }

  get(name: string): AgentProfile | undefined {
    return this.agents.get(name);
  }

  list(filter?: AgentFilter): AgentProfile[] {
    let results = Array.from(this.agents.values());

    if (filter?.category) {
      results = results.filter(a => a.category === filter.category);
    }
    if (filter?.tier) {
      results = results.filter(a => TIER_ORDER[a.tier] <= TIER_ORDER[filter.tier!]);
    }
    if (filter?.tags) {
      results = results.filter(a =>
        filter.tags!.some(t => a.tags.includes(t))
      );
    }

    return results;
  }
}

Agent Invocation#

Invoker Implementation#

// core/agents/invoker.ts

export class AgentInvoker {
  private registry: AgentRegistry;
  private contextBuilder: ContextBuilder;
  private llmProvider: LLMProvider;
  private entitlements: EntitlementChecker;

  async invoke(
    agentName: string,
    prompt: string,
    options: InvokeOptions = {}
  ): Promise<AgentResponse> {
    // 1. Load agent profile
    const agent = this.registry.get(agentName);
    if (!agent) {
      throw new AgentNotFoundError(agentName);
    }

    // 2. Check entitlements
    await this.checkEntitlements(agent, options.userId);

    // 3. Build context
    const context = await this.buildContext(agent, options);

    // 4. Prepare messages
    const messages = this.prepareMessages(agent, prompt, context);

    // 5. Invoke LLM
    const startTime = Date.now();
    const response = await this.llmProvider.complete(messages, {
      model: agent.model || 'claude-3-5-sonnet',
      temperature: agent.temperature ?? 0.7,
      maxTokens: options.maxTokens || agent.maxTokens || 4096,
    });

    // 6. Process response
    const processed = await this.processResponse(response, agent);

    // 7. Track usage
    await this.trackUsage({
      agent: agentName,
      duration: Date.now() - startTime,
      tokens: response.usage,
      userId: options.userId,
    });

    return processed;
  }

  private async buildContext(
    agent: AgentProfile,
    options: InvokeOptions
  ): Promise<InvocationContext> {
    const context: InvocationContext = {
      agent: {
        name: agent.name,
        capabilities: agent.capabilities,
      },
    };

    // Add project context
    if (options.projectId) {
      context.project = await this.contextBuilder.getProjectContext(
        options.projectId
      );
    }

    // Add file context
    if (options.files?.length) {
      context.files = await this.contextBuilder.getFileContents(
        options.files
      );
    }

    // Add conversation history
    if (options.history?.length) {
      context.history = options.history;
    }

    return context;
  }

  private prepareMessages(
    agent: AgentProfile,
    prompt: string,
    context: InvocationContext
  ): Message[] {
    const messages: Message[] = [];

    // System message with agent persona
    messages.push({
      role: 'system',
      content: this.buildSystemPrompt(agent, context),
    });

    // Add history if present
    if (context.history) {
      messages.push(...context.history);
    }

    // User prompt
    messages.push({
      role: 'user',
      content: this.buildUserPrompt(prompt, context),
    });

    return messages;
  }
}

Context Building#

Context Builder#

// core/agents/context-builder.ts

export class ContextBuilder {
  async build(options: ContextOptions): Promise<string> {
    const sections: string[] = [];

    // Agent context
    sections.push(this.formatAgentContext(options.agent));

    // Project context
    if (options.project) {
      sections.push(await this.formatProjectContext(options.project));
    }

    // File contents
    if (options.files?.length) {
      sections.push(await this.formatFileContents(options.files));
    }

    // Custom context
    if (options.custom) {
      sections.push(options.custom);
    }

    return sections.join('\n\n---\n\n');
  }

  private formatAgentContext(agent: AgentProfile): string {
    return `
## Agent: ${agent.displayName}

**Capabilities:**
${agent.capabilities.map(c => `- ${c}`).join('\n')}

**Collaboration:**
When appropriate, suggest involving:
${agent.collaborates.map(c => `- ${c}`).join('\n')}
    `.trim();
  }

  private async formatProjectContext(projectId: string): Promise<string> {
    const context = await this.loadProjectContext(projectId);

    return `
## Project Context

${context.summary}

**Tech Stack:** ${context.stack.join(', ')}
**Key Files:**
${context.keyFiles.map(f => `- ${f.path}: ${f.description}`).join('\n')}
    `.trim();
  }
}

Agent Collaboration#

Delegation System#

// core/agents/delegation.ts

export class DelegationManager {
  private registry: AgentRegistry;

  shouldDelegate(
    agent: AgentProfile,
    prompt: string
  ): DelegationSuggestion | null {
    for (const rule of agent.delegates || []) {
      const regex = new RegExp(rule.pattern, 'i');

      if (regex.test(prompt)) {
        const targetAgent = this.registry.get(rule.to);

        if (targetAgent) {
          return {
            from: agent.name,
            to: rule.to,
            reason: `This task involves ${rule.pattern}, which is better handled by ${targetAgent.displayName}`,
            confidence: this.calculateConfidence(prompt, rule),
          };
        }
      }
    }

    return null;
  }

  suggestCollaborators(
    agent: AgentProfile,
    prompt: string
  ): CollaborationSuggestion[] {
    const suggestions: CollaborationSuggestion[] = [];

    for (const collaborator of agent.collaborates) {
      const collaboratorProfile = this.registry.get(collaborator);

      if (collaboratorProfile && this.isRelevant(prompt, collaboratorProfile)) {
        suggestions.push({
          agent: collaborator,
          reason: `${collaboratorProfile.displayName} could help with ${this.getRelevantCapability(prompt, collaboratorProfile)}`,
        });
      }
    }

    return suggestions;
  }
}

Multi-Agent Workflows#

// core/agents/orchestration.ts

export class MultiAgentOrchestrator {
  async orchestrate(
    task: Task,
    agents: string[]
  ): Promise<OrchestrationResult> {
    const results: AgentResult[] = [];

    for (const agentName of agents) {
      // Get previous results as context
      const previousContext = this.formatPreviousResults(results);

      // Invoke agent with context
      const result = await this.invoker.invoke(agentName, task.prompt, {
        context: previousContext,
        task: task.id,
      });

      results.push({
        agent: agentName,
        response: result,
      });

      // Check if task is complete
      if (this.isTaskComplete(task, results)) {
        break;
      }
    }

    return {
      task: task.id,
      agents: results.map(r => r.agent),
      finalResponse: this.synthesizeResults(results),
    };
  }
}

Response Processing#

Processor Implementation#

// core/agents/processor.ts

export class ResponseProcessor {
  process(response: LLMResponse, agent: AgentProfile): AgentResponse {
    const content = response.content;

    return {
      id: generateId(),
      agent: agent.name,
      content: content,
      type: this.detectResponseType(content),
      codeBlocks: this.extractCodeBlocks(content),
      suggestions: this.extractSuggestions(content, agent),
      usage: response.usage,
      timestamp: new Date(),
    };
  }

  private detectResponseType(content: string): ResponseType {
    if (content.includes('```')) return 'code';
    if (content.includes('##')) return 'documentation';
    if (content.includes('- [ ]')) return 'checklist';
    return 'text';
  }

  private extractCodeBlocks(content: string): CodeBlock[] {
    const regex = /```(\w+)?\n([\s\S]*?)```/g;
    const blocks: CodeBlock[] = [];
    let match;

    while ((match = regex.exec(content)) !== null) {
      blocks.push({
        language: match[1] || 'text',
        code: match[2].trim(),
      });
    }

    return blocks;
  }
}

Agent Categories#

Development Agents#

Agent	Expertise
`frontend-expert`	React, Next.js, CSS
`backend-expert`	APIs, servers, logic
`database-expert`	Schemas, queries, optimization
`api-expert`	REST, GraphQL, design
`mobile-expert`	React Native, iOS, Android

Quality Agents#

Agent	Expertise
`testing-expert`	Unit, integration, E2E
`security-expert`	Auth, vulnerabilities, compliance
`performance-expert`	Optimization, profiling
`code-review-expert`	Best practices, patterns

Architecture Agents#

Agent	Expertise
`architecture-expert`	System design, patterns
`devops-expert`	CI/CD, infrastructure
`cloud-expert`	AWS, GCP, Azure

Business Agents#

Agent	Expertise
`business-strategy-expert`	Strategy, planning
`fundraising-expert`	Investors, pitching
`growth-expert`	Metrics, acquisition