Supervision Layer
Stop trusting agents to police themselves. Supervision Layer wraps every tool call in timeouts, circuit breakers, and audit logs — enforcement the agent cannot bypass.
Before vs After
| Without Supervision | With Supervision | |
|---|---|---|
| Runaway calls | Agent loops infinitely on a failing API | Circuit breaker trips after 3 failures |
| Stuck sessions | Tool hangs silently, agent waits forever | Timeout kills it after 30s |
| Audit trail | No record of what happened | Every call logged with timestamp, outcome, cost |
| Crash loops | Subagent restarts infinitely | After 3 crashes, marked permanently failed |
Quick Start
from supervision import get_supervisor
supervisor = get_supervisor()
result = await supervisor.execute(
tool="web_fetch",
fn=fetch_fn,
agent_id="worker-1",
session_id="sess-abc",
)
Components
- TimeoutWrapper — Per-tool configurable timeouts (default 30s)
- CircuitBreaker — 3-state machine (CLOSED → OPEN → HALF_OPEN)
- AuditLogger — Structured JSONL logging, 50MB rotation, queryable
- CrashLoopProtector — Track restarts, mark failed after 3 within window
- SupervisedCall — All-in-one: crash check → circuit check → audit → timeout → audit
Testing
cd scripts/ && python -m pytest test_supervision.py -v
58 tests. 0 external dependencies. Works with any async Python project.
License
MIT