Skip to main content

Custom Workflows & Multi-Agent Systems

For complex tasks, a single agent may not be sufficient. Forge allows you to create custom workflows with multiple specialized agents working together to accomplish sophisticated tasks.

Multi-Agent Architecture Overview​

Forge implements a sophisticated multi-agent architecture that enables specialized agents to collaborate on complex tasks. This distributed approach to problem-solving provides several technical advantages:

  • Specialization: Agents can focus on specific tasks they excel at
  • Efficiency: Smaller models can handle simpler tasks, saving resources
  • Parallelization: Multiple agents can work simultaneously on different aspects of a problem
  • Collaboration: Agents can share information and build upon each other's work

Creating Custom Workflows​

You can configure your own workflows by creating a YAML file and pointing to it with the -w flag:

forge -w /path/to/your/workflow.yaml

Configuration Loading and Precedence​

Forge loads workflow configurations using the following precedence rules:

  1. Explicit Path: When a path is provided with the -w flag, Forge loads that configuration directly without any merging
  2. Project Configuration: If no explicit path is provided, Forge looks for forge.yaml in the current directory
  3. Default Configuration: An embedded default configuration is always available as a fallback

When a project configuration exists in the current directory, Forge creates a merged configuration where:

  • Project settings in forge.yaml take precedence over default settings
  • Any settings not specified in the project configuration inherit from defaults

This approach allows you to customize only the parts of the configuration you need while inheriting sensible defaults for everything else.

Workflow Configuration Structure​

A workflow consists of agents connected via events. Each agent has specific capabilities and can perform designated tasks.

Event System​

Agents communicate through events which they can publish and subscribe to:

Built-in Events​

  • user_task_init - Published when a new task is initiated
  • user_task_update - Published when follow-up instructions are provided by the user

Agent Tools​

Each agent needs tools to perform tasks, configured in the tools field:

Built-in Tools​

  • tool_forge_fs_read - Read from the filesystem
  • tool_forge_fs_create - Create or overwrite files
  • tool_forge_fs_remove - Remove files
  • tool_forge_fs_search - Search for patterns in files
  • tool_forge_fs_list - List files in a directory
  • tool_forge_fs_info - Get file metadata
  • tool_forge_process_shell - Execute shell commands
  • tool_forge_process_think - Perform internal reasoning
  • tool_forge_net_fetch - Fetch data from the internet
  • tool_forge_event_dispatch - Dispatch events to other agents
  • tool_forge_fs_patch - Patch existing files

Agent Configuration Options​

  • id - Unique identifier for the agent
  • model - AI model to use (from the \models list)
  • temperature - Control response determinism and creativity (0.0-2.0)
  • tools - List of tools the agent can use
  • subscribe - Events the agent listens to
  • ephemeral - If true, agent is destroyed after task completion
  • tool_supported - (Optional) Boolean flag that determines whether tools defined in the agent configuration are actually made available to the LLM
  • system_prompt - (Optional) Instructions for how the agent should behave
  • user_prompt - (Optional) Format for user inputs
  • hide_content - (Optional) When true, agent responses aren't displayed in console
  • compact - (Optional) Configuration for automatic context summarization
  • max_walker_depth - (Optional) Maximum directory/file depth for exploration

Built-in Templates​

Forge provides templates to simplify system prompt creation:

  • system-prompt-engineer.hbs - Template for engineering tasks
  • system-prompt-title-generator.hbs - Template for generating descriptive titles
  • system-prompt-advocate.hbs - Template for user advocacy and explanation
  • partial-tool-information.hbs - Tool documentation for agents
  • partial-tool-examples.hbs - Usage examples for tools

Use these templates with the syntax: {{> name-of-the-template.hbs }}

Example Workflow Configuration​

variables:
  models:
    advanced_model: &advanced_model anthropic/claude-3.7-sonnet
    efficiency_model: &efficiency_model anthropic/claude-3.5-haiku

agents:
  - id: title_generation_worker
    model: *efficiency_model
    tools:
      - tool_forge_event_dispatch
    subscribe:
      - user_task_init
    tool_supported: false # Force XML-based tool call formatting
    system_prompt: "{{> system-prompt-title-generator.hbs }}"
    user_prompt: <technical_content>{{event.value}}</technical_content>

  - id: background_researcher
    model: *efficiency_model
    temperature: 0.3 # Lower temperature for more deterministic responses
    hide_content: true # Responses won't appear in console
    tools:
      - tool_forge_net_fetch
      - tool_forge_event_dispatch
      - tool_forge_process_think
    subscribe:
      - research_request
    system_prompt: "{{> system-prompt-researcher.hbs }}"

  - id: developer
    model: *advanced_model
    temperature: 0.7 # Balanced creativity and determinism
    tools:
      - tool_forge_fs_read
      - tool_forge_fs_create
      - tool_forge_fs_remove
      - tool_forge_fs_patch
      - tool_forge_process_shell
      - tool_forge_net_fetch
      - tool_forge_fs_search
      - tool_forge_display_show_user # Rich markdown display tool
    subscribe:
      - user_task_init
      - user_task_update
      - research_results
    max_walker_depth: 1024 # Maximum directory exploration depth
    compact:
      max_tokens: 2000 # Maximum tokens for summary
      token_threshold: 80000 # When to trigger compaction
      model: *efficiency_model
      retention_window: 6 # Recent messages to preserve
    ephemeral: false
    tool_supported: true # Use model's native tool call format (default)
    system_prompt: "{{> system-prompt-engineer.hbs }}"
    user_prompt: |
      <task>{{event.value}}</task>

This example workflow creates three agents:

  1. A title generation worker that creates meaningful titles for user conversations
  2. A background researcher that fetches information without displaying its work in the console
  3. A developer agent that can perform comprehensive file and system operations with context compaction enabled

Advanced Configuration Examples​

Context Compaction Configuration​

Enable automatic context management to maintain lengthy conversations:

agents:
  - id: assistant
    model: anthropic/claude-3.5-sonnet
    compact:
      max_tokens: 2000 # Maximum tokens for summary
      token_threshold: 80000 # When to trigger compaction
      model: google/gemini-2.0-flash-001 # Fast model for summarization
      retention_window: 6 # Recent messages to preserve
      prompt: "{{> system-prompt-context-summarizer.hbs }}" # Custom prompt

Temperature Configuration​

Control agent creativity and determinism with temperature settings:

agents:
  # Precise, deterministic coding agent
  - id: code_generator
    model: anthropic/claude-3.5-sonnet
    temperature: 0.1 # Very deterministic for consistent code

  # Balanced general assistant
  - id: assistant
    model: anthropic/claude-3.5-sonnet
    temperature: 0.7 # Default balanced setting

  # Creative content generator
  - id: creative_writer
    model: anthropic/claude-3.5-sonnet
    temperature: 1.2 # Higher creativity for brainstorming

Agent Visibility Control​

Hide background agent responses from the console:

agents:
  # Background helper that works silently
  - id: background_helper
    model: anthropic/claude-3.5-haiku
    hide_content: true

  # Main agent that displays its responses
  - id: main_agent
    model: anthropic/claude-3.5-sonnet
    # hide_content defaults to false

Rich Display Configuration​

Enable formatted markdown display to users:

agents:
  - id: presenter
    model: anthropic/claude-3.5-sonnet
    tools:
      - tool_forge_display_show_user # Required for rich display
      # Other tools...