sf-agent-framework/docs/tutorials/06-agent-collaboration.md

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

# Tutorial: Multi-Agent Collaboration Protocol

## Overview

The Multi-Agent Collaboration Protocol enables formal handoffs between specialized agents, artifact passing, and collaborative reviews. This tutorial will guide you through orchestrating multiple agents working together on complex tasks.

## Prerequisites

- SF-Agent Framework installed
- Understanding of different agent roles
- Basic command-line knowledge

## What You'll Learn

- Creating agent handoffs
- Passing artifacts between agents
- Managing collaboration sequences
- Conducting collaborative reviews
- Tracking collaboration metrics

## Step 1: Understanding Agent Collaboration

### Key Concepts

- **Handoff**: Formal transfer of work from one agent to another
- **Artifacts**: Work products passed between agents
- **Acceptance Criteria**: Conditions for successful handoff
- **Collaboration Sequence**: Chain of handoffs
- **Review Process**: Multi-agent validation

## Step 2: Create Your First Handoff

### Basic Handoff Creation

```bash
sf-agent handoff create --from sf-analyst --to sf-developer \
  --notes "Requirements complete, ready for implementation"
```

Output:

```
✅ Handoff created: handoff-1234567890-abcd
From: sf-analyst → To: sf-developer
```

### Handoff with Artifacts

```bash
sf-agent handoff create --from sf-analyst --to sf-developer \
  --artifacts requirements.md user-stories.md \
  --notes "All requirements documented"
```

## Step 3: Accept a Handoff

### View Pending Handoffs

```bash
sf-agent handoff status
```

Output:

```
Active Handoffs:
  - handoff-1234567890-abcd: sf-analyst → sf-developer (pending)
  - handoff-0987654321-efgh: sf-architect → sf-developer (in_progress)
```

### Accept as Target Agent

```bash
sf-agent handoff accept handoff-1234567890-abcd --agent sf-developer
```

Output:

```
✅ Handoff handoff-1234567890-abcd accepted by sf-developer
Artifacts loaded: 2
```

## Step 4: Complete a Handoff

### Complete with Deliverables

```bash
sf-agent handoff complete handoff-1234567890-abcd --agent sf-developer \
  --artifacts feature-implementation.apex test-class.apex
```

Output:

```
✅ Handoff handoff-1234567890-abcd completed
Deliverables: 2
```

## Step 5: Create a Collaboration Sequence

### Define the Sequence

Create a file `collaboration-sequence.js`:

```javascript
const AgentCollaborationProtocol = require('./tools/lib/agent-collaboration-protocol');
const protocol = new AgentCollaborationProtocol();

await protocol.initialize();

const sequence = await protocol.createCollaborationSequence({
  name: 'Feature Development',
  description: 'Complete feature development workflow',
  agents: [
    {
      agent: 'sf-analyst',
      creates: ['requirements.md', 'user-stories.md'],
      transforms: ['business-requirements'],
    },
    {
      agent: 'sf-architect',
      requires: ['requirements.md'],
      creates: ['technical-design.md', 'data-model.md'],
      transforms: ['technical-architecture'],
    },
    {
      agent: 'sf-developer',
      requires: ['technical-design.md'],
      creates: ['implementation.apex', 'tests.apex'],
      transforms: ['code-implementation'],
    },
    {
      agent: 'sf-tester',
      requires: ['implementation.apex'],
      creates: ['test-results.md', 'bug-reports.md'],
      transforms: ['quality-validation'],
    },
  ],
});

console.log('Sequence created:', sequence.id);
```

## Step 6: Collaborative Review Process

### Request a Review

```javascript
const review = await protocol.requestReview({
  requester: 'sf-developer',
  reviewers: ['sf-architect', 'sf-tester', 'sf-pm'],
  artifacts: ['implementation.apex', 'technical-design.md'],
  subject: 'Feature Implementation',
  criteria: [
    'Code follows best practices',
    'Meets technical requirements',
    'Includes proper error handling',
    'Has adequate test coverage',
  ],
});

console.log('Review requested:', review.id);
```

### Submit Review Feedback

```javascript
await protocol.submitReviewFeedback(review.id, 'sf-architect', {
  feedback: 'Architecture looks good, minor suggestions added',
  approval: true,
  suggestions: ['Consider adding caching for performance', 'Update error messages for clarity'],
});
```

## Step 7: Real-World Example

Let's walk through a complete collaboration scenario:

### Scenario: Building a Customer Portal Feature

#### 1. Analyst Creates Requirements

```bash
# Analyst completes requirements gathering
sf-agent handoff create --from sf-analyst --to sf-architect \
  --artifacts requirements.md stakeholder-interviews.md \
  --notes "Requirements gathered from 5 stakeholders"
```

#### 2. Architect Designs System

```bash
# Architect accepts handoff
sf-agent handoff accept handoff-001 --agent sf-architect

# Architect completes design
sf-agent handoff complete handoff-001 --agent sf-architect \
  --artifacts system-design.md api-spec.yaml data-model.md
```

#### 3. Create Developer Handoff

```bash
# Architect hands off to developer
sf-agent handoff create --from sf-architect --to sf-developer \
  --artifacts system-design.md api-spec.yaml \
  --notes "Design approved by technical review board"
```

#### 4. Developer Implementation

```bash
# Developer accepts and implements
sf-agent handoff accept handoff-002 --agent sf-developer

# Developer completes implementation
sf-agent handoff complete handoff-002 --agent sf-developer \
  --artifacts CustomerPortalController.apex CustomerPortal.lwc \
  PortalService.apex TestCustomerPortal.apex
```

#### 5. Tester Validation

```bash
# Developer hands off to tester
sf-agent handoff create --from sf-developer --to sf-tester \
  --artifacts CustomerPortalController.apex TestCustomerPortal.apex \
  --notes "All unit tests passing, ready for QA"

# Tester performs validation
sf-agent handoff accept handoff-003 --agent sf-tester
sf-agent handoff complete handoff-003 --agent sf-tester \
  --artifacts test-results.md performance-report.md
```

## Step 8: Advanced Collaboration Patterns

### Parallel Collaboration

Multiple agents working simultaneously:

```javascript
// Create parallel handoffs
const designHandoff = await protocol.createHandoff({
  from: 'sf-analyst',
  to: 'sf-architect',
  artifacts: ['requirements.md'],
  metadata: { type: 'parallel' },
});

const uxHandoff = await protocol.createHandoff({
  from: 'sf-analyst',
  to: 'sf-ux-designer',
  artifacts: ['requirements.md'],
  metadata: { type: 'parallel' },
});

// Both agents work in parallel
```

### Conditional Handoffs

Handoffs based on conditions:

```javascript
const handoff = await protocol.createHandoff({
  from: 'sf-developer',
  to: 'sf-tester',
  artifacts: ['implementation.apex'],
  acceptance_criteria: ['Code coverage > 85%', 'No critical SonarQube issues', 'All unit tests passing'],
  metadata: {
    condition: 'auto_validate',
    fallback_agent: 'sf-developer', // Return if criteria not met
  },
});
```

### Review Gates

Mandatory review before proceeding:

```javascript
const reviewGate = await protocol.requestReview({
  requester: 'sf-developer',
  reviewers: ['sf-architect', 'sf-security'],
  artifacts: ['implementation.apex'],
  criteria: ['Security best practices followed', 'No SOQL injection vulnerabilities', 'Proper FLS checks implemented'],
  metadata: {
    blocking: true,
    minimum_approvals: 2,
  },
});
```

## Step 9: Monitoring Collaboration

### View Collaboration Metrics

```bash
sf-agent handoff metrics
```

Output:

```json
{
  "total_handoffs": 15,
  "pending_handoffs": 2,
  "in_progress_handoffs": 3,
  "completed_handoffs": 10,
  "collaboration_events": 45,
  "active_agents": 6
}
```

### Track Specific Agent

```bash
sf-agent handoff status --agent sf-developer
```

Output:

```
Active Handoffs for sf-developer:
  - handoff-001: sf-architect → sf-developer (in_progress)
  - handoff-002: sf-developer → sf-tester (pending)
  - handoff-003: sf-pm → sf-developer (pending)
```

## Step 10: Best Practices

### 1. Clear Acceptance Criteria

Always define clear acceptance criteria:

```javascript
acceptance_criteria: [
  'All requirements addressed',
  'Code follows style guide',
  'Documentation complete',
  'Tests provide 90% coverage',
];
```

### 2. Artifact Versioning

Track artifact versions:

```javascript
artifacts: [
  { name: 'design-v2.md', version: '2.0' },
  { name: 'api-spec-v1.yaml', version: '1.0' },
];
```

### 3. Context Preservation

Include context in handoffs:

```javascript
context: {
  project_phase: 'development',
  sprint: 'Sprint 23',
  priority: 'high',
  deadline: '2024-01-15',
  dependencies: ['auth-service', 'data-model']
}
```

### 4. Review Patterns

Establish review patterns:

- **Peer Review**: Same-level agent review
- **Hierarchical Review**: Senior agent approval
- **Cross-Functional Review**: Multiple disciplines

## Example: Complete Feature Workflow

Here's a complete example combining all concepts:

```javascript
async function executeFeatureWorkflow() {
  const protocol = new AgentCollaborationProtocol();
  await protocol.initialize();

  // Phase 1: Requirements
  console.log('Phase 1: Requirements Gathering');
  const reqHandoff = await protocol.createHandoff({
    from: 'sf-pm',
    to: 'sf-analyst',
    artifacts: ['feature-request.md'],
    requirements: ['Gather detailed requirements', 'Create user stories'],
    acceptance_criteria: ['All stakeholders interviewed', 'Stories estimated'],
  });

  // Phase 2: Architecture
  console.log('Phase 2: Architecture Design');
  const archHandoff = await protocol.createHandoff({
    from: 'sf-analyst',
    to: 'sf-architect',
    artifacts: ['requirements.md', 'user-stories.md'],
    requirements: ['Design technical architecture', 'Define data model'],
    acceptance_criteria: ['Design reviewed', 'Performance considered'],
  });

  // Phase 3: Development
  console.log('Phase 3: Implementation');
  const devHandoff = await protocol.createHandoff({
    from: 'sf-architect',
    to: 'sf-developer',
    artifacts: ['technical-design.md', 'data-model.md'],
    requirements: ['Implement features', 'Write unit tests'],
    acceptance_criteria: ['Code coverage > 90%', 'All tests passing'],
  });

  // Phase 4: Review
  console.log('Phase 4: Collaborative Review');
  const review = await protocol.requestReview({
    requester: 'sf-developer',
    reviewers: ['sf-architect', 'sf-tester', 'sf-security'],
    artifacts: ['implementation.apex', 'tests.apex'],
    criteria: ['Meets requirements', 'Follows best practices', 'Secure implementation', 'Performant code'],
  });

  // Phase 5: Testing
  console.log('Phase 5: Quality Assurance');
  const testHandoff = await protocol.createHandoff({
    from: 'sf-developer',
    to: 'sf-tester',
    artifacts: ['implementation.apex', 'test-plan.md'],
    requirements: ['Execute test plan', 'Performance testing'],
    acceptance_criteria: ['All tests passing', 'No critical bugs'],
  });

  // Phase 6: Deployment
  console.log('Phase 6: Deployment');
  const deployHandoff = await protocol.createHandoff({
    from: 'sf-tester',
    to: 'sf-devops',
    artifacts: ['test-results.md', 'deployment-package.zip'],
    requirements: ['Deploy to production', 'Monitor deployment'],
    acceptance_criteria: ['Successful deployment', 'No errors in logs'],
  });

  console.log('Workflow initiated successfully!');
}
```

## Troubleshooting

### Handoff Not Found

```bash
# List all handoffs to find correct ID
sf-agent handoff status

# Use correct ID format
sf-agent handoff accept handoff-1234567890-abcd --agent sf-developer
```

### Agent Compatibility Issues

Check agent compatibility:

```javascript
const compatibility = await protocol.checkAgentCompatibility('sf-analyst', 'sf-developer');
console.log(compatibility);
```

### Validation Failures

When deliverables don't meet criteria:

1. Review acceptance criteria
2. Update deliverables
3. Retry completion

## Next Steps

- Master [Context Memory](./07-context-memory.md)
- Review [Interactive Workflows](./05-interactive-workflows.md)
- Explore [Web UI Commands](./04-web-ui-commands.md)

## Conclusion

The Multi-Agent Collaboration Protocol provides a robust framework for orchestrating complex, multi-agent workflows. By formalizing handoffs, managing artifacts, and enabling collaborative reviews, teams can ensure quality and consistency throughout the development lifecycle.