Quickstart

Install Agent Control, start the server, and protect your first agent in minutes.

Protect your AI agent in 4 simple steps.

Prefer a full demo walkthrough? See the complete Agent Control Demo for an end-to-end, runnable alternative.

Prerequisites

• Python 3.12+

• Docker — For running PostgreSQL

Step 1: Start the Agent Control Server

Choose one of the following setups.

Option A — SDK-only (fastest)

Install the SDK in your project:

pip install agent-control-sdk

Run the Agent Control server and PostgreSQL database via Docker Compose:

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

Server runs at http://localhost:8000 ✅

Option B — Local development

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: Register Your Agent

Agent must be registered with the server. You should also add the @control() decorator around tools and LLM call functions.

# 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",
)

# Test it

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

asyncio.run(main())

Step 3: Add Controls

The easiest way to add controls is to use the UI. You can also use the SDK or directly call the API.

# 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"]},
                "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())

In your Agent application directory (not inside the agent-control repo):

uv venv
uv .venv/bin/activate
uv pip install agent-control-sdk
uv run setup.py

Step 4: Run Your Agent

uv run my_agent.py

🎉 Done! Your agent now blocks SSN patterns automatically.

What’s Happening Under the Hood

1. Your app calls chat("test")

2. Function executes and returns "Your SSN is 123-45-6789"

3. @control() decorator sends output to Agent Control server

4. Server checks the output against all controls

5. block-ssn control finds SSN pattern → matches

6. Server returns is_safe=False with the matched control

7. 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

Next Steps

• Add more controls: See Controls for examples and guidance

• Explore evaluators: Try AI-powered evaluators like Luna-2 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.

What’s Next

Concepts

Learn about controls, selectors, evaluators, and actions.

Examples

See working integration examples with LangChain, CrewAI, and more.