Skip to content

cleanup overview #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
namrataghadi-galileo merged 5 commits into from
Mar 11, 2026
Merged

cleanup overview #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
27bba6c
cleanup overview
namrataghadi-galileo Mar 11, 2026
9b7dee1
improve the landing page
namrataghadi-galileo Mar 11, 2026
589a96c
update text
namrataghadi-galileo Mar 11, 2026
0d14fa5
change title
namrataghadi-galileo Mar 11, 2026
cf49d70
move diagram lower
namrataghadi-galileo Mar 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
246 changes: 25 additions & 221 deletions core/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
title: Agent Control
description: Runtime guardrails for AI agents — configurable, extensible, and production-ready.
icon: "house"
description: An open‑source control plane for centralized agent governance and guardrails.
---

<iframe
Expand All @@ -14,245 +13,50 @@ icon: "house"
allowFullScreen
></iframe>

**Agent Control** provides a policy-based control layer that sits between your AI agents and the outside world. It evaluates inputs and outputs against configurable rules, blocking harmful content, prompt injections, PII leakage, and other risks — all without changing your agent's code. It's fully open source--check out the **Agent Control** [repo](https://github.com/agentcontrol/agent-control).
**Agent Control** provides a centralized control layer that evaluates inputs and outputs against configurable rules to block harmful content, prompt injections, PII leakage, and more—without changing agent code.

## Why Do You Need It?
Choose your next step: follow the quickstart, explore examples, or head to the repo:

Traditional guardrails embedded inside your agent code have critical limitations:

- **Scattered Logic:** Control code is buried across your agent codebase, making it hard to audit or update
- **Deployment Overhead:** Changing protection rules requires code changes and redeployment
- **Limited Adaptability:** Hard-coded checks can't adapt to new attack patterns or production data variations

**Agent Control gives you runtime control over what your agents can and cannot do:**

- **For developers:** Centralize safety logic and adapt to emerging threats instantly without redeployment
- **For non-technical teams:** Intuitive UI to configure and monitor agent safety without touching code
- **For organizations:** Reusable policies across agents with comprehensive audit trails


![Agent Control Architecture](/images/Architecture.png)


## Get started

Protect your AI agent in 4 simple steps.

## Prerequisites

- **Python 3.12+**

- **Docker**

<Tip>
**Quick setup (no repo cloning required)** - Copy this into your terminal or directly paste into your coding agent to start the Agent Control server, UI:

```bash
curl -L https://raw.githubusercontent.com/agentcontrol/agent-control/refs/heads/main/docker-compose.yml | docker compose -f - up -d
```

Then, install sdk in your virtual env:

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

**What this does:**

- ✅ Starts Agent Control server at `http://localhost:8000`
- ✅ Starts UI dashboard at `http://localhost:8000`
- ✅ Installs Python SDK (`agent-control-sdk`)

**Next:** Jump to [Step 3: Register your agent](#step-3-register-your-agent)

</Tip>


**Alternatively**, for local development with the Agent Control repository, clone the repo and follow all steps below.

## Step 1: Start the Agent Control Server

Startup AgentControl server manually for local development.

### Local development (cloning the repo)

Prerequisites:

- **uv** — Fast Python package manager (`curl -LsSf https://astral.sh/uv/install.sh | sh`)

- **Node.js 18+** — For the web dashboard (optional)

```bash

# Clone the repository (contains the server)

git clone https://github.com/agentcontrol/agent-control.git
cd agent-control

# Install dependencies

make sync

# Start the Agent Control server (boots Postgres + runs migrations)

make server-run

# Start the UI (in a separate shell)

make ui-install
make ui-dev
```

- **Server runs at `http://localhost:8000`** ✅

- **UI runs at `http://localhost:4000`** ✅

> 💡 **Verify the server:** Open [http://localhost:8000/health](http://localhost:8000/health) — you should see `{"status": "healthy", "version": "..."}`.

## Step 2: Install the SDK

In your agent application project:

```bash
pip install agent-control-sdk
```

## Step 3: Register Your Agent

Agent must be registered with the server. You should also add `@control` decorator around tools and LLM call functions.

Here is a contrived example. Reference our [Examples](/examples/overview) for real world examples for specific frameworks.

```python

# my_agent.py

import asyncio
import agent_control
from agent_control import control, ControlViolationError

# Protect any function (like LLM calls)

@control()
async def chat(message: str) -> str:
# In production: response = await LLM.ainvoke(message)
# For demo: simulate LLM that might leak sensitive data
if "test" in message.lower():
return "Your SSN is 123-45-6789" # Will be blocked!
return f"Echo: {message}"

# Initialize your agent

agent_control.init(
agent_name="awesome_bot_3000", # Unique name
agent_description="My Chatbot",
)

async def main():
try:
print(await chat("test")) # ❌ Blocked
except ControlViolationError as e:
print(f"❌ Blocked: {e.control_name}")

asyncio.run(main())
```

## Step 4: Add Controls

The easiest way to add controls is through the UI — see the [UI Quickstart](/core/ui-quickstart) for a step-by-step guide. Alternatively, use the SDK as shown below or call the API directly.

Run following setup script to create controls to protect your agent.

```python
# 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"]},
"selector": {"path": "output"},
"evaluator": {
"name": "regex",
"config": {"pattern": r"\b\d{3}-\d{2}-\d{4}\b"},
},
"action": {"decision": "deny"},
},
)
<CardGroup cols={2}>

# 3. Associate control directly with agent
await agents.add_agent_control(
client,
agent_name=agent.agent_name,
control_id=control["control_id"],
)
<Card title="Quickstart" icon="bolt" href="/core/quickstart">
Install, run, and protect your first agent in minutes.
</Card>

print("✅ Setup complete!")
print(f" Control ID: {control['control_id']}")
<Card title="Examples" icon="flask" href="/examples/overview">
Real-world use cases and end-to-end integrations.
</Card>

asyncio.run(setup())
```
<Card title="Agent Control Repo" icon="github" href="https://github.com/agentcontrol/agent-control">
Browse the source, contribute, or star the project.
</Card>

> [!NOTE]
> **Authentication Note:** Authentication is disabled by default in the server .env (`AGENT_CONTROL_API_KEY_ENABLED=false`). If you enable it, this setup script needs an admin API key because it creates a control and attaches it to an agent. `agents.register_agent()` accepts a regular or admin key, but `controls.create_control()` and `agents.add_agent_control()` require a key listed in `AGENT_CONTROL_ADMIN_API_KEYS`.
>
> In the example .env, the placeholders are:
>
> - **Regular API key(s):** `AGENT_CONTROL_API_KEYS` (e.g., "my-ui-key")
> - **Admin API key(s):** `AGENT_CONTROL_ADMIN_API_KEYS` (e.g., "my-admin-key")
>
> **Replace these defaults before any shared or production deployment.**
</CardGroup>

**With authentication enabled:**
## Why It Matters

```bash
curl -L https://raw.githubusercontent.com/agentcontrol/agent-control/refs/heads/main/docker-compose.yml | AGENT_CONTROL_API_KEY_ENABLED=true AGENT_CONTROL_API_KEYS="my-ui-key" AGENT_CONTROL_ADMIN_API_KEYS="my-admin-key" AGENT_CONTROL_SESSION_SECRET="some-long-random-string" CORS_ORIGINS="http://localhost:4000" docker compose -f - up -d && pip install agent-control-sdk
```
Traditional guardrails embedded inside your agent code have critical limitations:

- **Scattered Logic:** Control code is buried across your agent codebase, making it hard to audit or update
- **Deployment Overhead:** Changing protection rules requires code changes and redeployment
- **Limited Adaptability:** Hard-coded checks can’t adapt to new attack patterns or production data variations

Now, run your agent code.
**Agent Control gives you runtime control over what your agents can and cannot do:**

**🎉 Done!** Your agent now blocks SSN patterns automatically.
- **For developers:** Centralize safety logic and adapt to emerging threats without redeployment
- **For non-technical teams:** Configure and monitor agent safety without touching code
- **For organizations:** Reuse controls across agents with audit-ready traces

For detailed explanations of how controls work under the hood, performance benchmarks, configuration options, and development setup, see the complete [Quickstart](/core/quickstart) guide.
Explore the core building blocks:

<CardGroup cols={2}>

<Card title="Quickstart" icon="bolt" href="/core/quickstart">
Install, run, and protect your first agent in minutes.
</Card>

<Card title="Examples" icon="flask" href="/examples/overview">
Real-world use cases and end-to-end integrations.
</Card>

<Card title="Concepts" icon="lightbulb" href="/concepts">
Controls, Selectors, Evaluators, and Actions.
Controls, selectors, evaluators, and actions.
</Card>

<Card title="Architecture" icon="sitemap" href="/concepts/architecture">
Component overview, data flow, and system design.
</Card>

</CardGroup>

15 changes: 9 additions & 6 deletions core/quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ make ui-dev
In your agent application project:

```bash
pip install agent-control-sdk
uv pip install agent-control-sdk
```

## Step 3: Register Your Agent
Expand Down Expand Up @@ -182,7 +182,11 @@ async def setup():
asyncio.run(setup())
```

> [!NOTE]
Now, run your agent code.

**🎉 Done!** Your agent now blocks SSN patterns automatically.

> [**!NOTE**]
> **Authentication Note:** Authentication is disabled by default in the server .env (`AGENT_CONTROL_API_KEY_ENABLED=false`). If you enable it, this setup script needs an admin API key because it creates a control and attaches it to an agent. `agents.register_agent()` accepts a regular or admin key, but `controls.create_control()` and `agents.add_agent_control()` require a key listed in `AGENT_CONTROL_ADMIN_API_KEYS`.
>
> In the example .env, the placeholders are:
Expand All @@ -195,15 +199,14 @@ asyncio.run(setup())
**With authentication enabled:**

```bash
curl -L https://raw.githubusercontent.com/agentcontrol/agent-control/refs/heads/main/docker-compose.yml | AGENT_CONTROL_API_KEY_ENABLED=true AGENT_CONTROL_API_KEYS="my-ui-key" AGENT_CONTROL_ADMIN_API_KEYS="my-admin-key" AGENT_CONTROL_SESSION_SECRET="some-long-random-string" CORS_ORIGINS="http://localhost:4000" docker compose -f - up -d && pip install agent-control-sdk
curl -L https://raw.githubusercontent.com/agentcontrol/agent-control/refs/heads/main/docker-compose.yml | AGENT_CONTROL_API_KEY_ENABLED=true AGENT_CONTROL_API_KEYS="my-ui-key" AGENT_CONTROL_ADMIN_API_KEYS="my-admin-key" AGENT_CONTROL_SESSION_SECRET="some-long-random-string" CORS_ORIGINS="http://localhost:4000" docker compose -f - up -d
```

Now, run your agent code.

**🎉 Done!** Your agent now blocks SSN patterns automatically.

### What Is Happening Under the Hood

![Agent Control Architecture](/images/Architecture.png)

1. Your app calls `chat("test")`

2. Function executes and returns `"Your SSN is 123-45-6789"`
Expand Down
Loading