Agent Collaboration
Multi-agent task delegation with handoff protocols for complex development tasks
Agent Collaboration enables multiple Bootspring agents to work together on complex tasks, with structured delegation and handoff protocols.
Overview#
Instead of using a single agent, collaboration sessions allow:
- Primary agents to lead complex tasks
- Supporting agents to assist with specialized subtasks
- Handoffs to transfer context between agents
- Aggregated results from all participants
How It Works#
┌─────────────────────────────────────────────────────────────┐
│ Collaboration Session │
│ │
│ Primary: architecture-expert │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Main Task │ │
│ │ "Design authentication system" │ │
│ └───────────────────┬─────────────────────────────────┘ │
│ │ │
│ ┌────────────┼────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │Subtask 1 │ │Subtask 2 │ │Subtask 3 │ │
│ │security- │ │database- │ │api- │ │
│ │expert │ │expert │ │expert │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │
│ └────────────┼────────────┘ │
│ ▼ │
│ Final Results │
└─────────────────────────────────────────────────────────────┘
Starting a Collaboration Session#
Via CLI#
1# Start a session with a primary agent
2bootspring collab start --primary architecture-expert --task "Design auth system"
3
4# Add supporting agents
5bootspring collab add-agent security-expert
6bootspring collab add-agent database-expertVia API#
1const collab = require('bootspring/intelligence/agent-collab');
2
3// Start a session
4const session = collab.startSession({
5 primaryAgent: 'architecture-expert',
6 supportingAgents: ['security-expert', 'database-expert'],
7 task: {
8 title: 'Design authentication system',
9 description: 'Create a secure, scalable auth system with SSO support',
10 requirements: ['OAuth 2.0', 'SSO/SAML', 'MFA support']
11 }
12});
13// {
14// success: true,
15// sessionId: 'collab-abc123',
16// primaryAgent: 'architecture-expert',
17// supportingAgents: ['security-expert', 'database-expert']
18// }Delegating Tasks#
Create Subtasks#
1// Delegate a subtask
2collab.delegateTask(sessionId, {
3 title: 'Security requirements analysis',
4 description: 'Identify security requirements and threats',
5 assignee: 'security-expert',
6 priority: 'high'
7});
8
9collab.delegateTask(sessionId, {
10 title: 'Database schema design',
11 description: 'Design user and session tables',
12 assignee: 'database-expert',
13 priority: 'medium'
14});Complete Subtasks#
1// Mark a subtask as complete with results
2collab.completeSubtask(sessionId, subtaskId, {
3 findings: ['Use bcrypt for passwords', 'Implement rate limiting'],
4 recommendations: ['Add audit logging', 'Use secure session tokens'],
5 code: '// Security middleware implementation...'
6});Agent Handoffs#
Transfer context from one agent to another mid-task:
1// Request a handoff
2collab.requestHandoff(sessionId, {
3 fromAgent: 'security-expert',
4 toAgent: 'backend-expert',
5 reason: 'Security review complete, ready for implementation',
6 context: {
7 securityRequirements: ['...'],
8 approvedPatterns: ['...']
9 }
10});
11
12// Accept the handoff (as backend-expert)
13collab.acceptHandoff(sessionId, handoffId);Handoff Flow#
security-expert backend-expert
│ │
│ 1. Request Handoff │
│─────────────────────────────────▶│
│ (context + findings) │
│ │
│ 2. Accept Handoff │
│◀─────────────────────────────────│
│ │
│ │
│ 3. Continue Work │
│ ─┼─
│ │
Collaboration Patterns#
Use pre-defined patterns for common scenarios:
Code Review Pattern#
collab.startFromPattern('code-review');
// Primary: code-review-expert
// Supporting: security-expert, performance-expertFeature Development Pattern#
collab.startFromPattern('feature-development');
// Primary: architecture-expert
// Supporting: frontend-expert, backend-expert, testing-expertSecurity Audit Pattern#
collab.startFromPattern('security-audit');
// Primary: security-expert
// Supporting: code-review-expert, devops-expertAvailable Patterns#
| Pattern | Primary Agent | Supporting Agents |
|---|---|---|
code-review | code-review-expert | security, performance |
feature-development | architecture-expert | frontend, backend, testing |
security-audit | security-expert | code-review, devops |
performance-optimization | performance-expert | database, frontend |
api-design | api-expert | security, database |
database-migration | database-expert | backend, devops |
Session Management#
Check Session Status#
1const status = collab.getSessionStatus(sessionId);
2// {
3// sessionId: 'collab-abc123',
4// status: 'active',
5// primaryAgent: 'architecture-expert',
6// supportingAgents: ['security-expert', 'database-expert'],
7// task: {...},
8// subtasks: [
9// { id: '...', title: '...', status: 'completed', assignee: '...' }
10// ],
11// pendingHandoffs: [],
12// progress: { completed: 2, total: 3, percent: 67 }
13// }List Active Sessions#
const sessions = collab.listActiveSessions();Finalize Session#
1const results = collab.finalizeSession(sessionId);
2// {
3// success: true,
4// duration: 3600,
5// completedSubtasks: 3,
6// aggregatedResults: {
7// findings: [...],
8// recommendations: [...],
9// code: [...],
10// artifacts: [...]
11// }
12// }CLI Commands#
1# Start a session
2bootspring collab start --primary architecture-expert
3
4# View session status
5bootspring collab status <session-id>
6
7# List all sessions
8bootspring collab list
9
10# Delegate a task
11bootspring collab delegate <session-id> --agent security-expert --task "Review auth"
12
13# Complete a subtask
14bootspring collab complete <session-id> <subtask-id>
15
16# Finalize session
17bootspring collab finalize <session-id>Best Practices#
- Choose the right primary - The primary agent should have the broadest expertise for the task
- Delegate appropriately - Assign subtasks to agents with matching specialties
- Use handoffs for context - Don't repeat information, transfer it
- Start with patterns - Use pre-defined patterns when they fit
- Finalize for results - Always finalize to get aggregated insights