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 handlingTest 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 fixesOptimize 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 datasetsDocumentation 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 projectsCode 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 validationAccessibility 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 featuresCreating 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
Issue : Agent behavior not visibleSolutions :
Check agent config is loaded
Verify agent name matches
Inspect system prompt in logs
Try more explicit instructions
Issue : Multiple agents conflictSolution : Limit to 2-3 compatible agents:Good : security + testing
Bad : performance + comprehensive-docs (conflicting goals)
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 
