Agent Control Demo

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

The source code for this example is available on GitHub: Agent Control Demo

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

curl -LsSf https://astral.sh/uv/install.sh | sh

Start the Agent Control server from the monorepo root:

make server-run

Verify the server is running:

curl http://localhost:8000/health

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

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

make sync

1. Create controls on the server

   Run the setup script to create the agent, controls, and policy:

   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.

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(), load the assigned policy, apply @control() decorators, and run test scenarios that demonstrate allow/deny behavior.

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

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

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:

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

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

Next Steps

• Explore Concepts to understand controls, policies, scopes, and evaluators

• Check out CrewAI example for multi-agent orchestration with controls

• Read SDK documentation for full API reference

• Try the LangChain SQL example for LangChain integration

Resources

• Main Documentation

• SDK Documentation

• Server Documentation