Tutorial: Creating Custom Agents | Bootspring Docs

Create your own specialized AI agents that integrate with Bootspring's orchestration system.

What You'll Build#

A custom "code-reviewer" agent
Custom prompts and personas
Integration with Bootspring orchestrator
Agent collaboration patterns

Prerequisites#

Bootspring Pro or higher
Basic understanding of agent concepts
Project with bootspring.config.js

Understanding Custom Agents#

Custom agents allow you to:

Create domain-specific expertise
Define custom prompts and behaviors
Add project-specific knowledge
Extend Bootspring's capabilities

Step 1: Agent Configuration#

Create a custom agent in your Bootspring configuration:

// bootspring.config.js
module.exports = {
  project: {
    name: 'my-saas',
    type: 'web',
    framework: 'nextjs',
  },

  // Custom agents
  agents: {
    custom: [
      {
        name: 'code-reviewer',
        description: 'Reviews code for quality, security, and best practices',
        persona: `You are an expert code reviewer with 15+ years of experience.
You focus on:
- Code quality and maintainability
- Security vulnerabilities
- Performance implications
- Best practices and patterns
- Test coverage gaps

You provide constructive feedback with specific suggestions.`,
        capabilities: [
          'code_review',
          'security_analysis',
          'performance_review',
          'best_practices',
        ],
        defaultContext: [
          'eslintrc',
          'tsconfig',
          'prettier',
        ],
      },
    ],
  },
};

Step 2: Create the Agent Definition#

Create a more detailed agent definition file:

// agents/code-reviewer.ts
export const codeReviewerAgent = {
  name: 'code-reviewer',
  displayName: 'Code Reviewer',
  category: 'quality',

  description: `Expert code reviewer that analyzes code for quality,
security vulnerabilities, performance issues, and adherence to best practices.`,

  persona: `You are a senior software engineer with extensive experience in
code review. You've worked at top tech companies and have developed a keen
eye for code quality.

Your review style is:
- **Constructive**: Always offer solutions, not just criticism
- **Prioritized**: Focus on high-impact issues first
- **Educational**: Explain the "why" behind suggestions
- **Pragmatic**: Balance perfection with shipping

You categorize feedback as:
- 🚨 CRITICAL: Must fix before merge (security, bugs)
- ⚠️ IMPORTANT: Should fix (performance, maintainability)
- 💡 SUGGESTION: Nice to have (style, minor improvements)
- ✅ GOOD: Positive feedback on well-written code`,

  systemPrompt: `When reviewing code, follow this structure:

## Summary
Brief overview of the changes and overall assessment.

## Critical Issues 🚨
Security vulnerabilities, bugs, or breaking changes.

## Important Improvements ⚠️
Performance issues, maintainability concerns.

## Suggestions 💡
Style improvements, alternative approaches.

## What's Good ✅
Highlight well-written code to reinforce good practices.

## Test Coverage
Assessment of test coverage for the changes.

Always provide specific line references and code examples for fixes.`,

  capabilities: [
    'analyze_code_quality',
    'identify_security_issues',
    'suggest_performance_improvements',
    'check_test_coverage',
    'verify_best_practices',
  ],

  tools: [
    'file_read',
    'file_search',
    'git_diff',
    'eslint_check',
  ],

  contextSources: [
    {
      type: 'file',
      pattern: '.eslintrc*',
      description: 'ESLint configuration',
    },
    {
      type: 'file',
      pattern: 'tsconfig.json',
      description: 'TypeScript configuration',
    },
    {
      type: 'file',
      pattern: '.prettierrc*',
      description: 'Prettier configuration',
    },
    {
      type: 'directory',
      pattern: '__tests__/**',
      description: 'Test files',
    },
  ],

  examplePrompts: [
    'Review the changes in the last commit',
    'Review app/api/users/route.ts for security issues',
    'Check if the authentication changes are secure',
    'Review the database queries for performance',
  ],

  collaborators: [
    'security-expert',
    'testing-expert',
    'performance-expert',
  ],
};

Step 3: Register the Agent#

// agents/index.ts
import { codeReviewerAgent } from './code-reviewer';

export const customAgents = [
  codeReviewerAgent,
];

// Register with Bootspring
export function registerCustomAgents() {
  return customAgents.map(agent => ({
    ...agent,
    invoke: createAgentInvoker(agent),
  }));
}

function createAgentInvoker(agent: typeof codeReviewerAgent) {
  return async (prompt: string, context?: any) => {
    // Build the full prompt with persona and system instructions
    const fullPrompt = `
${agent.persona}

${agent.systemPrompt}

---

User Request: ${prompt}
`;

    // Return the structured prompt for the orchestrator
    return {
      agent: agent.name,
      prompt: fullPrompt,
      context: {
        ...context,
        capabilities: agent.capabilities,
        tools: agent.tools,
      },
    };
  };
}

Step 4: Use the Custom Agent#

Via CLI#

# Invoke the custom agent
bootspring agent invoke code-reviewer "Review the changes in my last commit"

# Review specific files
bootspring agent invoke code-reviewer "Review app/api/auth/route.ts"

Via MCP#

In Claude or your AI assistant:

Use the code-reviewer agent to review the authentication changes

Programmatically#

// lib/review.ts
import { invokeAgent } from '@/lib/bootspring';

export async function reviewPullRequest(prNumber: number) {
  const diff = await getPRDiff(prNumber);

  const review = await invokeAgent('code-reviewer', {
    prompt: `Review this pull request:

## Changed Files
${diff.files.map(f => `- ${f.path}`).join('\n')}

## Diff
${diff.patch}

Focus on security and breaking changes.`,
    context: {
      prNumber,
      author: diff.author,
      baseBranch: diff.base,
    },
  });

  return review;
}

Step 5: Create Specialized Variants#

Create variants for specific use cases:

// bootspring.config.js
module.exports = {
  agents: {
    custom: [
      // Base code reviewer
      {
        name: 'code-reviewer',
        description: 'General code review',
        // ... base config
      },

      // Security-focused variant
      {
        name: 'security-reviewer',
        extends: 'code-reviewer',
        description: 'Security-focused code review',
        persona: `You are a security expert who reviews code for vulnerabilities.
You specialize in:
- OWASP Top 10 vulnerabilities
- Authentication/authorization flaws
- Input validation issues
- Cryptography problems
- Injection attacks

You are thorough and paranoid about security.`,
        capabilities: [
          'security_analysis',
          'vulnerability_detection',
          'auth_review',
          'input_validation_check',
        ],
      },

      // Performance-focused variant
      {
        name: 'performance-reviewer',
        extends: 'code-reviewer',
        description: 'Performance-focused code review',
        persona: `You are a performance engineer who reviews code for efficiency.
You focus on:
- Algorithm complexity (Big O)
- Database query efficiency
- Memory usage
- Bundle size impact
- Caching opportunities

You think about scale and production impact.`,
        capabilities: [
          'performance_analysis',
          'query_optimization',
          'bundle_analysis',
          'caching_recommendations',
        ],
      },
    ],
  },
};

Step 6: Agent Collaboration#

Configure how your custom agent collaborates with others:

// agents/code-reviewer.ts
export const codeReviewerAgent = {
  // ... previous config

  collaboration: {
    // Automatic handoffs based on findings
    handoffs: [
      {
        condition: 'security_issue_found',
        agent: 'security-expert',
        prompt: 'Deep dive into this security issue: {issue}',
      },
      {
        condition: 'performance_issue_found',
        agent: 'performance-expert',
        prompt: 'Analyze this performance concern: {issue}',
      },
      {
        condition: 'test_coverage_low',
        agent: 'testing-expert',
        prompt: 'Suggest tests for: {uncovered_code}',
      },
    ],

    // Consultation for specific topics
    consultations: [
      {
        topic: 'database',
        agent: 'database-expert',
      },
      {
        topic: 'api_design',
        agent: 'api-expert',
      },
    ],
  },
};

Step 7: Add Custom Tools#

Create custom tools for your agent:

// agents/tools/git-diff.ts
export const gitDiffTool = {
  name: 'git_diff',
  description: 'Get git diff for specified commits or files',

  parameters: {
    type: 'object',
    properties: {
      ref: {
        type: 'string',
        description: 'Git reference (commit, branch, or HEAD~n)',
        default: 'HEAD~1',
      },
      files: {
        type: 'array',
        items: { type: 'string' },
        description: 'Specific files to diff',
      },
      context: {
        type: 'number',
        description: 'Lines of context around changes',
        default: 3,
      },
    },
  },

  execute: async (params: {
    ref?: string;
    files?: string[];
    context?: number;
  }) => {
    const { ref = 'HEAD~1', files = [], context = 3 } = params;
    const { execSync } = require('child_process');

    const fileArgs = files.length > 0 ? `-- ${files.join(' ')}` : '';
    const command = `git diff -U${context} ${ref} ${fileArgs}`;

    try {
      const diff = execSync(command, { encoding: 'utf-8' });
      return {
        success: true,
        diff,
        summary: parseDiffSummary(diff),
      };
    } catch (error) {
      return {
        success: false,
        error: error.message,
      };
    }
  },
};

function parseDiffSummary(diff: string) {
  const files = diff.match(/diff --git a\/(.+) b\/.+/g) || [];
  const additions = (diff.match(/^\+[^+]/gm) || []).length;
  const deletions = (diff.match(/^-[^-]/gm) || []).length;

  return {
    filesChanged: files.length,
    additions,
    deletions,
  };
}

// agents/code-reviewer.ts
import { gitDiffTool } from './tools/git-diff';

export const codeReviewerAgent = {
  // ... previous config

  customTools: [
    gitDiffTool,
  ],
};

Step 8: Add Context Providers#

Create custom context providers:

// agents/context/eslint-issues.ts
export const eslintIssuesProvider = {
  name: 'eslint_issues',
  description: 'Current ESLint issues in the project',

  provide: async (options: { files?: string[] }) => {
    const { execSync } = require('child_process');
    const { files = ['.'] } = options;

    try {
      const result = execSync(
        `npx eslint ${files.join(' ')} --format json`,
        { encoding: 'utf-8' }
      );

      const issues = JSON.parse(result);

      return {
        totalIssues: issues.reduce(
          (acc: number, file: any) => acc + file.errorCount + file.warningCount,
          0
        ),
        errors: issues.reduce(
          (acc: number, file: any) => acc + file.errorCount,
          0
        ),
        warnings: issues.reduce(
          (acc: number, file: any) => acc + file.warningCount,
          0
        ),
        byFile: issues.map((file: any) => ({
          path: file.filePath,
          errors: file.errorCount,
          warnings: file.warningCount,
          messages: file.messages.slice(0, 5), // Top 5 issues
        })),
      };
    } catch (error) {
      return {
        error: 'Failed to run ESLint',
        details: error.message,
      };
    }
  },
};

Step 9: Test Your Agent#

Create tests for your custom agent:

// __tests__/agents/code-reviewer.test.ts
import { describe, it, expect } from 'vitest';
import { codeReviewerAgent } from '@/agents/code-reviewer';

describe('Code Reviewer Agent', () => {
  it('has required configuration', () => {
    expect(codeReviewerAgent.name).toBe('code-reviewer');
    expect(codeReviewerAgent.persona).toBeDefined();
    expect(codeReviewerAgent.capabilities).toContain('code_review');
  });

  it('generates proper system prompt', () => {
    expect(codeReviewerAgent.systemPrompt).toContain('Summary');
    expect(codeReviewerAgent.systemPrompt).toContain('Critical Issues');
  });

  it('has valid context sources', () => {
    const sources = codeReviewerAgent.contextSources;
    expect(sources.some(s => s.pattern.includes('eslint'))).toBe(true);
    expect(sources.some(s => s.pattern.includes('tsconfig'))).toBe(true);
  });

  it('lists collaborators', () => {
    expect(codeReviewerAgent.collaborators).toContain('security-expert');
  });
});

Step 10: Document Your Agent#

Create documentation for your custom agent:

<!-- docs/agents/code-reviewer.md -->
# Code Reviewer Agent

Custom agent for automated code review.

## Capabilities

- **Code Quality Analysis**: Reviews code for maintainability and readability
- **Security Review**: Identifies potential security vulnerabilities
- **Performance Review**: Spots performance anti-patterns
- **Test Coverage**: Checks for adequate test coverage

## Usage

### Basic Review

```bash
bootspring agent invoke code-reviewer "Review app/api/users/route.ts"

PR Review#

bootspring agent invoke code-reviewer "Review the changes in PR #123"

Security Focus#

bootspring agent invoke security-reviewer "Review authentication changes"

Example Output#

## Summary
This PR adds user authentication with Clerk. Overall good implementation
with a few security considerations.

## Critical Issues 🚨

### 1. Missing CSRF Protection
**File**: `app/api/auth/callback/route.ts:15`

The callback endpoint doesn't verify the state parameter...

## Important Improvements ⚠️

### 1. Rate Limiting
**File**: `app/api/auth/login/route.ts`

Consider adding rate limiting to prevent brute force...

## What's Good ✅

- Clean separation of concerns
- Proper error handling
- Good TypeScript types

Collaboration#

This agent automatically consults:

security-expert for security issues
performance-expert for performance concerns
testing-expert for test coverage gaps


## Verification Checklist

- [ ] Agent configuration added to `bootspring.config.js`
- [ ] Agent definition file created
- [ ] Custom tools implemented (optional)
- [ ] Context providers configured (optional)
- [ ] Agent tests written
- [ ] Documentation created
- [ ] Agent accessible via CLI
- [ ] Collaboration patterns working

## What You Learned

- Creating custom agent configurations
- Defining agent personas and prompts
- Building custom tools
- Configuring context providers
- Setting up agent collaboration
- Testing custom agents

## Next Steps

- [Create domain-specific agents](/docs/tutorials/domain-agents)
- [Build agent workflows](/docs/tutorials/custom-workflows)
- [Integrate with external services](/docs/tutorials/agent-integrations)