> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentgate.mynewapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Convergence
> Understanding convergence strategies - how AgentGate determines when a task is complete
# 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:
**Run exactly N iterations**
The simplest strategy. Runs a predetermined number of iterations regardless of outcome.
```yaml theme={null}
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 progressing**
Runs a base number of iterations, then continues with bonus iterations if the agent is making progress toward the goal.
```yaml theme={null}
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:**
1. Run `baseIterations` attempts
2. Calculate progress score (0-1) based on gate results
3. If score >= `progressThreshold`, grant bonus iterations
4. Continue until all gates pass or limits reached
**Continue until agent signals done or loop detected**
Named after the "Ralph" algorithm, this strategy continues until the agent indicates completion or until similarity detection identifies a loop.
```yaml theme={null}
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:**
1. Track similarity between recent agent outputs
2. If outputs are too similar (below threshold), detect loop
3. If agent signals completion, verify with gates
4. Stop on loop detection, gate passage, or limits
**ML-based strategy (future)**
Uses machine learning to predict optimal iteration counts based on historical data.
```yaml theme={null}
convergence:
strategy: adaptive
config:
modelId: "cost-optimized-v1"
```
Adaptive strategy is planned for future releases and not yet available.
**Human decides each iteration**
Pauses after each iteration for human review and decision.
```yaml theme={null}
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:
```yaml theme={null}
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:
```typescript theme={null}
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:
```bash theme={null}
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:
```json theme={null}
{
"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:
```json theme={null}
{
"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
**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
```yaml theme={null}
convergence:
strategy: fixed
config:
iterations: 3
limits:
maxIterations: 5
```
**Use hybrid when:**
* Tasks have variable complexity
* You want to balance cost and completion
* Progress is measurable through gates
* Most common choice for production
```yaml theme={null}
convergence:
strategy: hybrid
config:
baseIterations: 3
bonusIterations: 5
progressThreshold: 0.6
limits:
maxIterations: 15
maxWallClock: "1h"
```
**Use ralph when:**
* Tasks are complex or open-ended
* Agent needs flexibility to explore
* Loop detection is important
* You trust the agent's judgment
```yaml theme={null}
convergence:
strategy: ralph
config:
convergenceThreshold: 0.05
windowSize: 4
minIterations: 2
limits:
maxIterations: 50
maxWallClock: "4h"
maxCost: "$100"
```
**Use manual when:**
* Changes require human approval
* Learning how the agent behaves
* Compliance requires oversight
* High-risk or sensitive code
```yaml theme={null}
convergence:
strategy: manual
limits:
maxIterations: 20
maxWallClock: "24h"
```
## Convergence with Gates
Convergence strategies work with [gates](/concepts/gates) to determine completion:
```yaml theme={null}
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
1. **All gates pass** → Task complete, stop iterating
2. **Some gates fail with `iterate`** → Generate feedback, continue
3. **Any gate fails with `stop`** → Task failed, stop immediately
4. **Limits reached** → Task failed, stop with partial results
## Best Practices
For most tasks, `hybrid` provides the best balance. Start with conservative settings and adjust based on results.
```yaml theme={null}
strategy: hybrid
config:
baseIterations: 3
bonusIterations: 3
progressThreshold: 0.7
```
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 |
Use the strategy state API to monitor convergence:
```bash theme={null}
watch -n 10 'curl -s .../runs/run_123/strategy-state | jq .trend'
```
After completing several tasks, review convergence patterns:
* Tasks completing too early? Lower `progressThreshold`
* Wasting iterations? Raise `progressThreshold`
* Loop detection triggering? Adjust `convergenceThreshold`
## Related
Configure convergence within TaskSpec
Define verification checkpoints
Monitor iteration progress
Optimize convergence settings