Skip to main content

Agent Configuration

Forge provides extensive configuration options for AI agents, allowing you to tailor their behavior to your specific needs. This guide covers all available agent configuration options with examples and best practices.

Core Agent Configuration​

In your forge.yaml file, agents are defined under the agents section:

agents:
  - id: assistant
    model: anthropic/claude-3.5-sonnet
    system_prompt: "{{> system-prompt.hbs }}"

Basic Configuration Parameters​

ParameterRequiredDescription
idYesUnique identifier for the agent
modelYesAI model to use (e.g., anthropic/claude-3.5-sonnet)
system_promptYesSystem prompt or template reference
subscribeNoList of commands the agent should respond to
max_walker_depthNoMaximum directory/file depth for exploration
custom_rulesNoCustom instructions or rules (see Custom Rules)

Temperature Configuration​

Fine-tune the creativity and determinism of agent responses with the temperature setting:

agents:
  - id: assistant
    model: anthropic/claude-3.5-sonnet
    temperature: 0.7

The temperature parameter accepts values between 0.0 and 2.0:

TemperatureDescriptionBest For
0.0 - 0.3Most deterministic, highly consistentCode generation, factual responses
0.4 - 0.7Balanced creativity and consistencyGeneral purpose assistance
0.8 - 1.2Increased creativity and variationCreative writing, brainstorming
1.3 - 2.0Highest creativity, most variedUnconventional ideas, maximum exploration

When to Adjust Temperature​

  • Lower Temperature (0.0 - 0.3) when you need:

    • Precise, reproducible code
    • Factual, consistent responses
    • Technical documentation
    • Structured data outputs

  • Medium Temperature (0.4 - 0.7) when you need:

    • Balanced responses for everyday tasks
    • Natural-sounding text with reasonable variation
    • Problem-solving with some creativity

  • Higher Temperature (0.8 - 2.0) when you need:

    • Creative writing assistance
    • Diverse brainstorming ideas
    • Out-of-the-box thinking
    • Varied solution approaches

Context Compaction​

Control how conversation history is managed with context compaction:

agents:
  - id: assistant
    model: anthropic/claude-3.5-sonnet
    compact:
      max_tokens: 2000
      token_threshold: 80000
      model: google/gemini-2.0-flash-001
      retention_window: 6

For detailed information about context compaction settings, see the Context Compaction documentation.

Agent Visibility Control​

Control whether an agent's outputs are visible in the console with the hide_content setting:

agents:
  - id: background-helper
    model: anthropic/claude-3.5-sonnet
    hide_content: true

When hide_content is set to true:

  • The agent's responses won't appear in the console output
  • The agent will still function normally in the background
  • Other agents can still access its outputs
  • This is useful for "helper" agents that support other primary agents

Best Practices​

  1. Match Temperature to Task: Use lower temperatures for precise tasks and higher for creative ones
  2. Enable Context Compaction: For long-running sessions or complex projects
  3. Use Base Models Appropriately: More capable models for complex reasoning, faster models for simpler tasks
  4. Optimize System Prompts: Use Handlebars templates for dynamic system prompts
  5. Leverage Hidden Agents: Use background agents for auxiliary tasks without cluttering output

Troubleshooting​

Issue: Agent Responses Too Random​

  • Lower the temperature setting
  • Provide more specific instructions in the system prompt
  • Add more detailed custom_rules

Issue: Agent Responses Too Repetitive​

  • Increase the temperature slightly
  • Review and update system prompt to allow more flexibility
  • Check if your instructions are too restrictive

Issue: Agent Not Seeing Full Context​

  • Configure context compaction with higher token limits
  • Increase retention_window to keep more recent messages
  • Use a model with larger context window