Agent Control Demo

​

Overview

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

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

uv run python examples/agent_control_demo/setup_controls.py

• 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

uv run python examples/agent_control_demo/demo_agent.py

• 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

# 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

​

Files

​

How It Works

​

1. Server-Side Control Definition

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

# 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

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

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

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

​

Configuration

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

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

​

Source Code

​

Troubleshooting

​

Server Connection Issues

curl http://localhost:8000/health

# If not running, start it
make server-run

​

Agent Not Found

uv run python examples/agent_control_demo/setup_controls.py

​

Import Errors

make sync