> ## Documentation Index
> Fetch the complete documentation index at: https://agentcontrol-abhi-agent-control-auth-contract-docs.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.

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 associate them with the agent
3. Run an agent that uses the `@control` decorator with server-side controls
4. Dynamically update controls on the server (enable or disable rules without redeploying code)

## Prerequisites

Before running this example:

1. Start the Agent Control server from the monorepo root:

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

2. Verify the server is running:

   ```bash theme={null}
   curl http://localhost:8000/health
   # Expected: {"status":"healthy","version":"..."}
   ```

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

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

## Quick Start

### Step 1: Create Controls on the Server

Run the setup script to create the agent and controls:

```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**: Regex control to detect and block Social Security Numbers
  * **block-banned-words**: List-based control to block profanity and sensitive keywords
* A policy with both controls assigned to the agent

### Step 2: 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()` to connect to the server
* Load the assigned controls
* Apply the `@control()` decorator to protect functions
* Test various scenarios:
  * Normal message (allowed)
  * Message containing banned words (blocked)
  * Message with allowed content (passes)
  * Tool output containing SSN (blocked)

### Step 3: 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.

## Files

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

## How It Works

### 1. Server-Side Control Definition

Controls are defined on the server with:

* Scope: When to check (step types, stages: pre or post)
* Condition: What and how to check
* Action: What to do (deny, steer, observe)

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"]),
    condition=ConditionNode(
        selector=ControlSelector(path="output"),
        evaluator=EvaluatorSpec(
            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 which:

* Automatically fetches assigned controls from server
* Evaluates controls before or after function execution
* Blocks violations or allows safe operations

Example from `demo_agent.py`:

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

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

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

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:

* Enable or disable controls
* Update patterns and rules
* Change enforcement decisions (deny to observe)
* Add new controls to existing agents

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

## Source Code

View the complete example with all scripts and setup instructions:

[`Agent Control Demo Example`](https://github.com/agentcontrol/agent-control/tree/main/examples/agent_control_demo)

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