agentcontrolroom

🚀 Live Dashboard · ⚡ Quick Start · 📖 SDK Reference · 📦 PyPI · 🛠️ Deployment Guide

🧭 Why Agent Control Room

Autonomous agents fail in ways traditional APM tools were never designed to catch — runaway loops, silent cost overruns, degraded reasoning quality, and multi-step tool chains that are impossible to debug from logs alone.

Agent Control Room (ACR) is an open-source reliability layer purpose-built for agents. Drop it into an existing stack in seconds and immediately get full-fidelity tracing, live cost tracking, and safety guardrails — no code changes required.

# Before ACR — flying blind, must add callbacks everywhere manually
llm = ChatMistralAI(model="mistral-small-2506", callbacks=[acr_cb])
chain.with_config(callbacks=[acr_cb])   # ← tedious, error-prone

# After ACR v0.3.0 — TRUE zero-effort, zero code changes
acr-run python agents.py
# ↑ That's it. Every LLM call, tool, loop, cost → ACR dashboard instantly.

Every LLM call, tool invocation, and agent decision is captured, costed, and monitored in real time. When an agent starts looping, blows through budget, or degrades in quality, ACR flags it before it becomes a production incident.

✨ Features

🔌 Supported Frameworks (v0.4.0) — 13 Frameworks

⭐ New in v0.4.0

Install all integrations at once:

pip install "agentcontrolroom[all]"

Or install only what you need:

pip install "agentcontrolroom[groq]"
pip install "agentcontrolroom[anthropic]"
pip install "agentcontrolroom[gemini]"
pip install "agentcontrolroom[mistral]"

🏗️ Architecture

flowchart TB
    A["🤖 Your AI Agents\nLangChain · CrewAI · AutoGen · LlamaIndex · Custom"] -->|"acr-run python app.py\n(zero code changes)"| B

    subgraph B["🎛️ Agent Control Room"]
        direction TB
        C["📥 Ingest API\n/api/v1/ingest/traces"]
        D["🧪 Groq LLM Judge\nAuto-evaluation"]
        E[("🗄️ PostgreSQL + Redis")]
        F["📊 React Dashboard\nRuns · Spans · Costs · Guardrails"]
        G["🔐 Enterprise Layer\nSSO · Audit Logs · PII Redaction"]

        C --> E
        D --> E
        E --> F
        G --> E
    end

    B --> H["🚨 Guardrail Alerts\nCost · Latency · Loops · Quality"]

    style A fill:#0ea5e9,color:#fff,stroke:#0369a1,stroke-width:2px
    style B fill:#f8fafc,stroke:#6366f1,stroke-width:2px
    style E fill:#6366f1,color:#fff,stroke:#4338ca,stroke-width:2px
    style F fill:#22c55e,color:#fff,stroke:#15803d,stroke-width:2px
    style H fill:#ef4444,color:#fff,stroke:#b91c1c,stroke-width:2px

Stack: FastAPI · SQLAlchemy · PostgreSQL · Redis · Dramatiq · React · Vite · OpenTelemetry

⚡ Quick Start

Get from zero to a fully traced agent in under 60 seconds.

Option 1 — acr-run (TRUE zero-effort, no code changes)

# 1. Install
pip install agentcontrolroom

# 2. Set ONE environment variable — that's all
export ACR_API_KEY=your-api-key-here
# (endpoint defaults to ACR cloud automatically)

# 3. Run your EXISTING, UNMODIFIED project
acr-run python agents.py

What you'll see:

──────────────────────────────────────────────────────
  ACR Auto-Instrumentation Runner  v0.3.0
──────────────────────────────────────────────────────
  Scanning for AI frameworks...

  ✅ LangChain  — global callback injected (zero-effort)
  ✅ LangGraph  — monkey-patched (zero-effort)
  ✅ CrewAI     — monkey-patched (zero-effort)
  ✅ AutoGen    — monkey-patched (zero-effort)
  ✅ LlamaIndex — monkey-patched (zero-effort)
  ✅ OpenAI     — client auto-wrapped (zero-effort)

  6 frameworks instrumented. All traces → ACR dashboard.
──────────────────────────────────────────────────────

Option 2 — Manual (per-framework, one line)

# LangChain / LangGraph
from agentcontrolroom.instruments.langchain import ACRCallbackHandler
llm = ChatMistralAI(model="mistral-small-2506", callbacks=[ACRCallbackHandler()])

# CrewAI
from agentcontrolroom import instrument_crewai
instrument_crewai()   # call before Crew/Agent creation

# AutoGen
from agentcontrolroom import instrument_autogen
instrument_autogen()  # call before creating agents

# LlamaIndex
from agentcontrolroom import instrument_llamaindex
instrument_llamaindex()  # call before using any index/query engine

# OpenAI direct
from agentcontrolroom import wrap_openai
import openai
client = wrap_openai(openai.OpenAI())

Option 3 — Decorator-based (any Python framework)

from agentcontrolroom import trace, configure

configure(api_key="acr-dev-xxxx")

@trace.agent(name="research-agent")
def research(query: str):
    result = my_llm.invoke(query)
    return result

@trace.tool(name="web-search")
def search(query: str):
    return requests.get(f"https://api.search.com?q={query}").json()

Verify Setup

acr-check

==========================================================
  Agent Control Room — System Health Check
==========================================================
  ✅ Backend reachable   (version: 0.3.0)
  ✅ API key valid
  ✅ Test trace ingested (1 span stored)
  ✅ Dashboard reachable
  🎉 All checks passed! (4/4)
==========================================================

🔌 Model Context Protocol (MCP) Server

Connect your AI coding assistants (Cursor, Windsurf, Claude Desktop, Antigravity, VS Code) directly to Agent Control Room. Ask your IDE's assistant to debug failed runs, audit token spend, and inspect traces in chat without leaving your code editor!

1. Cursor Setup (Settings -> MCP -> Add New MCP Server)

• Name: acr
• Type: command
• Command: uvx agentcontrolroom mcp
• Environment Variables:
  • ACR_API_KEY: acr-dev-xxxx
  • ACR_ENDPOINT: https://acr-backend-xlj5.onrender.com

2. Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "acr": {
      "command": "uvx",
      "args": ["agentcontrolroom", "mcp"],
      "env": {
        "ACR_API_KEY": "acr-dev-xxxx",
        "ACR_ENDPOINT": "https://acr-backend-xlj5.onrender.com"
      }
    }
  }
}

3. Available MCP Tools:

• acr_list_runs: List recent agent runs with latency, cost, and status.
• acr_get_run_trace: Fetch full execution tree, child spans, prompts, and completions.
• acr_diagnose_failure: Pinpoint the exact failing span, triggering input, and stack trace so the AI can fix your code.
• acr_get_cost_summary: Analyze token spend across LLM models and detect anomalies.
• acr_list_guardrails: View active budget, latency, and loop detection rules.
• acr_create_guardrail: Create or adjust safety rules via natural language.

Deployment Options

pip install agentcontrolroom
export ACR_API_KEY=<your-key>
# ACR_ENDPOINT defaults to cloud automatically — nothing else needed

git clone https://github.com/Darshan-1812/Helm-AI
cd Helm-AI
cp .env.example .env  # fill in your values
docker compose up -d

Full guide including Railway, VPS, and enterprise VPC setups: docs/deployment.md

📚 Examples

🗂️ Repository Structure

Helm-AI/
├── backend/                    FastAPI + PostgreSQL + Redis
│   ├── app/
│   │   ├── api/                REST endpoints (runs, ingest, guardrails, auth, ...)
│   │   ├── models/             SQLAlchemy ORM models
│   │   ├── services/           Business logic (tracing, eval, cost, PII, ...)
│   │   └── workers/            Dramatiq background workers
│   ├── alembic/                Database migrations
│   └── Dockerfile.prod
├── sdk/                        agentcontrolroom Python package (PyPI)
│   └── src/agentcontrolroom/
│       ├── instruments/
│       │   ├── langchain.py    LangChain + LangGraph handler
│       │   ├── crewai.py       CrewAI monkey-patcher
│       │   ├── autogen.py      AutoGen / AG2 monkey-patcher
│       │   ├── llamaindex.py   LlamaIndex monkey-patcher  ← NEW v0.3.0
│       │   └── openai.py       OpenAI client wrapper
│       ├── tracer.py           @trace.agent / @trace.tool decorators
│       ├── guardrails.py       Client-side guardrail engine
│       ├── cost.py             Token cost calculator (OpenAI/Anthropic/Mistral/...)
│       └── _cli.py             acr-check + acr-run CLI  ← NEW v0.3.0
├── frontend/                   React + Vite dashboard
│   └── src/components/
│       └── DashboardView.tsx   Main dashboard (Traces, Cost, Guardrails, Agents, ...)
├── sdk-node/                   @agentcontrolroom/node TypeScript SDK
├── docs/                       Documentation
├── examples/                   Working code examples
├── render.yaml                 One-click Render deploy
└── docker-compose.yml          Local development

🕒 Changelog

📖 Documentation

• Quick Start Guide — up and running in 60 seconds
• SDK Reference — full API documentation
• LangChain Integration — deep dive into LangChain support
• Guardrails Setup — cost limits, loop detection, quality gates
• Enterprise & Security — SSO, audit logs, PII redaction, SOC 2
• Deployment Guide — all deployment options
• FAQ — common questions answered

📄 Citation

If you use Agent Control Room in research or production, please cite:

@software{agentcontrolroom2026,
  author  = {Darshan Girase},
  title   = {Agent Control Room: Reliability Layer for Autonomous AI Agents},
  year    = {2026},
  url     = {https://github.com/Darshan-1812/Helm-AI},
  version = {0.3.0}
}

📜 License

MIT License — see LICENSE for details.