Skip to main content
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.