> ## Documentation Index
> Fetch the complete documentation index at: https://agentcontrol-docs-add-source-code-notes-to-examples.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/examples/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:

```bash theme={null}
pip install agent-control-sdk
```

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

```bash theme={null}
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)

```bash theme={null}

# 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](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.

```python theme={null}

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

```python theme={null}

# 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):

```bash theme={null}
uv venv
uv .venv/bin/activate
uv pip install agent-control-sdk
uv run setup.py
```

## Step 4: Run Your Agent

```bash theme={null}
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](/concepts/controls#defining-controls) for examples and guidance

* **Explore evaluators:** Try AI-powered evaluators like [Luna-2](/concepts/controls#example-block-toxic-input-luna-2-ai) or create custom evaluators. See [DeepEval example](/examples/deepeval) for custom evaluator examples

* **Production setup:** Enable authentication — see the [Reference](/reference#authentication)

* **Check examples:** See [Examples](/examples/overview) for real-world patterns

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

## What’s Next

<CardGroup cols={2}>
  <Card title="Concepts" icon="lightbulb" href="/concepts">
    Learn about controls, selectors, evaluators, and actions.
  </Card>

  <Card title="Examples" icon="code" href="/examples/overview">
    See working integration examples with LangChain, CrewAI, and more.
  </Card>
</CardGroup>