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:

   make server-run
   

2. Verify the server is running:

   curl http://localhost:8000/health
   # Expected: {"status":"healthy","version":"..."}
   

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

   make sync
   

Quick Start

Step 1: Create Controls on the Server

Run the setup script to create the agent and controls:

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:

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:

# 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 (allow, deny, steer, warn, log)

Example from setup_controls.py:

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

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 warn)
• Add new controls to existing agents

Configuration

All scripts use the same agent configuration:

AGENT_NAME = "demo-chatbot"
SERVER_URL = os.getenv("AGENT_CONTROL_URL", "http://localhost:8000")

Set AGENT_CONTROL_URL to connect to a different server:

export AGENT_CONTROL_URL=http://your-server:8000

Source Code

View the complete example with all scripts and setup instructions:

Agent Control Demo Example

Troubleshooting

Server Connection Issues

Error: Failed to connect to server

Fix:

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:

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:

make sync