Specialized Agents - Automagik Suite Documentation

Overview

Specialized agents are custom configurations that modify how any base AI agent behaves. Apply “personas” like “security expert” or “test writer” to any LLM for task-specific optimization.

Key Concept: Specialized agents are prompts + configurations, not separate models. They work with ANY base LLM!

How They Work

Base Agent (Claude) + Specialized Profile (Security Expert) = Secure Code Focus
Base Agent (Gemini) + Specialized Profile (Test Writer) = Comprehensive Tests
Base Agent (GPT-4) + Specialized Profile (Performance) = Optimized Code

Built-in Specialized Agents

Security Expert

Focus on security best practices and vulnerability prevention.

forge task create \
  --title "Add file upload" \
  --llm claude \
  --agent security-expert

Behaviors:

Always validates input
Considers injection attacks
Implements proper sanitization
Adds rate limiting
Includes security headers
Documents security decisions

Best for: Auth systems, API endpoints, data handling

Test Writer

Comprehensive test coverage with edge cases.

forge task create \
  --title "Add authentication" \
  --llm gemini \
  --agent test-writer

Behaviors:

Writes tests first (TDD)
Covers edge cases
Tests error handling
Adds integration tests
Achieves 90%+ coverage
Documents test scenarios

Best for: New features, refactoring, bug fixes

Performance Optimizer

Optimize for speed and efficiency.

forge task create \
  --title "Speed up API" \
  --llm claude \
  --agent performance-optimizer

Behaviors:

Profiles bottlenecks
Adds caching
Optimizes queries
Reduces allocations
Implements lazy loading
Measures improvements

Best for: Slow endpoints, database queries, large datasets

Documentation Writer

Clear, comprehensive documentation.

forge task create \
  --title "Document API" \
  --llm openai \
  --agent docs-writer

Behaviors:

Writes clear JSDoc/docstrings
Includes usage examples
Explains edge cases
Creates README sections
Adds inline comments
Documents assumptions

Best for: Public APIs, complex logic, team projects

Code Reviewer

Thorough code review with suggestions.

forge task create \
  --title "Review authentication PR" \
  --llm claude \
  --agent code-reviewer

Behaviors:

Checks code style
Identifies bugs
Suggests improvements
Reviews tests
Validates architecture
Provides constructive feedback

Best for: PR reviews, code audits, refactoring validation

Accessibility Expert

WCAG-compliant accessible interfaces.

forge task create \
  --title "Build form component" \
  --llm cursor \
  --agent accessibility-expert

Behaviors:

Adds ARIA labels
Ensures keyboard navigation
Proper focus management
Screen reader support
Color contrast compliance
Semantic HTML

Best for: UI components, forms, interactive features

Creating Custom Agents

Configuration File

Create .forge/agents.yaml:

agents:
  # Custom agent for your team's style
  team-style:
    name: "Team Style Enforcer"
    description: "Enforces our coding standards"
    systemPrompt: |
      You are a code generator following our team's style guide:
      - Use TypeScript with strict mode
      - Prefer functional programming
      - Use async/await, never callbacks
      - Write tests with Jest
      - Follow our naming conventions: PascalCase for components, camelCase for functions
      - Always add JSDoc comments

    temperature: 0.3  # Less creative, more consistent
    examples:
      - input: "Create user component"
        output: |
          /**
           * User profile component
           * @param {UserProps} props - Component props
           */
          export const UserProfile: React.FC<UserProps> = ({ user }) => {
            // Implementation following team style
          }

  # Database expert
  database-expert:
    name: "Database Optimization Expert"
    systemPrompt: |
      You are a database optimization expert. For every query:
      - Consider indexing strategies
      - Avoid N+1 problems
      - Use prepared statements
      - Optimize JOIN operations
      - Add query performance comments
      - Include EXPLAIN plans in comments

    focusAreas:
      - "Query optimization"
      - "Index design"
      - "Transaction management"

  # API designer
  api-designer:
    name: "RESTful API Designer"
    systemPrompt: |
      You design clean, RESTful APIs following best practices:
      - Use proper HTTP methods (GET, POST, PUT, PATCH, DELETE)
      - Design resource-oriented URLs
      - Version APIs (v1, v2)
      - Include pagination for lists
      - Implement proper error responses
      - Add request/response examples
      - Follow OpenAPI spec

    guidelines:
      - "REST principles"
      - "HTTP status codes"
      - "API versioning"

Using Custom Agents

# Use your custom agent
forge task create \
  --title "Add user endpoint" \
  --llm claude \
  --agent team-style

# Load from file
forge task create \
  --title "Optimize queries" \
  --llm gemini \
  --agent database-expert \
  --agent-config .forge/agents.yaml

Agent Combinations

Apply multiple agents to same task:

# Security + Testing
forge task create \
  --title "Add payment processing" \
  --llm claude \
  --agents security-expert,test-writer

# Performance + Documentation
forge task create \
  --title "Optimize search" \
  --llm gemini \
  --agents performance-optimizer,docs-writer

Result: Code that’s secure, well-tested, AND fast!

Agent Templates

Frontend Component Agent

frontend-component:
  name: "React Component Expert"
  systemPrompt: |
    Create React components following best practices:
    - Use TypeScript with proper types
    - Implement proper prop validation
    - Add accessibility (ARIA)
    - Make components responsive
    - Add loading and error states
    - Include Storybook stories
    - Write comprehensive tests

  preferredPatterns:
    - "Functional components with hooks"
    - "Composition over inheritance"
    - "Single responsibility"

Backend API Agent

backend-api:
  name: "Backend API Expert"
  systemPrompt: |
    Create backend APIs with:
    - Proper error handling
    - Input validation
    - Request logging
    - Authentication middleware
    - Rate limiting
    - API documentation (OpenAPI)
    - Integration tests

  frameworks:
    - "Express.js"
    - "Fastify"

  patterns:
    - "Controller-Service-Repository"
    - "Dependency injection"

Infrastructure Agent

infrastructure:
  name: "Infrastructure as Code Expert"
  systemPrompt: |
    Create infrastructure code following best practices:
    - Modular and reusable
    - Environment-specific configs
    - Secrets management
    - Resource tagging
    - Cost optimization
    - Disaster recovery

  tools:
    - "Terraform"
    - "Docker"
    - "Kubernetes"

SDK Usage

JavaScript/TypeScript

import { ForgeClient } from '@automagik/forge-sdk';

const forge = new ForgeClient();

// Use built-in agent
await forge.tasks.create({
  title: 'Add authentication',
  llm: 'claude',
  agent: 'security-expert'
});

// Use custom agent
await forge.tasks.create({
  title: 'Add component',
  llm: 'cursor',
  agent: 'frontend-component',
  agentConfig: './forge/agents.yaml'
});

// Multiple agents
await forge.tasks.create({
  title: 'Critical feature',
  llm: 'claude',
  agents: ['security-expert', 'test-writer', 'docs-writer']
});

Best Practices

Match Agent to Task

# Security-critical → security-expert
forge task create "Add auth" \
  --agent security-expert

# Public API → docs-writer
forge task create "Document API" \
  --agent docs-writer

Combine Strategically

Don’t use all agents at once:Good: security-expert + test-writer Bad: All 8 agents (conflicting priorities)

Create Team Agents

Codify your team’s style:

team-standard:
  systemPrompt: |
    Follow our team's standards:
    - [Your specific rules]

Iterate and Refine

Test agent configs:

# Try different temperatures
# Adjust system prompts
# Add examples
# Measure results

Agent Configuration Options

Temperature

Controls creativity vs consistency:

agents:
  consistent-coder:
    temperature: 0.3  # Very consistent

  creative-designer:
    temperature: 0.9  # More creative

Max Tokens

Control response length:

agents:
  concise:
    maxTokens: 1024  # Short responses

  comprehensive:
    maxTokens: 8192  # Detailed responses

Examples

Provide examples for better results:

agents:
  our-style:
    examples:
      - input: "Create function to add numbers"
        output: |
          /**
           * Adds two numbers together
           * @param a First number
           * @param b Second number
           * @returns Sum of a and b
           */
          export const add = (a: number, b: number): number => {
            return a + b;
          };

Measuring Agent Effectiveness

Track which agents work best:

# Generate report
forge agent-stats --month january

# Output:
# Agent              Tasks  Success  Avg Cost
# security-expert    12     100%     $0.28
# test-writer        18     94%      $0.19
# performance        8      88%      $0.31
# docs-writer        15     100%     $0.15

Troubleshooting

Agent not applying

Issue: Agent behavior not visibleSolutions:

Check agent config is loaded
Verify agent name matches
Inspect system prompt in logs
Try more explicit instructions

Conflicting agents

Issue: Multiple agents conflictSolution: Limit to 2-3 compatible agents:Good: security + testing Bad: performance + comprehensive-docs (conflicting goals)

Agent too strict

Issue: Agent over-optimizes for one aspectSolution: Adjust temperature or prompt:

agents:
  balanced-security:
    temperature: 0.7  # More flexible
    systemPrompt: "Consider security but balance with readability"

Real-World Examples

Example 1: Secure Payment Processing

forge task create \
  --title "Implement Stripe payment" \
  --description "
  Add Stripe payment processing:
  - Webhook handler
  - Payment intent creation
  - Subscription management
  " \
  --llm claude \
  --agents security-expert,test-writer

Result:

Input validation on all endpoints
Webhook signature verification
Idempotency keys
Error handling
Comprehensive tests (95% coverage)
Security documentation

Example 2: Public API

forge task create \
  --title "Create REST API" \
  --llm openai \
  --agents api-designer,docs-writer

Result:

RESTful URL design
Proper HTTP methods
OpenAPI specification
Request/response examples
Error documentation
Rate limiting docs

Next Steps

Task Templates

Reusable task patterns

Parallel Execution

Run multiple agents simultaneously

AI Agents Overview

Learn about base AI agents

Workflows

Complete development workflows

​Overview

​How They Work

​Built-in Specialized Agents

​Security Expert

​Test Writer

​Performance Optimizer

​Documentation Writer

​Code Reviewer

​Accessibility Expert

​Creating Custom Agents

​Configuration File

​Using Custom Agents

​Agent Combinations

​Agent Templates

​Frontend Component Agent

​Backend API Agent

​Infrastructure Agent

​SDK Usage

​JavaScript/TypeScript

​Best Practices

Match Agent to Task

Combine Strategically

Create Team Agents

Iterate and Refine

​Agent Configuration Options

​Temperature

​Max Tokens

​Examples

​Measuring Agent Effectiveness

​Troubleshooting

​Real-World Examples

​Example 1: Secure Payment Processing

​Example 2: Public API

​Next Steps

Task Templates

Parallel Execution

AI Agents Overview

Workflows

Overview

How They Work

Built-in Specialized Agents

Security Expert

Test Writer

Performance Optimizer

Documentation Writer

Code Reviewer

Accessibility Expert

Creating Custom Agents

Configuration File

Using Custom Agents

Agent Combinations

Agent Templates

Frontend Component Agent

Backend API Agent

Infrastructure Agent

SDK Usage

JavaScript/TypeScript

Best Practices

Agent Configuration Options

Temperature

Max Tokens

Examples

Measuring Agent Effectiveness

Troubleshooting

Real-World Examples

Example 1: Secure Payment Processing

Example 2: Public API

Next Steps