Convergence

Convergence is the process by which AgentGate determines when an agent has successfully completed a task. Instead of simply running a fixed number of iterations, convergence strategies intelligently decide when to continue iterating, when to stop, and how to interpret progress.

What Is Convergence

Traditional automation runs for a predetermined number of attempts. Convergence goes further by:

Detecting completion: Recognizing when the agent has achieved the desired state
Measuring progress: Tracking improvements across iterations
Preventing loops: Identifying when the agent is stuck in repetitive behavior
Optimizing cost: Stopping when further iterations are unlikely to help

Convergence Strategies

AgentGate supports five convergence strategies:

Fixed
Hybrid
Ralph
Adaptive
Manual

Run exactly N iterationsThe simplest strategy. Runs a predetermined number of iterations regardless of outcome.

convergence:
  strategy: fixed
  config:
    iterations: 5

Best for:

Simple tasks with predictable completion
Cost-controlled environments
Testing and debugging

Limitations:

May waste iterations on already-completed tasks
May stop before completion on complex tasks

Base iterations + bonus if progressingRuns a base number of iterations, then continues with bonus iterations if the agent is making progress toward the goal.

convergence:
  strategy: hybrid
  config:
    baseIterations: 3       # Guaranteed iterations
    bonusIterations: 5      # Extra iterations if progressing
    progressThreshold: 0.7  # Progress score needed (0-1)

Best for:

Most general-purpose tasks
Balancing cost with completion
Tasks with variable complexity

How it works:

Run baseIterations attempts
Calculate progress score (0-1) based on gate results
If score >= progressThreshold, grant bonus iterations
Continue until all gates pass or limits reached

Continue until agent signals done or loop detectedNamed after the “Ralph” algorithm, this strategy continues until the agent indicates completion or until similarity detection identifies a loop.

convergence:
  strategy: ralph
  config:
    convergenceThreshold: 0.05  # Similarity threshold (lower = more sensitive)
    windowSize: 3               # Recent outputs to compare
    minIterations: 2            # Minimum before allowing termination
    promptHotReload: true       # Allow prompt updates mid-run

Best for:

Complex, multi-step tasks
Open-ended development work
Tasks requiring agent judgment

How it works:

Track similarity between recent agent outputs
If outputs are too similar (below threshold), detect loop
If agent signals completion, verify with gates
Stop on loop detection, gate passage, or limits

ML-based strategy (future)Uses machine learning to predict optimal iteration counts based on historical data.

convergence:
  strategy: adaptive
  config:
    modelId: "cost-optimized-v1"

Adaptive strategy is planned for future releases and not yet available.

Human decides each iterationPauses after each iteration for human review and decision.

convergence:
  strategy: manual

Best for:

High-stakes changes
Learning agent behavior
Compliance requirements

Configuration Options

Strategy-Specific Options

Strategy	Option	Type	Default	Description
fixed	`iterations`	number	3	Exact iteration count
hybrid	`baseIterations`	number	3	Guaranteed iterations
hybrid	`bonusIterations`	number	2	Extra iterations if progressing
hybrid	`progressThreshold`	number	0.7	Progress score needed (0-1)
ralph	`convergenceThreshold`	number	0.05	Similarity threshold
ralph	`windowSize`	number	3	Outputs to compare
ralph	`minIterations`	number	1	Minimum before termination
ralph	`promptHotReload`	boolean	false	Allow prompt updates

Resource Limits

Every convergence configuration should include limits:

convergence:
  strategy: hybrid
  limits:
    maxIterations: 10        # Hard cap on iterations
    maxWallClock: "2h"       # Maximum elapsed time
    maxCost: "$50"           # Maximum cost budget
    maxTokens: 1000000       # Total token budget

Always set maxIterations to prevent runaway costs. The default of 100 may be too high for your use case.

Convergence State

During execution, AgentGate tracks convergence state:

interface ConvergenceState {
  iteration: number;           // Current iteration (1-based)
  elapsed: number;             // Elapsed time in milliseconds
  gateResults: GateResult[];   // Results from current iteration
  history: IterationHistory[]; // Previous iteration data
  trend: 'improving' | 'stagnant' | 'regressing';
}

You can query this state via the API:

curl https://agentgate.mynewapi.com/v1/runs/run_123/strategy-state \
  -H "Authorization: Bearer YOUR_API_KEY"

Convergence Decisions

Each iteration ends with a convergence decision:

{
  "continue": true,
  "reason": "Progress detected: 3/5 gates now passing (was 1/5)",
  "confidence": 0.85,
  "metadata": {
    "gatesPassing": 3,
    "gatesTotal": 5,
    "progressScore": 0.6
  }
}

Field	Description
`continue`	Whether to run another iteration
`reason`	Human-readable explanation
`confidence`	How confident the strategy is (0-1)
`metadata`	Strategy-specific details

Progress Metrics

AgentGate calculates progress metrics across iterations:

{
  "overall": 0.75,
  "byGate": {
    "lint": { "currentLevel": 1.0, "previousLevel": 0.8, "trend": "improving" },
    "tests": { "currentLevel": 0.5, "previousLevel": 0.3, "trend": "improving" },
    "ci": { "currentLevel": 0.0, "previousLevel": 0.0, "trend": "stagnant" }
  },
  "trend": "improving",
  "velocity": 0.15
}

Understanding Trends

Trend	Meaning	Action
`improving`	Gates passing at increasing rate	Continue iterations
`stagnant`	No change in gate passage	Consider stopping
`regressing`	Gates that passed are now failing	Investigate agent behavior

Choosing a Strategy

When to use Fixed

Use fixed when:

You have a well-understood task
Cost predictability is important
You’re testing or debugging
Tasks typically complete in 1-3 iterations

convergence:
  strategy: fixed
  config:
    iterations: 3
  limits:
    maxIterations: 5

When to use Hybrid

Use hybrid when:

Tasks have variable complexity
You want to balance cost and completion
Progress is measurable through gates
Most common choice for production

convergence:
  strategy: hybrid
  config:
    baseIterations: 3
    bonusIterations: 5
    progressThreshold: 0.6
  limits:
    maxIterations: 15
    maxWallClock: "1h"

When to use Ralph

Use ralph when:

Tasks are complex or open-ended
Agent needs flexibility to explore
Loop detection is important
You trust the agent’s judgment

convergence:
  strategy: ralph
  config:
    convergenceThreshold: 0.05
    windowSize: 4
    minIterations: 2
  limits:
    maxIterations: 50
    maxWallClock: "4h"
    maxCost: "$100"

When to use Manual

Use manual when:

Changes require human approval
Learning how the agent behaves
Compliance requires oversight
High-risk or sensitive code

convergence:
  strategy: manual
  limits:
    maxIterations: 20
    maxWallClock: "24h"

Convergence with Gates

Convergence strategies work with gates to determine completion:

convergence:
  strategy: hybrid
  config:
    baseIterations: 3
    progressThreshold: 0.7

  gates:
    - name: lint
      check:
        type: verification-levels
        levels: [L0, L1]
      onFailure:
        action: iterate

    - name: tests
      check:
        type: verification-levels
        levels: [L2]
      onFailure:
        action: iterate

    - name: ci
      check:
        type: github-actions
      onFailure:
        action: stop  # Don't retry CI failures

Gate Interaction

All gates pass → Task complete, stop iterating
Some gates fail with iterate → Generate feedback, continue
Any gate fails with stop → Task failed, stop immediately
Limits reached → Task failed, stop with partial results

Best Practices

Start with Hybrid

For most tasks, hybrid provides the best balance. Start with conservative settings and adjust based on results.

strategy: hybrid
config:
  baseIterations: 3
  bonusIterations: 3
  progressThreshold: 0.7

Set Reasonable Limits

Always set limits to control costs. Consider your task complexity:

Task Type	Recommended Max
Simple fix	5 iterations
Feature	10-15 iterations
Complex feature	20-30 iterations
Major refactor	50+ iterations

Monitor Progress

Use the strategy state API to monitor convergence:

watch -n 10 'curl -s .../runs/run_123/strategy-state | jq .trend'

Adjust Based on Results

After completing several tasks, review convergence patterns:

Tasks completing too early? Lower progressThreshold
Wasting iterations? Raise progressThreshold
Loop detection triggering? Adjust convergenceThreshold

TaskSpec

Configure convergence within TaskSpec

Gates

Define verification checkpoints

Runs

Monitor iteration progress

Best Practices

Optimize convergence settings

​Convergence

​What Is Convergence

​Convergence Strategies

​Configuration Options

​Strategy-Specific Options

​Resource Limits

​Convergence State

​Convergence Decisions

​Progress Metrics

​Understanding Trends

​Choosing a Strategy

​Convergence with Gates

​Gate Interaction

​Best Practices

​Related

TaskSpec

Gates

Runs

Best Practices

Convergence

What Is Convergence

Convergence Strategies

Configuration Options

Strategy-Specific Options

Resource Limits

Convergence State

Convergence Decisions

Progress Metrics

Understanding Trends

Choosing a Strategy

Convergence with Gates

Gate Interaction

Best Practices

Related