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

# Agent Control Demo

> Start Agent Control, add server-side controls, and rerun the demo to see blocks in action.

<Info>
  The source code for this example is available on GitHub:
  [Agent Control Demo](https://github.com/agentcontrol/agent-control/tree/main/examples/agent_control_demo)
</Info>

Complete example demonstrating the Agent Control workflow: creating controls, running a controlled agent, and dynamically updating controls without code changes.

## Overview

This demo shows how to:

1. Create an agent and register it with the Agent Control server

2. Define controls (regex, list-based) and assign them to a policy

3. Run an agent that uses the `@control` decorator with server-side policies

4. Dynamically update controls on the server without redeploying code

## Prerequisites

Python 3.12+

uv — fast Python package manager

```bash theme={null}
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Start the Agent Control server from the monorepo root:

```bash theme={null}
make server-run
```

Verify the server is running:

```bash theme={null}
curl http://localhost:8000/health

# Expected: {"status":"healthy","version":"..."}

```

Install dependencies (if not already done from monorepo root):

```bash theme={null}
make sync
```

<Steps>
  <Step title="Create controls on the server">
    Run the setup script to create the agent, controls, and policy:

    ```bash theme={null}
    uv run python examples/agent_control_demo/setup_controls.py
    ```

    This creates a demo agent (`demo-chatbot`), two controls (`block-ssn-output`, `block-banned-words`), and a policy assigned to the agent.
  </Step>

  <Step title="Run the demo agent">
    Start the agent that uses server-side controls:

    ```bash theme={null}
    uv run python examples/agent_control_demo/demo_agent.py
    ```

    The agent will initialize with `agent_control.init()`, load the assigned policy, apply `@control()` decorators, and run test scenarios that demonstrate allow/deny behavior.
  </Step>

  <Step title="Update controls dynamically">
    Update controls on the server without changing code or restarting the agent:

    ```bash theme={null}

    # Disable the SSN control (allow SSNs)

    uv run python examples/agent_control_demo/update_controls.py --allow-ssn

    # Re-enable the SSN control (block SSNs again)

    uv run python examples/agent_control_demo/update_controls.py --block-ssn
    ```

    Key insight: controls are enforced server-side, so you can update rules in real-time without redeploying code.
  </Step>
</Steps>

## Files

| File                 | Description                                                     |
| :------------------- | :-------------------------------------------------------------- |
| `setup_controls.py`  | Creates agent, controls, policy, and assigns policy to agent    |
| `demo_agent.py`      | Demo agent using `@control` decorator with server-side policies |
| `update_controls.py` | Updates controls dynamically (enable/disable SSN blocking)      |

## How It Works

### 1. Server-Side Control Definition

Controls are defined on the server with scope, selector, evaluator, and action. Example from `setup_controls.py`:

```python theme={null}

# Regex control to block SSN in output

control_data = ControlDefinition(
    description="Block SSN patterns in output",
    enabled=True,
    execution="server",
    scope=ControlScope(step_types=["tool"], stages=["post"]),
    selector=ControlSelector(path="output"),
    evaluator=EvaluatorConfig(
        name="regex",
        config={"pattern": r"\b\d{3}-\d{2}-\d{4}\b"}
    ),
    action=ControlAction(decision="deny")
)
```

### 2. Agent Integration

The agent uses the `@control()` decorator to fetch its policy from the server and enforce controls before/after execution. Example from `demo_agent.py`:

```python theme={null}
import agent_control
from agent_control import control, ControlViolationError

# Initialize and connect to server

agent_control.init(
    agent_name="demo-chatbot",
)

# Apply server-side controls

@control()
async def chat(message: str) -> str:
    return f"Echo: {message}"

# Handle violations

try:
    response = await chat("user input")
except ControlViolationError as e:
    print(f"Blocked: {e.message}")
```

### 3. Dynamic Updates

Controls can be updated on the server without code changes. You can enable/disable controls, update patterns, change decisions, or add new controls to policies.

## Configuration

All scripts use the same agent configuration:

```python theme={null}
AGENT_NAME = "demo-chatbot"
SERVER_URL = os.getenv("AGENT_CONTROL_URL", "http://localhost:8000")
```

Set `AGENT_CONTROL_URL` to connect to a different server:

```bash theme={null}
export AGENT_CONTROL_URL=http://your-server:8000
```

## Troubleshooting

### Server Connection Issues

Error: `Failed to connect to server`

Fix:

```bash theme={null}
curl http://localhost:8000/health

# If not running, start it

make server-run
```

### Agent Not Found

Error: `Agent not found` when running `demo_agent.py`

Fix: Run `setup_controls.py` first:

```bash theme={null}
uv run python examples/agent_control_demo/setup_controls.py
```

### Import Errors

Error: `ModuleNotFoundError: No module named 'agent_control'`

Fix: Install dependencies from monorepo root:

```bash theme={null}
make sync
```

## Next Steps

* Explore [Concepts](/concepts) to understand controls, policies, scopes, and evaluators

* Check out [CrewAI example](/examples/crewai) for multi-agent orchestration with controls

* Read [SDK documentation](/sdk/python-sdk) for full API reference

* Try the [LangChain SQL example](/examples/langchain-sql) for LangChain integration

## Resources

* [Main Documentation](/introduction)

* [SDK Documentation](/sdk/python-sdk)

* [Server Documentation](/reference)