DEADLOOP 為 AI 智能體提供本地優先可靠性與安全監控

https://github.com/Senthil455/DeadLoop

This Halloween I built DEADLOOP: a reliability and safety monitor for AI agents that detects when they get trapped in repetitive tool calls, unproductive loops, or circular workflows. It records execution traces, raises evidence-backed incidents, and lets a human acknowledge, resolve, dismiss, or request a pause. The core is fully deterministic; an optional open-weight model only explains the findings. It never changes a finding or executes an intervention.

What I built

DEADLOOP is a monitor, not an agent framework. Your agent keeps running as-is. DEADLOOP ingests its tool-call trace and answers:

• Is this repetition, or legitimate retrying?
• What exactly supports that conclusion?
• What should a human look at first?
• Can we stop the run without claiming control we do not have?

Detectors:

• Exact repetition
• Near-duplicate repetition
• A-B-A-B oscillation
• Repeated failure
• Explicit no-progress
• Session budgets (tool calls, duration, tokens, cost)

Every incident cites real event IDs, the observed sequence, measured metrics, confidence basis, and stated uncertainty. Risk scores are heuristics in [0, 100], not probabilities.

The spooky part

Every developer has watched an agent whisper the same command into the void over and over, burning tokens while nothing moves. DEADLOOP is the thing in the machine that notices the ghost repeating itself and breaks the cycle. It is not a horror game aesthetic; it is a forensic one: dark, precise, and readable.

Why open innovation matters for this

The open pieces are what make the project work:

• It runs offline. Detection, risk scoring, ingestion, and incident management are deterministic and local. No API key is required for the core product to function.
• It keeps data off servers you do not control. Execution traces can contain tool arguments, outputs, and errors. DEADLOOP redacts credential-shaped fields at two layers: the SDK before transport, and the backend before storage. Raw ingestion keys are never returned after creation.
• It is not locked inside a disappearing service. The stack is FastAPI, SQLAlchemy, SQLite/PostgreSQL, React, and Vite. The detector never depends on a hosted model. If the optional AI provider is disabled, slow, or returns invalid output, the deterministic explanation remains available.
• Optional open-weight AI. Explanations can use an OpenAI-compatible endpoint, verified with Gemma 2 2B through Ollama. No API key is required for a local endpoint. Detection remains on-device either way.
• Cost. The basic product requires no paid external services.

Where the open-based approach worked better than a closed one: a closed tracing service would show that calls happened, but it would not let me keep traces local, swap or disable the model, or explain exactly why a finding occurred. DEADLOOP can run with the internet off and still tell you what happened.

Demo walkthrough

The sample simulator generates real execution events through the same ingestion, persistence, detection, and incident paths as production. The exact-repetition scenario creates four identical failing calls and produces both exact-repetition and repeated-failure findings. Evidence references the real event IDs; you can open the incident, inspect the timeline, acknowledge it, request a pause, approve it, and verify the simulator acknowledges it.

Code that matters

# Send one event from any agent
from deadloop import DeadLoopClient

client = DeadLoopClient(
    endpoint="http://127.0.0.1:8000",
    api_key="dl_...",
)
client.send_event(
    agent_id="research-agent",
    session_id="run-42",
    tool_name="search_web",
    action="Search",
    input={"query": "database connection error"},
    output={"results": 3},
    status="success",
    progress=True,
)

# Run the backend
cd backend
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python -m alembic -c alembic.ini upgrade head
$env:DEADLOOP_ADMIN_TOKEN = "choose-a-long-random-token"
$env:DEADLOOP_AUTO_CREATE = "0"
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000

# Build the frontend
cd frontend
npm ci
npm run build

Open http://127.0.0.1:8000 and sign in with the configured admin token.

Verification

• Backend pytest: 62 passed, 0 failed
• SDK pytest: 8 passed, 0 failed
• Frontend Vitest: 8 passed, 0 failed
• Frontend production build: passed
• Clean-database Alembic migration: passed, 11 tables
• Live API acceptance workflow: passed with 0 failures

Security notes

• Secrets are not hardcoded; they come from environment variables.
• Inputs and configuration values are validated.
• Protected endpoints enforce authorization on the backend.
• Intervention operations require approval and are audited.
• External AI data transfer requires explicit configuration.
• Known limitations are documented, including single-node scope, no multi-tenant RBAC, and no built-in TLS.