2. Install the SDK

Run this in your agent project directory.

Python:

uv venv
source .venv/bin/activate
uv pip install agent-control-sdk

TypeScript:

• See the TypeScript SDK example.

setup.py - Run once to configure agent controls

import asyncio from datetime import datetime, UTC from agent_control import AgentControlClient, controls, agents from agent_control_models import Agent

async def setup(): async with AgentControlClient() as client: # Defaults to localhost:8000 # 1. Register agent first agent = Agent( agent_name="awesome_bot_3000", agent_description="My Chatbot", agent_created_at=datetime.now(UTC).isoformat(), ) await agents.register_agent(client, agent, steps=[])

# 2. Create control (blocks SSN patterns in output) control = await controls.create_control( client, name="block-ssn", data={ "enabled": True, "execution": "server", "scope": {"stages": ["post"]}, "condition": { "selector": {"path": "output"}, "evaluator": { "name": "regex", "config": {"pattern": r"\b\d{3}-\d{2}-\d{4}\b"}, }, }, "action": {"decision": "deny"}, }, )

# 3. Associate control directly with agent await agents.add_agent_control( client, agent_name=agent.agent_name, control_id=control["control_id"], )

print("✅ Setup complete!") print(f" Control ID: {control['control_id']}")

asyncio.run(setup())

Controls now store leaf `selector` and `evaluator` definitions under `condition`, which also enables composite `and`, `or`, and `not` trees.

**Tip**: If you prefer a visual flow, use the UI instead - see the [UI Quickstart](https://docs.agentcontrol.dev/core/ui-quickstart).

Run both scripts in order:

Expected output:

Podman Setup

If Docker Desktop is not available, you can use Podman as a drop-in replacement. No changes to repo files are needed — the setup below makes docker and docker compose transparently resolve to Podman.

One-time setup:

1. Install Podman Desktop and create a machine from its UI (start it before continuing).

1. Install podman-compose:

brew install podman-compose

1. Create a docker shim that routes docker compose to podman-compose and everything else to podman:

mkdir -p ~/.local/bin
cat > ~/.local/bin/docker << 'EOF'
#!/bin/zsh
if [[ "$1" == "compose" ]]; then
  shift
  exec podman-compose "$@"
fi
exec podman "$@"
EOF
chmod +x ~/.local/bin/docker

1. Add ~/.local/bin early in your PATH (if not already):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify:

docker ps
docker compose version

After this, all existing docker/docker compose commands and make targets work as-is.

Quick Start

Prerequisites: Docker (or Podman, see Podman setup) and Python 3.12+.

Quick start flow:

Start server
  ↓
Install SDK
  ↓
Wrap a model or tool call with @control() and register your agent
  ↓
Create controls (UI or SDK/API)

Examples:

Explore working examples for popular frameworks.

• Customer Support Agent - PII protection, prompt injection defense, and tool controls
• Steer Action Demo - observe, deny, and steer decisions in one workflow
• LangChain - protect a SQL agent from dangerous queries
• CrewAI - combine Agent Control with CrewAI guardrails
• AWS Strands - protect Strands workflows and tool calls
• Google ADK Decorator - add controls with @control()

Select registered sinks instead of the default SDK -> server sink.

agent_control.init( agent_name="awesome_bot_3000", observability_enabled=True, observability_sink_name="registered", )

Later, when tearing down the integration:

unregister_control_event_sink(sink)

Registered sinks receive the same local, server, and merged control-execution
events the SDK emits through its normal event-construction flow. The default
SDK sink remains the OSS path to the Agent Control server. To use registered
or named custom sinks, set `observability_sink_name` explicitly.

The SDK also includes a built-in OpenTelemetry sink. Install the OTEL extra,
select the `otel` sink, and configure the OTLP exporter through Agent Control
settings or environment variables:

If the otel sink is selected without an OTLP endpoint/exporter configured, the OTEL path stays inert and the default OSS SDK-to-server behavior still remains unchanged unless observability_sink_name is explicitly switched away from default.

Next, create a control in Step 4, then run the setup and agent scripts in order to see blocking in action.