Multi-Agent Workflows

Multi-agent workflows enable you to leverage specialized agents working together on complex tasks. Each agent brings domain expertise, and Forge orchestrates their collaboration to solve problems that require multiple perspectives and skill sets.

Overview

Forge supports multiple specialized agents:

Forge (default) - General-purpose coding agent
Sage - Code analysis and architecture expert
Muse - Strategic planning and design thinking
Planner - Task breakdown and project management
Custom agents - Define your own specialized agents

Multi-Agent Advantage

Complex tasks often require different types of thinking: strategic planning, detailed implementation, code review, and testing. Multi-agent workflows let you tap into the right expertise at each stage.

Agent Basics

Switching Agents

Interactive Mode
Shell Plugin
Direct Command

forge
> /agent sage
# Now using Sage agent

> Explain the authentication architecture

# Specify agent in command
:sage Explain how caching works

# Switch agent mid-conversation
: /agent muse
: Design a new feature architecture

# Use specific agent from CLI
forge -p "Explain authentication" --agent sage

Available Agents

Forge (Default)

Best for: General coding, debugging, implementationCapabilities:

Code generation and modification
Bug fixing and debugging
Test writing
Documentation creation
File operations

Use when: You need hands-on coding assistance

: Implement a user authentication system
: Debug this error in @[src/parser.rs]
: Add unit tests for the new feature

Sage

Best for: Code analysis, architecture review, deep understandingCapabilities:

Architecture analysis
Code quality assessment
Design pattern identification
System understanding
Best practices guidance

Use when: You need to understand complex systems

:sage Explain the authentication flow in this codebase
:sage Review this architecture for scalability issues
:sage What design patterns are used in @[src/core/]

Muse

Best for: Strategic planning, design thinking, innovationCapabilities:

Feature design and planning
System architecture proposals
Technology recommendations
Impact assessment
Strategic decision-making

Use when: You’re planning new features or major changes

:muse Design a caching strategy for this API
:muse How should we approach multi-tenancy?
:muse Evaluate database options for our use case

Planner

Best for: Task breakdown, project management, milestone planningCapabilities:

Breaking down large tasks
Creating implementation plans
Estimating complexity
Identifying dependencies
Milestone definition

Use when: You need to organize complex projects

:planner Break down building a REST API into tasks
:planner Create implementation plan for authentication
:planner What's the dependency graph for this feature?

Multi-Agent Workflows

Sequential Agent Flow

Use different agents for different stages:

Planning with Muse

:muse Design a new caching layer for the application

Output: Architecture proposal, technology choices, design patterns

Task Breakdown with Planner

: /agent planner
: Break down the caching layer implementation into tasks

Output: Ordered task list with dependencies

Implementation with Forge

: /agent forge
: Implement the cache interface from the plan

Output: Code implementation with tests

Review with Sage

: /agent sage
: Review the caching implementation for issues

Output: Code review, improvement suggestions

Parallel Agent Consultation

Get multiple perspectives on the same problem:

# Start with general exploration
: Analyze the authentication system

# Get architectural perspective
: /agent sage
: What are the security implications?

# Get strategic perspective  
: /agent muse
: How can we improve this for scale?

# Back to implementation
: /agent forge
: Implement the security improvements

Refine solutions through agent collaboration:

# Initial design
:muse Design an API rate limiting system

# Get implementation plan
: /agent planner
: Create a step-by-step implementation plan

# Review feasibility
: /agent sage
: Analyze this plan for potential issues

# Adjust design based on review
: /agent muse
: Revise the design addressing those concerns

# Implement refined design
: /agent forge
: Implement the revised rate limiting system

Creating Custom Agents

Define specialized agents for your team’s needs:

Agent Definition File

Create agents in your project or globally:

# .forge/agents/security-expert.yaml
id: security-expert
title: Security Expert
description: Specialized in security analysis and vulnerability detection

system_prompt: |
  You are a security expert specializing in application security.
  Focus on:
  - Identifying security vulnerabilities
  - Suggesting security best practices
  - Analyzing authentication and authorization
  - Reviewing cryptographic implementations
  - Detecting common security pitfalls
  
  Provide actionable security recommendations with severity levels.

tools:
  - fs_search
  - sem_search
  - read
  - bash

max_turns: 20
temperature: 0.3  # Lower temperature for focused security analysis

Agent Configuration Options

id: reviewer
title: Code Reviewer
description: Reviews code for quality and best practices

system_prompt: |
  You are a code reviewer focusing on:
  - Code quality and readability
  - Performance optimization
  - Best practices adherence

Agent Properties

Property	Description	Default
`id`	Unique agent identifier	Required
`title`	Display name	Same as id
`description`	Agent purpose	None
`system_prompt`	Instructions for agent behavior	Default prompt
`tools`	Available tools for agent	All tools
`max_turns`	Maximum conversation turns	50
`temperature`	Model creativity (0.0-2.0)	0.7
`max_tokens`	Maximum response length	Model default
`provider`	AI provider to use	Config default
`model`	Specific model to use	Config default
`custom_rules`	Additional constraints	None

Workflow Patterns

Research → Plan → Build

# Phase 1: Research
:sage Analyze current authentication implementation
:sage What are the limitations and issues?

# Phase 2: Design
: /agent muse
: Design an improved authentication system
: addressing the identified issues

# Phase 3: Planning
: /agent planner
: Break down the authentication redesign
: into implementable tasks

# Phase 4: Implementation
: /agent forge
: Implement task 1 from the plan

Explore → Understand → Modify

# Explore codebase
:sync  # Index for semantic search
:sage Map out the user management system

# Deep understanding
:sage Explain how user sessions work
:sage What security measures are in place?

# Make changes
: /agent forge
: Add rate limiting to login endpoint
: following the existing patterns

Design → Validate → Refine

# Initial design
:muse Design a notification system

# Validate feasibility
: /agent sage
: Review this design for potential issues
: in our current architecture

# Refine based on feedback
: /agent muse
: Adjust the design addressing those concerns

# Implementation planning
: /agent planner
: Create implementation roadmap

Advanced Techniques

Context Preservation

Maintain context across agent switches:

# Build context
:sage Analyze the payment processing flow

# Switch agent, context preserved
: /agent muse
: Based on the analysis, how can we improve reliability?
# Muse has access to Sage's analysis

: /agent forge
: Implement the suggested improvements
# Forge has access to both previous conversations

Agent-Specific Tools

Some agents may have specialized tool access:

# Security agent with limited tools
id: security-auditor
tools:
  - sem_search  # Find security-related code
  - read        # Read files for analysis
  - grep        # Search for patterns
  # Deliberately no 'write' or 'edit' - analysis only

Workflow Files

Create reusable multi-agent workflows:

# .forge/workflows/feature-development.yaml
name: Feature Development Workflow
description: End-to-end feature development

steps:
  - agent: muse
    prompt: Design the feature architecture
    
  - agent: planner
    prompt: Break down into implementation tasks
    
  - agent: forge
    prompt: Implement the feature
    
  - agent: sage
    prompt: Review for quality and security

Execute workflow:

forge --workflow .forge/workflows/feature-development.yaml \
      --event "Build user profile feature"

Best Practices

Choose the Right Agent

Match agent expertise to task type:

Understanding → Sage
Planning → Muse or Planner
Implementation → Forge
Review → Sage
Strategy → Muse

Build Context Early

Let agents understand the system first:

# Good: Build context
:sage Understand the auth system
: /agent forge
: Now modify the login handler

# Bad: Dive in blind
: Modify the login handler

Use Sequential Flow

Follow natural development stages:Plan → Implement → Review → RefineNot: Implement → Plan → Review

Leverage Specialization

Use agents for their strengths:

# Good
:muse What's the best architecture?
:forge Implement it

# Less optimal
:forge Design and implement architecture

Performance Considerations

Agent Model Selection

Different agents can use different models:

# Planning agent with fast model
id: quick-planner
model: claude-3-haiku
temperature: 0.5

# Analysis agent with powerful model
id: deep-analyzer  
model: claude-3.7-sonnet
temperature: 0.3

Tool Optimization

Limit tools for focused agents:

# Read-only analysis agent (faster)
id: code-analyzer
tools:
  - sem_search
  - read
  - grep

# Full-featured implementation agent
id: developer
tools:
  - sem_search
  - read
  - write
  - edit
  - bash
  - git

Troubleshooting

Agent not found

List available agents: forge agent list
Check agent file exists in .forge/agents/
Verify YAML syntax is valid
Reload Forge to pick up new agents

Context lost between agents

Verify conversation continuity with :info
Don’t use :new when switching agents
Use /agent command within same session
Check conversation ID remains consistent

Agent behavior unexpected

Review agent’s system_prompt
Check temperature setting (lower = more focused)
Verify custom_rules don’t conflict
Test with default agent for comparison

Examples

Building a New Feature

# Start with strategic thinking
:new
:muse I need to add real-time notifications
:muse What's the best approach for WebSockets vs SSE?

# Get implementation plan
: /agent planner
: Create a detailed implementation plan

# Implement core functionality
: /agent forge
: Implement the WebSocket server

# Review and improve
: /agent sage
: Review for scalability and error handling

# Iterate
: /agent forge
: Apply the suggested improvements

Debugging Complex Issues

# Understand the system
:sage Explain how the payment flow works @[src/payments/]

# Investigate issue
:sage Why might transactions fail intermittently?

# Design solution
: /agent muse
: Design a robust retry mechanism

# Implement fix
: /agent forge
: Implement the retry logic with exponential backoff

Refactoring Legacy Code

# Analyze current state
:sage Analyze the legacy user module @[src/legacy/user.rs]
:sage What are the main issues?

# Design modern approach
: /agent muse
: Design a modern replacement architecture

# Plan migration
: /agent planner
: Create a step-by-step refactoring plan
: that maintains backward compatibility

# Execute refactoring
: /agent forge
: Start with step 1 of the refactoring plan

Custom Commands - Automate multi-agent workflows
Semantic Search - Help agents understand codebases
Shell Integration - Quick agent switching
Git Operations - Collaborative git workflows

Getting Started

Core Concepts

Configuration

Providers

Features

Advanced Usage

Guides

Multi-Agent Workflows

Overview

Multi-Agent Advantage

Agent Basics

Switching Agents

Available Agents

Multi-Agent Workflows

Sequential Agent Flow

Parallel Agent Consultation

Iterative Refinement

Creating Custom Agents

Agent Definition File

Agent Configuration Options

Agent Properties

Workflow Patterns

Research → Plan → Build

Explore → Understand → Modify

Design → Validate → Refine

Advanced Techniques

Context Preservation

Agent-Specific Tools

Workflow Files

Best Practices

Performance Considerations

Agent Model Selection

Tool Optimization

Troubleshooting

Examples

Building a New Feature

Debugging Complex Issues

Refactoring Legacy Code

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Configuration

Providers

Features

Advanced Usage

Guides

​Overview

Multi-Agent Advantage

​Agent Basics

​Switching Agents

​Available Agents

​Multi-Agent Workflows

​Sequential Agent Flow

​Parallel Agent Consultation

​Iterative Refinement

​Creating Custom Agents

​Agent Definition File

​Agent Configuration Options

​Agent Properties

​Workflow Patterns

​Research → Plan → Build

​Explore → Understand → Modify

​Design → Validate → Refine

​Advanced Techniques

​Context Preservation

​Agent-Specific Tools

​Workflow Files

​Best Practices

​Performance Considerations

​Agent Model Selection

​Tool Optimization

​Troubleshooting

​Examples

​Building a New Feature

​Debugging Complex Issues

​Refactoring Legacy Code

​Related Features

Build docs developers (and LLMs) love

Overview

Agent Basics

Switching Agents

Available Agents

Multi-Agent Workflows

Sequential Agent Flow

Parallel Agent Consultation

Iterative Refinement

Creating Custom Agents

Agent Definition File

Agent Configuration Options

Agent Properties

Workflow Patterns

Research → Plan → Build

Explore → Understand → Modify

Design → Validate → Refine

Advanced Techniques

Context Preservation

Agent-Specific Tools

Workflow Files

Best Practices

Performance Considerations

Agent Model Selection

Tool Optimization

Troubleshooting

Examples

Building a New Feature

Debugging Complex Issues

Refactoring Legacy Code

Related Features