sf-agent-framework/docs/08-agents/README.md

AI Agent Orchestration Framework for Salesforce Development - Two-phase architecture with 70% context reduction

# Agent System Documentation

## Overview

The SF-Agent Framework features 30+ specialized Salesforce agents, each designed for specific roles and responsibilities. Agents operate in two modes: Rich (128k context) for planning and Lean (32k context) for development.

## Agent Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                        Agent System                          │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Planning Agents (128k)                   │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │ Product Manager │ Business Analyst │ Architect       │  │
│  │ Data Architect  │ Security Expert  │ UX Designer     │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │            Development Agents (32k)                   │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │ Developer │ Admin │ QA Engineer │ DevOps Lead       │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │             Specialty Agents                          │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │ OmniStudio │ MCP │ Marketing │ Commerce │ Analytics │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

## Core Agents

### Planning Phase Agents (128k Context)

#### 1. SF-Product-Manager

**Purpose**: Define product vision, requirements, and roadmap.

```yaml
agent: sf-product-manager
phase: planning
context_limit: 128000
expertise:
  - Product strategy
  - Feature prioritization
  - Stakeholder management
  - ROI analysis
  - User story creation

capabilities:
  - Requirement elicitation
  - Feature specification
  - Roadmap planning
  - Success metrics definition
  - Acceptance criteria creation

outputs:
  - requirements.md
  - product-roadmap.md
  - user-stories.yaml
  - success-metrics.md
```

**Usage Example**:

```bash
# Gather requirements for new feature
sf-agent agent sf-product-manager --task "Define requirements for customer portal"

# Create product roadmap
sf-agent agent sf-product-manager --task "Create Q2 2025 roadmap"
```

#### 2. SF-Business-Analyst

**Purpose**: Analyze business processes and translate to technical requirements.

```yaml
agent: sf-business-analyst
phase: planning
context_limit: 128000
expertise:
  - Process mapping
  - Gap analysis
  - Data flow analysis
  - Business rule documentation
  - Stakeholder interviews

capabilities:
  - Process documentation
  - Requirements analysis
  - Data mapping
  - User journey mapping
  - Impact assessment

outputs:
  - business-requirements.md
  - process-flows.md
  - data-dictionary.md
  - gap-analysis.md
```

**Usage Example**:

```bash
# Analyze current process
sf-agent agent sf-business-analyst --task "Map current order fulfillment process"

# Document business rules
sf-agent agent sf-business-analyst --task "Document pricing calculation rules"
```

#### 3. SF-Architect

**Purpose**: Design technical solutions and system architecture.

```yaml
agent: sf-architect
phase: planning
context_limit: 128000
expertise:
  - Solution architecture
  - Platform limits
  - Integration patterns
  - Security architecture
  - Performance optimization

capabilities:
  - Technical design
  - Pattern selection
  - Architecture documentation
  - Trade-off analysis
  - Platform assessment

outputs:
  - architecture.md
  - technical-design.md
  - integration-design.md
  - decision-log.md
```

**Core Patterns**:

```javascript
// Architecture patterns this agent understands
const patterns = {
  integration: ['REST', 'SOAP', 'Platform Events', 'CDC', 'Bulk API'],
  data: ['Master-Detail', 'Lookup', 'External Objects', 'Big Objects'],
  security: ['Sharing Rules', 'OWD', 'Profiles', 'Permission Sets'],
  performance: ['Selective Queries', 'Batch Apex', 'Queueable', 'Platform Cache'],
};
```

#### 4. SF-Technical-Architect

**Purpose**: Deep technical design and platform optimization.

```yaml
agent: sf-technical-architect
phase: planning
context_limit: 128000
expertise:
  - Apex patterns
  - LWC architecture
  - Governor limits
  - Bulk processing
  - Async patterns

capabilities:
  - Code architecture
  - Performance design
  - Scalability planning
  - Technical standards
  - Best practices enforcement

outputs:
  - technical-architecture.md
  - coding-standards.md
  - performance-plan.md
  - governor-limits-analysis.md
```

#### 5. SF-Data-Architect

**Purpose**: Design data model and data management strategy.

```yaml
agent: sf-data-architect
phase: planning
context_limit: 128000
expertise:
  - Data modeling
  - Object relationships
  - Data migration
  - Data governance
  - Large data volumes

capabilities:
  - ERD creation
  - Object design
  - Field optimization
  - Index planning
  - Archival strategy

outputs:
  - data-model.md
  - erd-diagram.md
  - migration-plan.md
  - data-governance.md
```

#### 6. SF-Integration-Architect

**Purpose**: Design integrations and API strategy.

```yaml
agent: sf-integration-architect
phase: planning
context_limit: 128000
expertise:
  - API design
  - Middleware patterns
  - Event-driven architecture
  - ETL/ELT
  - Real-time vs batch

capabilities:
  - Integration design
  - API specification
  - Error handling
  - Retry logic
  - Monitoring strategy

outputs:
  - integration-architecture.md
  - api-specification.yaml
  - error-handling.md
  - monitoring-plan.md
```

#### 7. SF-Security-Architect

**Purpose**: Design security model and compliance strategy.

```yaml
agent: sf-security-architect
phase: planning
context_limit: 128000
expertise:
  - Security model
  - Compliance (GDPR, HIPAA, SOC2)
  - Encryption
  - Authentication
  - Data privacy

capabilities:
  - Security assessment
  - Threat modeling
  - Compliance mapping
  - Access control design
  - Audit trail planning

outputs:
  - security-model.md
  - compliance-matrix.md
  - threat-model.md
  - audit-plan.md
```

#### 8. SF-UX-Expert

**Purpose**: Design user experience and interface.

```yaml
agent: sf-ux-expert
phase: planning
context_limit: 128000
expertise:
  - SLDS (Salesforce Lightning Design System)
  - User research
  - Wireframing
  - Accessibility
  - Mobile design

capabilities:
  - UI/UX design
  - Wireframe creation
  - User flow design
  - Accessibility audit
  - Design system creation

outputs:
  - ux-design.md
  - wireframes.md
  - user-flows.md
  - accessibility-checklist.md
```

### Development Phase Agents (32k Context)

#### 9. SF-Developer

**Purpose**: Implement code and components.

```yaml
agent: sf-developer
phase: development
context_limit: 32000
expertise:
  - Apex development
  - LWC/Aura
  - Triggers
  - Batch/Queueable
  - Test classes

capabilities:
  - Code generation
  - Unit testing
  - Debugging
  - Refactoring
  - Code review

templates:
  - apex-class.cls
  - lwc-component.js
  - trigger.trigger
  - test-class.cls
  - batch-class.cls
```

**Code Generation Example**:

```apex
// Generated by sf-developer agent
public with sharing class AccountService {

    public static List<Account> getActiveAccounts() {
        return [
            SELECT Id, Name, Type, Industry, AnnualRevenue
            FROM Account
            WHERE Active__c = true
            WITH SECURITY_ENFORCED
            LIMIT 1000
        ];
    }

    public static void updateAccountStatus(Set<Id> accountIds, String status) {
        List<Account> accountsToUpdate = new List<Account>();

        for(Id accountId : accountIds) {
            accountsToUpdate.add(new Account(
                Id = accountId,
                Status__c = status,
                Last_Modified_Date__c = System.now()
            ));
        }

        if(!accountsToUpdate.isEmpty()) {
            update accountsToUpdate;
        }
    }
}
```

#### 10. SF-Admin

**Purpose**: Configure Salesforce declaratively.

```yaml
agent: sf-admin
phase: development
context_limit: 32000
expertise:
  - Object configuration
  - Fields & relationships
  - Page layouts
  - Record types
  - Validation rules
  - Process automation

capabilities:
  - Metadata creation
  - Flow building
  - Report creation
  - Dashboard design
  - Email templates

outputs:
  - object-definitions.xml
  - field-definitions.xml
  - validation-rules.xml
  - page-layouts.xml
```

#### 11. SF-QA

**Purpose**: Test implementation and ensure quality.

```yaml
agent: sf-qa
phase: development
context_limit: 32000
expertise:
  - Test planning
  - Test case creation
  - Apex testing
  - UI testing
  - Performance testing

capabilities:
  - Test generation
  - Coverage analysis
  - Bug identification
  - Regression testing
  - Load testing

outputs:
  - test-plan.md
  - test-cases.md
  - test-results.md
  - coverage-report.md
```

#### 12. SF-DevOps-Lead

**Purpose**: Manage CI/CD and deployment.

```yaml
agent: sf-devops-lead
phase: development
context_limit: 32000
expertise:
  - CI/CD pipelines
  - Git workflows
  - Deployment strategies
  - Environment management
  - Release planning

capabilities:
  - Pipeline creation
  - Deployment automation
  - Rollback procedures
  - Environment setup
  - Monitoring setup

outputs:
  - deployment-plan.md
  - ci-cd-pipeline.yaml
  - rollback-plan.md
  - monitoring-setup.md
```

### Specialty Agents

#### 13. SF-OmniStudio-Architect

**Purpose**: Design OmniStudio solutions.

```yaml
agent: sf-omnistudio-architect
phase: planning
context_limit: 128000
expertise:
  - OmniScripts
  - FlexCards
  - DataRaptors
  - Integration Procedures
  - Decision Matrices

capabilities:
  - OmniScript design
  - FlexCard creation
  - DataRaptor mapping
  - Integration design
  - Industry solutions
```

#### 14. SF-Marketing-Cloud-Specialist

**Purpose**: Marketing Cloud implementation.

```yaml
agent: sf-marketing-cloud-specialist
phase: planning
context_limit: 128000
expertise:
  - Journey Builder
  - Email Studio
  - Automation Studio
  - Data Extensions
  - AMPscript

capabilities:
  - Journey design
  - Email template creation
  - Automation setup
  - Personalization
  - Analytics configuration
```

#### 15. SF-Commerce-Cloud-Expert

**Purpose**: Commerce Cloud solutions.

```yaml
agent: sf-commerce-cloud-expert
phase: planning
context_limit: 128000
expertise:
  - B2B Commerce
  - B2C Commerce
  - Product catalog
  - Pricing rules
  - Cart & checkout

capabilities:
  - Storefront design
  - Product configuration
  - Pricing setup
  - Payment integration
  - Order management
```

#### 16. SF-Service-Cloud-Specialist

**Purpose**: Service Cloud optimization.

```yaml
agent: sf-service-cloud-specialist
phase: planning
context_limit: 128000
expertise:
  - Case management
  - Knowledge base
  - Omni-channel
  - Service Console
  - CTI integration

capabilities:
  - Case routing design
  - Knowledge article creation
  - SLA configuration
  - Console customization
  - Agent productivity tools
```

#### 17. SF-Analytics-Expert

**Purpose**: Analytics and reporting solutions.

```yaml
agent: sf-analytics-expert
phase: planning
context_limit: 128000
expertise:
  - Einstein Analytics
  - Reports & Dashboards
  - SOQL optimization
  - Data visualization
  - KPI definition

capabilities:
  - Dashboard creation
  - Dataset design
  - SAQL queries
  - Lens creation
  - Story telling
```

## Agent Communication

### Handoff Protocol

Agents communicate through formal handoff protocol:

```javascript
// Handoff structure
const handoff = {
  id: 'HANDOFF-001',
  from: 'sf-architect',
  to: 'sf-developer',
  timestamp: '2025-08-11T10:00:00Z',

  artifacts: [
    {
      type: 'document',
      path: 'docs/architecture.md',
      description: 'System architecture design',
    },
    {
      type: 'diagram',
      path: 'docs/erd.png',
      description: 'Entity relationship diagram',
    },
  ],

  instructions: {
    priority: 'high',
    tasks: ['Implement AccountService class', 'Create LWC components for UI', 'Write test classes with 90% coverage'],

    constraints: ['Must handle 10k records', 'Response time < 2 seconds', 'Follow coding standards'],
  },

  validation: {
    required: ['All tests passing', 'Code coverage > 85%', 'No security vulnerabilities'],
  },
};
```

### Agent Collaboration Patterns

#### 1. Sequential Handoff

```mermaid
graph LR
    A[Product Manager] --> B[Business Analyst]
    B --> C[Architect]
    C --> D[Developer]
    D --> E[QA]
    E --> F[DevOps]
```

#### 2. Parallel Collaboration

```mermaid
graph TD
    A[Architect] --> B[Data Architect]
    A --> C[Security Architect]
    A --> D[Integration Architect]
    B --> E[Developer]
    C --> E
    D --> E
```

#### 3. Review Loop

```mermaid
graph LR
    A[Developer] --> B[Code Review by Architect]
    B --> C{Approved?}
    C -->|Yes| D[QA]
    C -->|No| A
```

## Agent Customization

### Creating Custom Agents

```javascript
// custom-agent.js
const CustomAgent = {
  id: 'sf-custom-manufacturing',
  name: 'Manufacturing Cloud Specialist',
  phase: 'planning',
  contextLimit: 128000,

  expertise: ['Manufacturing Cloud', 'Sales Agreements', 'Account Forecasting', 'Production Planning'],

  capabilities: {
    analyze: async (context) => {
      // Custom analysis logic
    },

    generate: async (requirements) => {
      // Custom generation logic
    },

    validate: async (artifacts) => {
      // Custom validation logic
    },
  },

  templates: {
    'sales-agreement': loadTemplate('sales-agreement.yaml'),
    'forecast-model': loadTemplate('forecast-model.yaml'),
  },

  prompts: {
    system: `You are a Manufacturing Cloud specialist...`,
    planning: `Analyze manufacturing requirements...`,
    implementation: `Implement manufacturing solutions...`,
  },
};

// Register custom agent
AgentRegistry.register(CustomAgent);
```

### Extending Existing Agents

```javascript
// Extend base developer agent
const EnhancedDeveloper = {
  ...BaseDeveloper,

  id: 'sf-developer-enhanced',

  // Add new capabilities
  capabilities: {
    ...BaseDeveloper.capabilities,

    generateMockData: async (schema) => {
      // Generate test data
    },

    performanceOptimize: async (code) => {
      // Optimize code for performance
    },
  },

  // Override existing methods
  generateTestClass: async (apexClass) => {
    // Enhanced test generation with better coverage
  },
};
```

## Agent Templates

### Agent Definition Template

```yaml
# agent-template.yaml
agent:
  id: sf-agent-name
  name: Human Readable Name
  version: 1.0.0
  phase: planning|development

  context:
    limit: 128000|32000
    optimization: aggressive|normal|minimal

  expertise:
    - Domain 1
    - Domain 2

  dependencies:
    required:
      - template-1.yaml
      - reference-1.md
    optional:
      - example-1.apex

  capabilities:
    primary:
      - capability-1
      - capability-2
    secondary:
      - capability-3

  outputs:
    documents:
      - type: markdown
        template: output-template.md
    code:
      - type: apex
        template: code-template.cls

  validation:
    rules:
      - Rule 1
      - Rule 2
    gates:
      - Gate 1
```

## Agent Metrics

### Performance Metrics

```javascript
// Agent performance tracking
const agentMetrics = {
  'sf-developer': {
    tasksCompleted: 156,
    averageTime: 4.2, // minutes
    successRate: 0.94,
    tokenUsage: {
      average: 12500,
      maximum: 28000,
      minimum: 5000,
    },
    satisfaction: 4.7, // out of 5
  },

  'sf-architect': {
    tasksCompleted: 89,
    averageTime: 8.5, // minutes
    successRate: 0.98,
    tokenUsage: {
      average: 45000,
      maximum: 95000,
      minimum: 20000,
    },
    satisfaction: 4.9,
  },
};
```

### Quality Metrics

```javascript
// Quality tracking per agent
const qualityMetrics = {
  'sf-developer': {
    codeQuality: {
      bugs: 0.3, // per 100 lines
      coverage: 0.87,
      complexity: 2.1, // cyclomatic
    },
    compliance: {
      standards: 0.95,
      security: 0.98,
      performance: 0.92,
    },
  },
};
```

## Best Practices

### 1. Agent Selection

```javascript
// Choose the right agent for the task
function selectAgent(task) {
  const agentMap = {
    requirements: 'sf-product-manager',
    architecture: 'sf-architect',
    'data-model': 'sf-data-architect',
    coding: 'sf-developer',
    testing: 'sf-qa',
    deployment: 'sf-devops-lead',
  };

  return agentMap[task.type] || 'sf-developer';
}
```

### 2. Context Management

```javascript
// Optimize context for each agent
function optimizeContext(agent, task) {
  if (agent.phase === 'planning') {
    return {
      limit: 128000,
      include: ['all-docs', 'history', 'examples'],
      compression: false,
    };
  } else {
    return {
      limit: 32000,
      include: ['current-story', 'standards'],
      compression: true,
    };
  }
}
```

### 3. Agent Chaining

```javascript
// Chain agents for complex workflows
async function chainAgents(workflow) {
  const results = [];

  for (const step of workflow.steps) {
    const agent = getAgent(step.agent);
    const input = step.usePrevious ? results[results.length - 1] : step.input;

    const result = await agent.execute(input);
    results.push(result);

    if (step.validate) {
      await validateResult(result);
    }
  }

  return results;
}
```

## Troubleshooting

### Common Issues

**Issue: Agent not found**

```bash
# List available agents
sf-agent agent list

# Rebuild agent registry
sf-agent agents rebuild
```

**Issue: Context overflow**

```bash
# Check agent context usage
sf-agent agent sf-developer --context-info

# Switch to lean variant
sf-agent agent sf-developer-lean
```

**Issue: Agent timeout**

```bash
# Increase timeout
sf-agent agent sf-architect --timeout 600

# Use async execution
sf-agent agent sf-architect --async
```

## Agent Reference

### Quick Reference Table

| Agent                    | Phase       | Context | Primary Use            |
| ------------------------ | ----------- | ------- | ---------------------- |
| sf-product-manager       | Planning    | 128k    | Requirements & roadmap |
| sf-business-analyst      | Planning    | 128k    | Process analysis       |
| sf-architect             | Planning    | 128k    | Solution design        |
| sf-technical-architect   | Planning    | 128k    | Technical design       |
| sf-data-architect        | Planning    | 128k    | Data modeling          |
| sf-integration-architect | Planning    | 128k    | Integration design     |
| sf-security-architect    | Planning    | 128k    | Security design        |
| sf-ux-expert             | Planning    | 128k    | User experience        |
| sf-developer             | Development | 32k     | Code implementation    |
| sf-admin                 | Development | 32k     | Configuration          |
| sf-qa                    | Development | 32k     | Testing                |
| sf-devops-lead           | Development | 32k     | CI/CD & deployment     |

## Summary

The SF-Agent Framework's agent system provides:

1. **Specialized Expertise**: Each agent is an expert in its domain
2. **Phase Optimization**: Right-sized context for each phase
3. **Seamless Collaboration**: Formal handoff protocol
4. **Extensibility**: Create custom agents for your needs
5. **Quality Assurance**: Built-in validation and review

The agent system is the heart of the framework, enabling AI-augmented Salesforce development at scale.

---

_Last Updated: 2025-08-11_
_Version: 4.0.0_