Quickstart

Protect your AI agent in 4 simple steps.

Prerequisites

Python 3.12+
Docker

Quick setup (no repo cloning required) - Copy this into your terminal or directly paste into your coding agent to start the Agent Control server, UI:

curl -L https://raw.githubusercontent.com/agentcontrol/agent-control/refs/heads/main/docker-compose.yml | docker compose -f - up -d

Then, install sdk in your virtual env:

uv venv
source .venv/bin/activate
uv pip install agent-control-sdk

What this does:

✅ Starts Agent Control server at http://localhost:8000
✅ Starts UI dashboard at http://localhost:8000
✅ Installs Python SDK (agent-control-sdk)

Next: Jump to Step 3: Register your agent

Alternatively, for local development with the Agent Control repository, clone the repo and follow all steps below.

Step 1: Start the Agent Control Server

Startup AgentControl server manually for local development.

Local development (cloning the repo)

Prerequisites:

uv — Fast Python package manager (curl -LsSf https://astral.sh/uv/install.sh | sh)
Node.js 18+ — For the web dashboard (optional)

# Clone the repository (contains the server)

git clone https://github.com/agentcontrol/agent-control.git
cd agent-control

# Install dependencies

make sync

# Start the Agent Control server (boots Postgres + runs migrations)

make server-run

# Start the UI (in a separate shell)

make ui-install
make ui-dev

Server runs at http://localhost:8000 ✅
UI runs at http://localhost:4000 ✅

💡 Verify the server: Open http://localhost:8000/health — you should see {"status": "healthy", "version": "..."}.

Step 2: Install the SDK

In your agent application project:

uv pip install agent-control-sdk

Step 3: Register Your Agent

Agent must be registered with the server. You should also add @control decorator around tools and LLM call functions. Here is a contrived example. Reference our Examples for real world examples for specific frameworks.

# my_agent.py

import asyncio
import agent_control
from agent_control import control, ControlViolationError

# Protect any function (like LLM calls)

@control()
async def chat(message: str) -> str:
    # In production: response = await LLM.ainvoke(message)
    # For demo: simulate LLM that might leak sensitive data
    if "test" in message.lower():
        return "Your SSN is 123-45-6789"  # Will be blocked!
    return f"Echo: {message}"

# Initialize your agent

agent_control.init(
    agent_name="awesome_bot_3000",  # Unique name
    agent_description="My Chatbot",
)

async def main():
    try:
        print(await chat("test"))  # ❌ Blocked
    except ControlViolationError as e:
        print(f"❌ Blocked: {e.control_name}")

asyncio.run(main())

Step 4: Add Controls

The easiest way to add controls is through the UI — see the UI Quickstart for a step-by-step guide. Alternatively, use the SDK as shown below or call the API directly. Run following setup script to create controls to protect your agent.

# setup.py - Run once to configure agent controls

import asyncio
from datetime import datetime, UTC
from agent_control import AgentControlClient, controls, agents
from agent_control_models import Agent

async def setup():
    async with AgentControlClient() as client:  # Defaults to localhost:8000
        # 1. Register agent first
        agent = Agent(
            agent_name="awesome_bot_3000",
            agent_description="My Chatbot",
            agent_created_at=datetime.now(UTC).isoformat(),
        )
        await agents.register_agent(client, agent, steps=[])

        # 2. Create control (blocks SSN patterns in output)
        control = await controls.create_control(
            client,
            name="block-ssn",
            data={
                "enabled": True,
                "execution": "server",
                "scope": {"stages": ["post"]},
                "condition": {
                    "selector": {"path": "output"},
                    "evaluator": {
                        "name": "regex",
                        "config": {"pattern": r"\b\d{3}-\d{2}-\d{4}\b"},
                    },
                },
                "action": {"decision": "deny"},
            },
        )

        # 3. Associate control directly with agent
        await agents.add_agent_control(
            client,
            agent_name=agent.agent_name,
            control_id=control["control_id"],
        )

        print("✅ Setup complete!")
        print(f"   Control ID: {control['control_id']}")

asyncio.run(setup())

Controls store leaf selector and evaluator definitions under condition, which also enables composite and, or, and not trees. Now, run your agent code. 🎉 Done! Your agent now blocks SSN patterns automatically.

[!NOTE] Authentication Note: Authentication is disabled by default in the server .env (AGENT_CONTROL_API_KEY_ENABLED=false). If you enable it, this setup script needs an admin API key because it creates a control and attaches it to an agent. agents.register_agent() accepts a regular or admin key, but controls.create_control() and agents.add_agent_control() require a key listed in AGENT_CONTROL_ADMIN_API_KEYS. In the example .env, the placeholders are:

Regular API key(s): AGENT_CONTROL_API_KEYS (e.g., “my-ui-key”)

Admin API key(s): AGENT_CONTROL_ADMIN_API_KEYS (e.g., “my-admin-key”)

Replace these defaults before any shared or production deployment.

With authentication enabled:

curl -L https://raw.githubusercontent.com/agentcontrol/agent-control/refs/heads/main/docker-compose.yml | AGENT_CONTROL_API_KEY_ENABLED=true AGENT_CONTROL_API_KEYS="my-ui-key" AGENT_CONTROL_ADMIN_API_KEYS="my-admin-key" AGENT_CONTROL_SESSION_SECRET="some-long-random-string" CORS_ORIGINS="http://localhost:4000" docker compose -f - up -d

What Is Happening Under the Hood

Your app calls chat("test")
Function executes and returns "Your SSN is 123-45-6789"
@control() decorator sends output to Agent Control server
Server checks the output against all controls
block-ssn control finds SSN pattern → matches
Server returns is_safe=False with the matched control
SDK raises ControlViolationError and blocks the response

Key Benefits:

✅ Controls are managed separately from your code
✅ Update controls without redeploying your agent
✅ Same controls can protect multiple agents
✅ View analytics and control execution in the dashboard

Performance

Endpoint	Scenario	RPS	p50	p99
Agent init	Agent with 3 tool steps	509	19 ms	54 ms
Evaluation	1 control, 500-char content	437	36 ms	61 ms
Evaluation	10 controls, 500-char content	349	35 ms	66 ms
Evaluation	50 controls, 500-char content	199	63 ms	91 ms
Controls refresh	5-50 controls per agent	273-392	20-27 ms	27-61 ms

Agent init handles both create and update identically (create-or-update operation).
All four built-in evaluators (regex, list, JSON, SQL) perform within 40-46 ms p50 at 1 control.
Moving from 1 to 50 controls increased evaluation p50 by about 27 ms.
Local laptop benchmarks are directional and intended for developer reference. They are not production sizing guidance.

Performance tested on Apple M5 (16 GB RAM), Docker Compose (postgres:16 + agent-control). 2 minutes per scenario, 5 concurrent users for latency (p50, p99), 10-20 for throughput (RPS). RPS = completed requests per second. All scenarios completed with 0% errors.

Configuration

Environment Variables

Variable	Default	Description
`AGENT_CONTROL_URL`	`http://localhost:8000`	Server URL for SDK
`AGENT_CONTROL_API_KEY`	—	API key for authentication (if enabled)
`DB_URL`	`postgresql+psycopg://agent_control:agent_control@localhost:5432/agent_control`	Database connection string (SQLite: `sqlite+aiosqlite:///./agent_control.db`)
`GALILEO_API_KEY`	—	Required for Luna-2 AI evaluator

Server Configuration

The server supports additional environment variables:

AGENT_CONTROL_API_KEY_ENABLED - Enable API key authentication (default: false)
AGENT_CONTROL_API_KEYS - Valid API keys for runtime/read access when auth is enabled
AGENT_CONTROL_ADMIN_API_KEYS - Admin API keys required for control-plane mutations
LOG_LEVEL - Logging level (default: INFO)

See Server Docs for complete server configuration.

Agent Control Components

Agent Control is built as a monorepo with these components:

Server - FastAPI server handling control evaluation, agent registration, and analytics
Engine - Evaluation engine that orchestrates control checks and applies actions
Models - Shared data models and schemas used across all components
Evaluators - Built-in and AI-powered evaluators (regex, list, JSON, SQL, Luna-2)
UI - Next.js dashboard for managing controls, agents, and viewing analytics
SDKs - Python and TypeScript client libraries for integrating with your agents

Development

Directory Structure

agent-control/
├── sdks/python/     # Python SDK (agent-control)
├── sdks/typescript/ # TypeScript SDK (generated)
├── server/          # FastAPI server (agent-control-server)
├── engine/          # Evaluation engine (agent-control-engine)
├── models/          # Shared models (agent-control-models)
├── evaluators/      # Evaluator implementations (agent-control-evaluators)
├── ui/              # Next.js web dashboard
├── scripts/         # Build scripts
└── examples/        # Usage examples

Makefile Commands

The project uses a Makefile for common tasks:

Command	Description
`make sync`	Install dependencies for all workspace packages
`make test`	Run tests across all packages
`make lint`	Run ruff linting
`make lint-fix`	Run ruff with auto-fix
`make typecheck`	Run mypy typechecking
`make check`	Run all quality checks (test + lint + typecheck)
`make server-run`	Start the server
`make server-<target>`	Forward commands to server (e.g., `make server-alembic-upgrade`)
`make sdk-<target>`	Forward commands to SDK (e.g., `make sdk-test`)
`make engine-<target>`	Forward commands to engine (e.g., `make engine-test`)

Next Steps

Add more controls: See Controls for examples and guidance
Explore evaluators: See Evaluators or create custom evaluators. See DeepEval example for custom evaluator examples
Production setup: Enable authentication — see the Reference
Check examples: See Examples for real-world patterns

💡 Pro Tip: Start with simple regex controls, then graduate to AI-powered evaluators for complex safety checks.

Getting Started

Concepts

How-to Guides

Integrations

Examples

Reference

Prerequisites

Step 1: Start the Agent Control Server

Local development (cloning the repo)

Step 2: Install the SDK

Step 3: Register Your Agent

Step 4: Add Controls

What Is Happening Under the Hood

Performance

Configuration

Environment Variables

Server Configuration

Agent Control Components

Development

Directory Structure

Makefile Commands

Next Steps

What’s Next

Concepts

Examples

Getting Started

Concepts

How-to Guides

Integrations

Examples

Reference

​Prerequisites

​Step 1: Start the Agent Control Server

​Local development (cloning the repo)

​Step 2: Install the SDK

​Step 3: Register Your Agent

​Step 4: Add Controls

​What Is Happening Under the Hood

​Performance

​Configuration

​Environment Variables

​Server Configuration

​Agent Control Components

​Development

​Directory Structure

​Makefile Commands

​Next Steps

​What’s Next

Concepts

Examples

Prerequisites

Step 1: Start the Agent Control Server

Local development (cloning the repo)

Step 2: Install the SDK

Step 3: Register Your Agent

Step 4: Add Controls

What Is Happening Under the Hood

Performance

Configuration

Environment Variables

Server Configuration

Agent Control Components

Development

Directory Structure

Makefile Commands

Next Steps

What’s Next