Skip to content

docs(docs): update Readme #58

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
lan17 merged 2 commits into from
Mar 5, 2026
Merged

docs(docs): update Readme #58

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
69ed78b
docs: update Readme
lan17 Mar 4, 2026
8fdb626
Merge branch 'main' into lev/updatereadme
lan17 Mar 5, 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
6 changes: 6 additions & 0 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ TS_SDK_DIR := sdks/typescript
ENGINE_DIR := engine
EVALUATORS_DIR := evaluators/builtin
GALILEO_DIR := evaluators/contrib/galileo
UI_DIR := ui

help:
@echo "Agent Control - Makefile commands"
Expand All @@ -25,6 +26,7 @@ help:
@echo ""
@echo "Run:"
@echo " make server-<target> - forward to server targets (e.g., server-help, server-alembic-upgrade)"
@echo " make ui-<target> - forward to UI targets (e.g., ui-help, ui-dev, ui-lint, ui-lint--fix)"
@echo " make openapi-spec - generate runtime OpenAPI spec at $(OPENAPI_SPEC_PATH)"
@echo " make openapi-spec-check - verify OpenAPI generation succeeds"
@echo ""
Expand Down Expand Up @@ -214,6 +216,10 @@ evaluators-build:
server-%:
$(MAKE) -C $(SERVER_DIR) $(patsubst server-%,%,$@)

.PHONY: ui-%
ui-%:
$(MAKE) -C $(UI_DIR) $(patsubst ui-%,%,$@)

# ---------------------------
# Contrib Evaluators (Galileo)
# ---------------------------
Expand Down
234 changes: 60 additions & 174 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@
[![CI](https://github.com/agentcontrol/agent-control/actions/workflows/ci.yml/badge.svg)](https://github.com/agentcontrol/agent-control/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/agentcontrol/agent-control/branch/main/graph/badge.svg)](https://codecov.io/gh/agentcontrol/agent-control)

> **💡 Pro Tip:** Checkout [docs](https://docs.agentcontrol.dev/) for complete reference

**Runtime guardrails for AI agents — configurable, extensible, and production-ready.**

AI agents interact with users, tools, and external systems in unpredictable ways. **Agent Control** provides an extensible, control-based runtime layer that evaluates inputs and outputs against configurable rules — blocking prompt injections, PII leakage, and other risks without modifying your agent's code.
Expand All @@ -26,8 +28,6 @@ Traditional guardrails embedded inside your agent code have critical limitations
- **For non-technical teams:** Intuitive UI to configure and monitor agent safety without touching code
- **For organizations:** Reusable controls across agents with comprehensive audit trails

---

## Key Features

- **Safety Without Code Changes** — Add guardrails with a `@control()` decorator
Expand All @@ -38,13 +38,6 @@ Traditional guardrails embedded inside your agent code have critical limitations
- **Fail-Safe Defaults** — Deny controls fail closed on error with configurable error handling
- **API Key Authentication** — Secure your control server in production

---

## Core Concepts
See the [Concepts guide](CONCEPTS.md) to familiarize yourself with Agent Control's core concepts and terminology—essential for designing effective controls and evaluators for your application.

---

### Examples

Explore real-world integrations with popular agent frameworks, or jump to [Quick Start](#quick-start) for hands-on setup.
Expand All @@ -57,104 +50,92 @@ Explore real-world integrations with popular agent frameworks, or jump to [Quick
- **[CrewAI SDK Integration](examples/crewai/)** — Working example on integrating with third party Agent SDKs and using Agent Control along side their guardrails
- **[DeepEval Integration](examples/deepeval/)** — Working Example on How to create custom evaluators to use with your controls

---

## Real Quick Start

Get up and running with Agent Control in **one command**:

**Prerequisites**: Python 3.12+ and Docker must be installed.
## Quick start

### Option 1: Quick Install (Recommended)
### Installation

```bash
curl -fsSL -H "Authorization: token YOUR_GITHUB_TOKEN" https://raw.githubusercontent.com/agentcontrol/agent-control/main/setup.sh | sh
```
**Prerequisites**:
* Python 3.12+
* Docker

> ⚠️ **Note**: This will automatically download and run the setup script. [Review the script](https://github.com/agentcontrol/agent-control/blob/main/setup.sh) before running if you prefer.
#### SDK only
Install our SDK in your project - `pip install agent-control-sdk`
> **📝 Note:** Depending on your setup the command maybe different such as `uv add agent-control-sdk` if you're using uv.

### Option 2: Clone and Run

```bash
git clone https://github.com/agentcontrol/agent-control.git
cd agent-control
./setup.sh
Run the Agent Control server and Postgres database via docker compose:
```commandline
curl "https://raw.githubusercontent.com/agentcontrol/agent-control/refs/heads/main/docker-compose.yml" | docker compose -f - up -d
Comment thread
lan17 marked this conversation as resolved.
```

**What the script does:**
- ✓ Check Python 3.12+ is installed
- ✓ Create a virtual environment
- ✓ Pull and start PostgreSQL + Agent Control Server + UI via Docker
- ✓ Install the Agent Control SDK

**Server will be running at `http://localhost:8000` and UI at `http://localhost:4000` — ready to use!**


---

**Prefer manual setup?** Continue to the detailed [Quick Start](#quick-start) section below.

---

## Quick Start
Server will be running at `http://localhost:8000`

Protect your AI agent in 4 simple steps.
#### Local development

**Prerequisites:**
- **Python 3.12+**
- **uv** — Fast Python package manager (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
- **Docker** — For running PostgreSQL
- **Node.js 18+** — For the web dashboard (optional)

---

### Step 1: Start the Agent Control Server

The server stores controls and evaluates agent operations for safety.
* 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)
# Clone the repo
git clone https://github.com/agentcontrol/agent-control.git
cd agent-control

# Install dependencies
make sync

# Start PostgreSQL database
cd server && docker-compose up -d && cd ..

# Run database migrations
make server-alembic-upgrade

# Start the Agent Control server
# Start the Agent Control server. This will also boot Postgres and run alembic migrations
make server-run

# Start the UI (in a separate shell)
make ui-install
make ui-dev
```
* Server will run on `http://localhost:8000`
* UI will run on `http://localhost:4000`

**Server is now running at `http://localhost:8000`** ✅
### Onboarding your agent

> 💡 **Verify it's working:** Open http://localhost:8000/health in your browser - you should see `{"status": "ok"}`
#### Register your agent with server

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

### Step 2: (Optional) Start the Web Dashboard
Here is a contrived example. Reference our [examples](/examples) for real world examples for specific frameworks.
```python
# my_agent.py
import asyncio
import agent_control
from agent_control import control, ControlViolationError

The dashboard provides a UI for managing agents, controls, and viewing analytics. Everything can be done via API/SDK, but the UI is more convenient.
# 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}"

In a separate terminal:
```bash
cd ~/path_to_agent-control/
cd ui
pnpm install
pnpm dev
```
# Initialize your agent
agent_control.init(
agent_name="awesome_bot_3000", # This should be a unique name
agent_description="My Chatbot",
)

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

**Dashboard is now running at `http://localhost:4000`** ✅
asyncio.run(main())
```

---
#### Add some controls

### Step 3: Setup Controls for Your Agent
Easiest way to add controls is to use the UI.

Create controls to protect your agent's operations:
You can also use SDK or directly call api:

```python
# setup.py - Run once to configure everything
Expand Down Expand Up @@ -202,61 +183,7 @@ async def setup():

asyncio.run(setup())
```

**In your Agent application directory** (not inside the agent-control repo):
```bash
uv venv
uv .venv/bin/activate
uv pip install agent-control-sdk
uv run setup.py
```

---

### Step 4: Now, Use in Your Agent

Now protect your functions with `@control()`:

```python
# my_agent.py
import asyncio
import agent_control
from agent_control import control, ControlViolationError

# Initialize your agent
agent_control.init(
agent_name="550e8400-e29b-41d4-a716-446655440000", # Agent identifier (UUID recommended)
agent_description="My Chatbot",
)

# 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}"

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

asyncio.run(main())
```

```bash
uv run my_agent.py
```

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

---

### What's Happening Under the Hood?
#### What's Happening Under the Hood?

1. Your app calls `chat("test")`
2. Function executes and returns `"Your SSN is 123-45-6789"`
Expand All @@ -266,47 +193,6 @@ uv run my_agent.py
6. Server returns `is_safe=False` with the matched control
7. SDK raises `ControlViolationError` and blocks the response

**Key Benefits:**
- ✅ Controls are managed **separately** from your code
- ✅ Update controls **without redeploying** your agent
- ✅ Same controls can protect **multiple agents**
- ✅ View analytics and control execution in the dashboard

---

### Next Steps

- **Add more controls:** See [CONCEPTS.md](CONCEPTS.md#defining-controls) for examples and guidance
- **Explore evaluators:** Try AI-powered evaluators like [Luna-2](CONCEPTS.md#example-block-toxic-input-luna-2-ai) or create custom evaluators. See [examples/deepeval](examples/deepeval) for custom evaluator examples
- **Production setup:** Enable authentication - see [docs/REFERENCE.md](docs/REFERENCE.md#authentication)
- **Check examples:** See [examples/](examples/) for real-world patterns

> **💡 Pro Tip:** Start with simple regex controls, then graduate to AI-powered evaluators for complex safety checks!

### 5. Assign Controls

Controls can be associated directly with agents. An agent's **active controls** are the controls currently linked to that agent.

**Direct controls** — attach individual controls to an agent:

```bash
# Add a control directly to an agent
curl -X POST http://localhost:8000/api/v1/agents/support-agent-v1/controls/3

# Remove a direct control
curl -X DELETE http://localhost:8000/api/v1/agents/support-agent-v1/controls/3
```

**List all active controls**:

```bash
curl http://localhost:8000/api/v1/agents/support-agent-v1/controls
```

> Controls are optional. An agent can operate with no controls configured.

---

## Configuration

### Environment Variables
Expand Down
Loading
Loading