---
title: agent-loop — FORGE Self-Improvement Orchestrator
emoji: 🔄
colorFrom: blue
colorTo: red
sdk: docker
pinned: true
license: mit
short_description: Feedback loop — trace→learn→propose→approve→deploy
---

# 🔄 agent-loop
### FORGE Self-Improvement Orchestrator

Closes the feedback loop. Runs on a configurable cron interval, detects underperforming agents,
generates improved system prompts via NEXUS, creates drafts in agent-prompts, and notifies you
for approval. **Never auto-deploys — every change requires human approval.**

## Improvement pipeline

```
TRACE ──(events)──▶ LEARN ──(scored)──▶ LOOP
                                          │
                              NEXUS ◀──(generate proposal)
                                │
                          PROMPTS ◀──(POST draft, status=draft)
                                │
                        RELAY ◀──(Telegram notify)
                                │
                       YOU ──(approve via dashboard or API)
                                │
                    PROMPTS persona updated → agents fetch at next startup
```

## Decision thresholds

| Condition | Action |
|-----------|--------|
| `avg_reward < REWARD_THRESHOLD (0.2)` | Generate improvement proposal |
| `error_rate > ERROR_ESCALATE (15%)` | Mark critical, escalate via RELAY |
| `reward_delta < 0.05` after 24h | Mark cycle inconclusive |
| `reward_delta > 0.05` after 24h | Mark cycle successful |

## REST API

```
POST /api/cycle                     Trigger a cycle manually
GET  /api/cycles                    List recent cycles
GET  /api/proposals                 List proposals (state, agent filters)
POST /api/proposals/{id}/approve    Approve → deploy to agent-prompts
POST /api/proposals/{id}/reject     Reject proposal
GET  /api/health/agents             Agent health snapshot
GET  /api/stats                     Loop statistics
```

## MCP

```
GET /mcp/sse · POST /mcp

Tools: loop_status, loop_trigger, loop_proposals, loop_approve,
       loop_reject, loop_health, loop_cycles
```

## Secrets

| Key | Description |
|-----|-------------|
| `LOOP_KEY` | Optional write auth (X-Loop-Key header) |
| `LEARN_URL` | `https://chris4k-agent-learn.hf.space` |
| `TRACE_URL` | `https://chris4k-agent-trace.hf.space` |
| `PROMPTS_URL` | `https://chris4k-agent-prompts.hf.space` |
| `NEXUS_URL` | `https://chris4k-agent-nexus.hf.space` |
| `RELAY_URL` | `https://chris4k-agent-relay.hf.space` |
| `CYCLE_MINUTES` | Default: `60` |
| `REWARD_THRESHOLD` | Default: `0.2` |
| `CYCLE_ENABLED` | Set `false` to pause |

Built by [Chris4K](https://huggingface.co/Chris4K) — ki-fusion-labs.de