Custom Agents

Create and deploy custom AI agents tailored to your specific needs

Overview

Custom agents in NikCLI allow you to create specialized AI assistants tailored to your specific technologies, workflows, and business requirements. Build agents with domain expertise, custom tool access, and specialized knowledge for your unique use cases.

Agent Factory

Visual agent creation with templates and wizards

Specialized Knowledge

Embed custom knowledge bases and documentation

Custom Tools

Integrate with proprietary tools and services

Team Collaboration

Share and manage agents across your organization

Agent Creation Methods

Visual Agent Factory

Interactive Creation

# Start the agent factory wizard
/factory create --wizard

# Follow interactive prompts:
# 1. Agent name and description
# 2. Base template selection
# 3. Specialization areas
# 4. Tool access configuration
# 5. Knowledge base integration
# 6. Testing and validation

Factory Features:

• Visual drag-and-drop interface
• Pre-built templates and components
• Real-time preview and testing
• Guided configuration wizards
• Performance optimization suggestions
• Deployment automation

Template-Based Creation

# Browse available templates
/factory templates --category development --technology react

# Create from template
/create-agent "React Testing Specialist" 
              --template react-expert-base
              --customize

# Available templates:
# - Frontend specialists (React, Vue, Angular)
# - Backend specialists (Node.js, Python, Go)
# - DevOps specialists (Docker, K8s, AWS)
# - Industry specialists (FinTech, HealthTech, E-commerce)
# - Tool specialists (Testing, Security, Performance)

Code-First Creation

# Create agent from configuration file
/create-agent --from-config custom-agent.yaml

# Clone and modify existing agent
/create-agent "Custom React Expert" 
              --clone react-expert
              --modify-skills "add:storybook,chromatic"
              --modify-context "company-design-system/"

Agent Configuration Schema

Basic Agent Definition

# custom-agent.yaml
agent:
  name: "Custom React Expert"
  version: "1.0.0"
  description: "React specialist with company-specific knowledge"
  
  base:
    template: "react-expert"
    inherit_tools: true
    inherit_knowledge: true
    
  specialization:
    domains: ["react", "typescript", "testing", "company-standards"]
    technologies: ["react-18", "next-js", "tailwind", "jest", "storybook"]
    expertise_level: "expert"
    
  personality:
    style: "collaborative"
    verbosity: "detailed"
    creativity: 0.3
    approach: "methodical"
    
  capabilities:
    code_generation: true
    code_review: true
    testing: true
    documentation: true
    debugging: true
    refactoring: true

Knowledge Base Integration

knowledge_base:
  sources:
    - type: "documentation"
      path: "docs/company-standards/"
      include_patterns: ["*.md", "*.mdx"]
      
    - type: "code_examples"
      path: "src/examples/"
      include_patterns: ["*.tsx", "*.ts"]
      
    - type: "external_docs"
      urls: 
        - "https://company.com/api-docs"
        - "https://company.com/design-system-docs"
        
    - type: "custom_prompts"
      path: "prompts/react-patterns/"
      
  processing:
    embedding_model: "text-embedding-3-large"
    chunk_size: 1000
    overlap: 200
    similarity_threshold: 0.8
    
  indexing:
    update_frequency: "daily"
    auto_refresh: true
    version_control: true

Tool Integration

tools:
  built_in:
    - "file_operations"
    - "code_analysis"
    - "test_runner"
    - "git_operations"
    
  custom_tools:
    - name: "company_linter"
      type: "external_command"
      command: "npx company-lint"
      description: "Run company-specific linting rules"
      
    - name: "design_system_checker"
      type: "api_integration"
      endpoint: "https://api.company.com/design-system/validate"
      description: "Validate against company design system"
      
    - name: "deployment_checker"
      type: "mcp_server"
      server: "company-deployment-mcp"
      description: "Check deployment status and requirements"
      
  permissions:
    file_system:
      read: ["src/", "docs/", "tests/"]
      write: ["src/", "tests/"]
      execute: ["package.json.scripts.*"]
      
    network:
      allowed_domains: ["company.com", "api.company.com"]
      
    commands:
      allowed: ["npm", "yarn", "git", "company-lint"]
      blocked: ["rm -rf", "sudo", "curl"]

Advanced Agent Features

Custom Prompt Engineering

Prompt Templates

# Create custom prompt templates
/factory prompts create --template react-component --agent custom-react-expert

# Edit prompt templates
/factory prompts edit react-component.txt

Example Custom Prompt:

# react-component-prompt.txt
You are a React expert specialized in our company's technology stack and standards.

TECHNOLOGY STACK:
- React 18 with TypeScript (strict mode)
- Next.js 14 with App Router
- Tailwind CSS with company design tokens
- Jest and React Testing Library
- Storybook for component documentation

COMPANY STANDARDS:
- Use functional components with hooks
- Implement proper TypeScript types for all props
- Include comprehensive JSDoc documentation  
- Follow accessibility best practices (WCAG 2.1 AA)
- Use company design system components when available
- Include unit tests with 90% coverage minimum
- Create Storybook stories for all components

CODING PATTERNS:
- Prefer composition over inheritance
- Use custom hooks for reusable logic
- Implement proper error boundaries
- Use React.memo for performance optimization
- Follow company naming conventions

When creating components, always:
1. Start with TypeScript interface for props
2. Implement the component with proper typing
3. Add JSDoc documentation
4. Create comprehensive tests
5. Add Storybook stories with multiple variants
6. Ensure accessibility compliance
7. Optimize for performance

Ask clarifying questions if requirements are unclear.

Dynamic Prompts

// Dynamic prompt generation based on context
interface PromptContext {
  projectType: string;
  technologies: string[];
  userExperience: 'beginner' | 'intermediate' | 'expert';
  taskComplexity: 'simple' | 'medium' | 'complex';
}

const generatePrompt = (context: PromptContext) => {
  let basePrompt = getBasePrompt();
  
  // Adjust verbosity based on user experience
  if (context.userExperience === 'beginner') {
    basePrompt += '\\nProvide detailed explanations and educational context.';
  }
  
  // Add technology-specific guidance
  context.technologies.forEach(tech => {
    basePrompt += `\\n${getTechnologyGuidance(tech)}`;
  });
  
  // Adjust approach based on complexity
  if (context.taskComplexity === 'complex') {
    basePrompt += '\\nBreak down complex tasks into manageable steps.';
  }
  
  return basePrompt;
};

Context-Aware Prompts

# Configure context-aware prompting
/agent-config custom-react-expert --context-awareness high
/agent-config custom-react-expert --adaptive-prompting enable

# Example context adaptations:
# - Project type (startup vs enterprise) → Different architecture advice
# - Team size → Collaboration vs individual patterns  
# - Timeline → Quick solutions vs comprehensive implementations
# - Performance requirements → Different optimization strategies

Custom Tool Development

External Command Tools

// custom-tools/company-linter.ts
import { Tool, ToolExecutionContext } from '@nikcli/agent-sdk';

export class CompanyLinterTool implements Tool {
  name = 'company_linter';
  description = 'Run company-specific linting and formatting rules';
  
  parameters = {
    type: 'object',
    properties: {
      files: {
        type: 'array',
        items: { type: 'string' },
        description: 'Files to lint'
      },
      fix: {
        type: 'boolean',
        description: 'Auto-fix issues when possible'
      }
    },
    required: ['files']
  };
  
  async execute(params: any, context: ToolExecutionContext) {
    const { files, fix = false } = params;
    const command = fix ? 'company-lint --fix' : 'company-lint';
    
    try {
      const result = await context.executeCommand(`${command} ${files.join(' ')}`);
      
      return {
        success: result.exitCode === 0,
        output: result.stdout,
        errors: result.stderr,
        fixedFiles: fix ? this.extractFixedFiles(result.stdout) : []
      };
    } catch (error) {
      return {
        success: false,
        error: error.message
      };
    }
  }
  
  private extractFixedFiles(output: string): string[] {
    // Parse linter output to extract fixed files
    const fixedFiles = output
      .split('\\n')
      .filter(line => line.includes('✓ Fixed'))
      .map(line => line.match(/✓ Fixed (.+)/)?.[1])
      .filter(Boolean);
      
    return fixedFiles as string[];
  }
}

API Integration Tools

// custom-tools/design-system-validator.ts
import { Tool, ToolExecutionContext } from '@nikcli/agent-sdk';
import axios from 'axios';

export class DesignSystemValidator implements Tool {
  name = 'design_system_validator';
  description = 'Validate components against company design system';
  
  parameters = {
    type: 'object',
    properties: {
      componentCode: {
        type: 'string',
        description: 'React component code to validate'
      },
      componentName: {
        type: 'string', 
        description: 'Name of the component'
      }
    },
    required: ['componentCode', 'componentName']
  };
  
  async execute(params: any, context: ToolExecutionContext) {
    const { componentCode, componentName } = params;
    
    try {
      const response = await axios.post('https://api.company.com/design-system/validate', {
        code: componentCode,
        name: componentName,
        framework: 'react'
      }, {
        headers: {
          'Authorization': `Bearer ${process.env.COMPANY_API_TOKEN}`,
          'Content-Type': 'application/json'
        }
      });
      
      const validation = response.data;
      
      return {
        isValid: validation.valid,
        score: validation.score,
        issues: validation.issues,
        suggestions: validation.suggestions,
        compatibleComponents: validation.alternatives,
        designTokens: validation.availableTokens
      };
    } catch (error) {
      return {
        isValid: false,
        error: `Design system validation failed: ${error.message}`
      };
    }
  }
}

MCP Server Integration

// custom-tools/deployment-status.ts
import { Tool, ToolExecutionContext, MCPClient } from '@nikcli/agent-sdk';

export class DeploymentStatusTool implements Tool {
  name = 'deployment_status';
  description = 'Check deployment status and requirements';
  
  private mcpClient: MCPClient;
  
  constructor() {
    this.mcpClient = new MCPClient('company-deployment-mcp');
  }
  
  parameters = {
    type: 'object',
    properties: {
      environment: {
        type: 'string',
        enum: ['development', 'staging', 'production'],
        description: 'Target deployment environment'
      },
      service: {
        type: 'string',
        description: 'Service name to check'
      }
    },
    required: ['environment']
  };
  
  async execute(params: any, context: ToolExecutionContext) {
    const { environment, service } = params;
    
    try {
      // Connect to company MCP server
      await this.mcpClient.connect();
      
      // Get deployment status
      const status = await this.mcpClient.call('get_deployment_status', {
        environment,
        service
      });
      
      // Check deployment readiness
      const readiness = await this.mcpClient.call('check_deployment_readiness', {
        environment,
        service,
        currentBranch: await context.executeCommand('git branch --show-current')
      });
      
      return {
        status: status.data,
        readiness: readiness.data,
        recommendations: readiness.data.recommendations,
        blockers: readiness.data.blockers
      };
    } catch (error) {
      return {
        error: `Deployment check failed: ${error.message}`
      };
    } finally {
      await this.mcpClient.disconnect();
    }
  }
}

Agent Deployment and Management

Deployment Process

Local Development

# Develop and test agent locally
/factory dev --agent custom-react-expert --watch

# Test agent with sample tasks
/factory test custom-react-expert --tasks test-scenarios.json

# Debug agent behavior
/debug agent custom-react-expert --trace-execution

Team Deployment

# Package agent for sharing
/factory package custom-react-expert --include-knowledge-base

# Deploy to team registry
/factory deploy custom-react-expert --registry team --version 1.0.0

# Install agent from registry
/factory install team/custom-react-expert@1.0.0

Enterprise Deployment

# Enterprise deployment with approval workflow  
/factory deploy custom-react-expert 
         --registry enterprise
         --require-approval
         --compliance-check
         --security-scan

# Batch deployment to multiple environments
/factory deploy-batch agents.yaml 
                --environments dev,staging,prod
                --rollout-strategy blue-green

Version Management

Semantic Versioning

# Version management
/factory version custom-react-expert --bump minor --changelog "Added Storybook integration"

# Tag and release
/factory release custom-react-expert --version 1.1.0 --notes "Enhanced component generation"

# Rollback to previous version
/factory rollback custom-react-expert --to-version 1.0.0

A/B Testing

# Deploy multiple versions for testing
/factory deploy custom-react-expert-v2 --experimental --traffic-split 20%

# Monitor performance comparison
/factory analytics compare --versions 1.0.0,2.0.0 --metrics performance,satisfaction

# Promote winning version
/factory promote custom-react-expert-v2 --to-production

Agent Analytics

Performance Metrics

# Agent performance dashboard
/factory analytics custom-react-expert --metrics "
  response_time
  task_completion_rate
  user_satisfaction
  code_quality_score
  error_rate
" --time-range 30d

Usage Analytics

# Usage pattern analysis
/factory analytics custom-react-expert --usage "
  most_common_tasks
  user_patterns
  peak_usage_times
  feature_utilization
  integration_points
"

Improvement Insights

# Get improvement recommendations
/factory insights custom-react-expert --recommendations "
  performance_optimizations
  knowledge_base_gaps
  tool_integration_opportunities
  user_experience_improvements
"

Industry-Specific Agents

FinTech Specialist Agent

Compliance-Focused Development

# fintech-compliance-agent.yaml
agent:
  name: "FinTech Compliance Expert"
  specialization:
    domains: ["financial-services", "compliance", "security"]
    regulations: ["PCI-DSS", "SOX", "GDPR", "PSD2", "Open-Banking"]
    
  knowledge_base:
    sources:
      - type: "regulatory_docs"
        path: "compliance/regulations/"
      - type: "security_standards"
        path: "security/financial-standards/"
      - type: "audit_requirements"
        path: "audit/requirements/"
        
  tools:
    compliance_tools:
      - name: "pci_validator"
        description: "Validate PCI-DSS compliance"
      - name: "sox_auditor"  
        description: "SOX compliance checking"
      - name: "gdpr_analyzer"
        description: "GDPR data protection analysis"
        
  validation_rules:
    - "All payment data must be encrypted"
    - "Audit trails required for all transactions"
    - "No sensitive data in logs or error messages"
    - "Implement proper access controls"
    - "Regular security assessments required"

HealthTech Specialist Agent

HIPAA-Compliant Development

# healthtech-hipaa-agent.yaml
agent:
  name: "HealthTech HIPAA Expert"
  specialization:
    domains: ["healthcare", "hipaa-compliance", "fhir", "hl7"]
    standards: ["FHIR-R4", "HL7-v3", "DICOM", "IHE"]
    
  knowledge_base:
    sources:
      - type: "hipaa_guidelines"
        path: "compliance/hipaa/"
      - type: "fhir_specifications"
        url: "https://hl7.org/fhir/R4/"
      - type: "medical_coding_standards"
        path: "standards/medical-codes/"
        
  tools:
    healthcare_tools:
      - name: "hipaa_validator"
        description: "HIPAA compliance validation"
      - name: "fhir_validator"
        description: "FHIR resource validation"
      - name: "phi_detector"
        description: "Detect Protected Health Information"
        
  privacy_controls:
    - "No PHI in development environments"
    - "Encryption at rest and in transit"
    - "Access logging and monitoring"
    - "Data minimization principles"
    - "Patient consent management"

Agent Marketplace

Publishing Agents

Public Marketplace

# Publish to public marketplace
/factory publish custom-react-expert 
         --marketplace public
         --license MIT
         --price free
         --categories react,frontend,typescript

# Submit for review
/factory submit-review custom-react-expert --documentation-complete

Enterprise Marketplace

# Publish to enterprise marketplace
/factory publish fintech-compliance-expert
         --marketplace enterprise
         --price 99.99
         --subscription-model monthly
         --support-level premium

Discovering Agents

Agent Discovery

# Browse marketplace
/factory marketplace --category react --rating 4+

# Search for specific capabilities
/factory search "typescript testing storybook" --type agent

# Get agent recommendations
/factory recommend --based-on-project --current-stack react,typescript

Agent Installation

# Install from marketplace
/factory install marketplace/react-testing-expert@2.1.0

# Install with customization
/factory install react-expert --customize --add-knowledge "company-docs/"

# Bulk install for team
/factory install-batch team-agents.yaml --approve-all

Best Practices

Agent Design Principles

Single Responsibility

Design agents with focused, well-defined responsibilities

# Good: Focused agent
name: "React Testing Specialist"
focus: "Testing React components with Jest and RTL"

# Avoid: Overly broad agent  
name: "Full-Stack Everything Agent"

Knowledge Quality

Curate high-quality, relevant knowledge sources

knowledge_base:
  quality_criteria:
    - accuracy: "verified-sources-only"
    - recency: "updated-within-6-months"
    - relevance: "domain-specific-only"

Tool Integration

Integrate tools that provide real value to users

tools:
  selection_criteria:
    - essential_for_domain: true
    - reliable_and_maintained: true
    - clear_value_proposition: true

User Experience

Design for intuitive, helpful user interactions

personality:
  helpful: true
  patient: true
  educational: true
  context_aware: true

Testing and Quality Assurance

Agent Testing

# Comprehensive agent testing
/factory test custom-react-expert --test-suite "
  unit_tests: Test individual capabilities
  integration_tests: Test tool integrations  
  user_scenario_tests: Test real-world usage
  performance_tests: Response time and accuracy
  edge_case_tests: Handle unusual inputs gracefully
"

Quality Metrics

# Define quality benchmarks
/factory quality-gates custom-react-expert --gates "
  response_accuracy: >95%
  response_time: <30s
  user_satisfaction: >4.5/5
  code_quality_score: >8/10
  error_rate: <2%
"

Next Steps

Agent Orchestration

Learn how to coordinate custom agents with others

Advanced Features

Explore advanced NikCLI features for agent development

Integration Examples

See how custom agents integrate with development workflows

Contributing

Contribute to the NikCLI agent ecosystem

Start with simple custom agents that solve specific problems in your workflow. Focus on quality knowledge curation and user experience. Test thoroughly before sharing with your team or publishing to the marketplace.