diff --git a/.gitignore b/.gitignore index abce7919..9ac25d4f 100644 --- a/.gitignore +++ b/.gitignore @@ -38,6 +38,7 @@ uv.lock *.swo *~ .DS_Store +coverage-*.xml # Testing .pytest_cache/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a250a8f..f4d7358a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -108,52 +108,52 @@ ### Bug Fixes - Tighten evaluation error handling and preserve control data - ([`52a1ef8`](https://github.com/rungalileo/agent-control/commit/52a1ef8127aca382e373ee6b6433a2d527e6e5e2)) + ([`52a1ef8`](https://github.com/agentcontrol/agent-control/commit/52a1ef8127aca382e373ee6b6433a2d527e6e5e2)) - **examples**: Update crew ai example to use evaluator - ([#93](https://github.com/rungalileo/agent-control/pull/93), - [`1c65084`](https://github.com/rungalileo/agent-control/commit/1c6508434860ed5bb56c622a721197c5a8f7ad4e)) + ([#93](https://github.com/agentcontrol/agent-control/pull/93), + [`1c65084`](https://github.com/agentcontrol/agent-control/commit/1c6508434860ed5bb56c622a721197c5a8f7ad4e)) -- **sdk**: Fix logging ([#77](https://github.com/rungalileo/agent-control/pull/77), - [`b1f078c`](https://github.com/rungalileo/agent-control/commit/b1f078c52c29ac048a9bcbea09252786e842acbd)) +- **sdk**: Fix logging ([#77](https://github.com/agentcontrol/agent-control/pull/77), + [`b1f078c`](https://github.com/agentcontrol/agent-control/commit/b1f078c52c29ac048a9bcbea09252786e842acbd)) - **sdk**: Plugin to evaluator.. agent_protect to agent_control - ([#88](https://github.com/rungalileo/agent-control/pull/88), - [`fc9b088`](https://github.com/rungalileo/agent-control/commit/fc9b088fcd091132a1e38deae372b73fc2834beb)) + ([#88](https://github.com/agentcontrol/agent-control/pull/88), + [`fc9b088`](https://github.com/agentcontrol/agent-control/commit/fc9b088fcd091132a1e38deae372b73fc2834beb)) - **ui**: Fix UI and clients for simplified step schema - ([#75](https://github.com/rungalileo/agent-control/pull/75), - [`be2aaf0`](https://github.com/rungalileo/agent-control/commit/be2aaf0ae43a9051cb60ce3597f089307f731d0a)) + ([#75](https://github.com/agentcontrol/agent-control/pull/75), + [`be2aaf0`](https://github.com/agentcontrol/agent-control/commit/be2aaf0ae43a9051cb60ce3597f089307f731d0a)) ### Documentation -- **examples**: Add crew ai example ([#84](https://github.com/rungalileo/agent-control/pull/84), - [`1077c3b`](https://github.com/rungalileo/agent-control/commit/1077c3b9281ece7885383dccf58dbf0e4e70080e)) +- **examples**: Add crew ai example ([#84](https://github.com/agentcontrol/agent-control/pull/84), + [`1077c3b`](https://github.com/agentcontrol/agent-control/commit/1077c3b9281ece7885383dccf58dbf0e4e70080e)) ### Features - **docs**: Add GitHub badges and CI coverage reporting - ([#90](https://github.com/rungalileo/agent-control/pull/90), - [`be1fa14`](https://github.com/rungalileo/agent-control/commit/be1fa140e4208993886f0afaef29b4a45fd27253)) + ([#90](https://github.com/agentcontrol/agent-control/pull/90), + [`be1fa14`](https://github.com/agentcontrol/agent-control/commit/be1fa140e4208993886f0afaef29b4a45fd27253)) -- **ui**: Stats dashboard ([#80](https://github.com/rungalileo/agent-control/pull/80), - [`4cbb7fe`](https://github.com/rungalileo/agent-control/commit/4cbb7fee43ed14145815c9fd807b150f19200654)) +- **ui**: Stats dashboard ([#80](https://github.com/agentcontrol/agent-control/pull/80), + [`4cbb7fe`](https://github.com/agentcontrol/agent-control/commit/4cbb7fee43ed14145815c9fd807b150f19200654)) ### Refactoring - **evaluators**: Rename plugin to evaluator throughout - ([#81](https://github.com/rungalileo/agent-control/pull/81), - [`0134682`](https://github.com/rungalileo/agent-control/commit/0134682c1d0f167528d7267507dbcf3a1e7b3192)) + ([#81](https://github.com/agentcontrol/agent-control/pull/81), + [`0134682`](https://github.com/agentcontrol/agent-control/commit/0134682c1d0f167528d7267507dbcf3a1e7b3192)) ### Testing - **server**: Add behavioral coverage for controls, agents - follow up - ([#95](https://github.com/rungalileo/agent-control/pull/95), - [`dfa9c3f`](https://github.com/rungalileo/agent-control/commit/dfa9c3f2b110c96041893e392b3a11ab02cafcdb)) + ([#95](https://github.com/agentcontrol/agent-control/pull/95), + [`dfa9c3f`](https://github.com/agentcontrol/agent-control/commit/dfa9c3f2b110c96041893e392b3a11ab02cafcdb)) - **server**: Add behavioral coverage for controls, agents, observability - ([#91](https://github.com/rungalileo/agent-control/pull/91), - [`d5c2301`](https://github.com/rungalileo/agent-control/commit/d5c2301a8707ad9b4c84400f64695c53505d479a)) + ([#91](https://github.com/agentcontrol/agent-control/pull/91), + [`d5c2301`](https://github.com/agentcontrol/agent-control/commit/d5c2301a8707ad9b4c84400f64695c53505d479a)) ## v2.1.0 (2026-01-27) @@ -161,16 +161,16 @@ ### Features - **server**: Add evaluator config store - ([#78](https://github.com/rungalileo/agent-control/pull/78), - [`cc14aa6`](https://github.com/rungalileo/agent-control/commit/cc14aa68391fd7fd4a187364a0a9a9fe712129fe)) + ([#78](https://github.com/agentcontrol/agent-control/pull/78), + [`cc14aa6`](https://github.com/agentcontrol/agent-control/commit/cc14aa68391fd7fd4a187364a0a9a9fe712129fe)) ## v2.0.1 (2026-01-26) ### Bug Fixes -- **docs**: Clean up Protect ([#76](https://github.com/rungalileo/agent-control/pull/76), - [`99c16fd`](https://github.com/rungalileo/agent-control/commit/99c16fd8ed6620363f919818ebe4083f1489ba1c)) +- **docs**: Clean up Protect ([#76](https://github.com/agentcontrol/agent-control/pull/76), + [`99c16fd`](https://github.com/agentcontrol/agent-control/commit/99c16fd8ed6620363f919818ebe4083f1489ba1c)) ## v2.0.0 (2026-01-24) @@ -178,14 +178,14 @@ ### Features - **server**: Add observability system for control execution tracking - ([#44](https://github.com/rungalileo/agent-control/pull/44), - [`fd0bddc`](https://github.com/rungalileo/agent-control/commit/fd0bddce3a9aa53472edb13e1c8fee6305571e98)) + ([#44](https://github.com/agentcontrol/agent-control/pull/44), + [`fd0bddc`](https://github.com/agentcontrol/agent-control/commit/fd0bddce3a9aa53472edb13e1c8fee6305571e98)) ### Refactoring - **models**: Simplify step model and schema - ([#70](https://github.com/rungalileo/agent-control/pull/70), - [`4c1d637`](https://github.com/rungalileo/agent-control/commit/4c1d6378a4a05edc44f02fa78c1698b9203da81b)) + ([#70](https://github.com/agentcontrol/agent-control/pull/70), + [`4c1d637`](https://github.com/agentcontrol/agent-control/commit/4c1d6378a4a05edc44f02fa78c1698b9203da81b)) ## v1.1.4 (2026-01-23) @@ -193,8 +193,8 @@ ### Chores - **infra**: Rename project from agent-control to agent-control-sdk - ([#74](https://github.com/rungalileo/agent-control/pull/74), - [`7a16463`](https://github.com/rungalileo/agent-control/commit/7a1646341d4b4fc4edc1ab67a202c14ffb485934)) + ([#74](https://github.com/agentcontrol/agent-control/pull/74), + [`7a16463`](https://github.com/agentcontrol/agent-control/commit/7a1646341d4b4fc4edc1ab67a202c14ffb485934)) ## v1.1.3 (2026-01-23) @@ -202,16 +202,16 @@ ### Chores - **infra**: Rename sdk to agent-control - ([#73](https://github.com/rungalileo/agent-control/pull/73), - [`2a4c88a`](https://github.com/rungalileo/agent-control/commit/2a4c88a1d0c69bb71c7b61df7e636b7a8ef0a002)) + ([#73](https://github.com/agentcontrol/agent-control/pull/73), + [`2a4c88a`](https://github.com/agentcontrol/agent-control/commit/2a4c88a1d0c69bb71c7b61df7e636b7a8ef0a002)) ## v1.1.2 (2026-01-23) ### Chores -- **infra**: Use pypi token for publish ([#72](https://github.com/rungalileo/agent-control/pull/72), - [`3f3ef15`](https://github.com/rungalileo/agent-control/commit/3f3ef154fd22012d38932e3a461b08ce417c4e84)) +- **infra**: Use pypi token for publish ([#72](https://github.com/agentcontrol/agent-control/pull/72), + [`3f3ef15`](https://github.com/agentcontrol/agent-control/commit/3f3ef154fd22012d38932e3a461b08ce417c4e84)) ## v1.1.1 (2026-01-23) @@ -219,8 +219,8 @@ ### Chores - **infra**: Publish models and sdk on release - ([#71](https://github.com/rungalileo/agent-control/pull/71), - [`7fcf53a`](https://github.com/rungalileo/agent-control/commit/7fcf53a4392752e21f9eba77498bcc9ec2593bce)) + ([#71](https://github.com/agentcontrol/agent-control/pull/71), + [`7fcf53a`](https://github.com/agentcontrol/agent-control/commit/7fcf53a4392752e21f9eba77498bcc9ec2593bce)) ## v1.1.0 (2026-01-23) @@ -228,42 +228,42 @@ ### Bug Fixes - **ci**: Add ui scope to PR title validation - ([#59](https://github.com/rungalileo/agent-control/pull/59), - [`e0fdb52`](https://github.com/rungalileo/agent-control/commit/e0fdb528c201e15bab06668683ee02ef1dde70e8)) + ([#59](https://github.com/agentcontrol/agent-control/pull/59), + [`e0fdb52`](https://github.com/agentcontrol/agent-control/commit/e0fdb528c201e15bab06668683ee02ef1dde70e8)) -- **docs**: Fix Examples for LangGraph ([#64](https://github.com/rungalileo/agent-control/pull/64), - [`23b30ae`](https://github.com/rungalileo/agent-control/commit/23b30ae1ddc5b878d8375b4f39a6617e7a0ae604)) +- **docs**: Fix Examples for LangGraph ([#64](https://github.com/agentcontrol/agent-control/pull/64), + [`23b30ae`](https://github.com/agentcontrol/agent-control/commit/23b30ae1ddc5b878d8375b4f39a6617e7a0ae604)) - **docs**: Improve documentation for open source release - ([#47](https://github.com/rungalileo/agent-control/pull/47), - [`9018fb3`](https://github.com/rungalileo/agent-control/commit/9018fb3c79e385732957bafcf75dcec4f83b958d)) + ([#47](https://github.com/agentcontrol/agent-control/pull/47), + [`9018fb3`](https://github.com/agentcontrol/agent-control/commit/9018fb3c79e385732957bafcf75dcec4f83b958d)) -- **docs**: Remove old/unused examples ([#66](https://github.com/rungalileo/agent-control/pull/66), - [`f417781`](https://github.com/rungalileo/agent-control/commit/f4177810579037a6c3f14cc4db59222166ec5209)) +- **docs**: Remove old/unused examples ([#66](https://github.com/agentcontrol/agent-control/pull/66), + [`f417781`](https://github.com/agentcontrol/agent-control/commit/f4177810579037a6c3f14cc4db59222166ec5209)) - **examples**: Control sets cleanup with signed - ([#65](https://github.com/rungalileo/agent-control/pull/65), - [`af7b5fb`](https://github.com/rungalileo/agent-control/commit/af7b5fb44fe800a98c617ee70ae258576e146115)) + ([#65](https://github.com/agentcontrol/agent-control/pull/65), + [`af7b5fb`](https://github.com/agentcontrol/agent-control/commit/af7b5fb44fe800a98c617ee70ae258576e146115)) ### Chores - **ui**: Update and add readme & agents md - ([#60](https://github.com/rungalileo/agent-control/pull/60), - [`53d46ec`](https://github.com/rungalileo/agent-control/commit/53d46ec509d47a0e8da8abc4a060396bf4addffc)) + ([#60](https://github.com/agentcontrol/agent-control/pull/60), + [`53d46ec`](https://github.com/agentcontrol/agent-control/commit/53d46ec509d47a0e8da8abc4a060396bf4addffc)) ### Features - **server**: Add prometheus metrics for endpoints - ([#68](https://github.com/rungalileo/agent-control/pull/68), - [`775612c`](https://github.com/rungalileo/agent-control/commit/775612c2ebe4895760c326bb8e23ee29a5101247)) + ([#68](https://github.com/agentcontrol/agent-control/pull/68), + [`775612c`](https://github.com/agentcontrol/agent-control/commit/775612c2ebe4895760c326bb8e23ee29a5101247)) - **ui**: Add sql, luna2, json control forms and restructure the code - ([#54](https://github.com/rungalileo/agent-control/pull/54), - [`c4c1d4a`](https://github.com/rungalileo/agent-control/commit/c4c1d4ab53bce9bb9ee77657d4b9dd3152e587cd)) + ([#54](https://github.com/agentcontrol/agent-control/pull/54), + [`c4c1d4a`](https://github.com/agentcontrol/agent-control/commit/c4c1d4ab53bce9bb9ee77657d4b9dd3152e587cd)) - **ui**: Tests added and some minor ui changes, added error boundaries - ([#61](https://github.com/rungalileo/agent-control/pull/61), - [`009852b`](https://github.com/rungalileo/agent-control/commit/009852bb678d570d21de82fb1af89eececd2fdc8)) + ([#61](https://github.com/agentcontrol/agent-control/pull/61), + [`009852b`](https://github.com/agentcontrol/agent-control/commit/009852bb678d570d21de82fb1af89eececd2fdc8)) ## v1.0.1 (2026-01-17) @@ -271,8 +271,8 @@ ### Bug Fixes - **infra**: Add plugins directory to Dockerfile - ([#58](https://github.com/rungalileo/agent-control/pull/58), - [`171d459`](https://github.com/rungalileo/agent-control/commit/171d459377aa294087f0af1561345a5e010120cb)) + ([#58](https://github.com/agentcontrol/agent-control/pull/58), + [`171d459`](https://github.com/agentcontrol/agent-control/commit/171d459377aa294087f0af1561345a5e010120cb)) ## v1.0.0 (2026-01-17) diff --git a/CONCEPTS.md b/CONCEPTS.md new file mode 100644 index 00000000..c42282f3 --- /dev/null +++ b/CONCEPTS.md @@ -0,0 +1,287 @@ +## Concepts +Understanding these core concepts will help you get the most out of Agent Control. + +![Agent Control Policy Architecture](./docs/images/Policy.png) + +## Policy + +A Policy is a named collection of controls assigned to an agent. Policies enable you to: + +- Bundle multiple controls together as a cohesive protection strategy +- Audit your safety rules +- Enables reusable security/compliance configurations across agents +- Apply different policies to different environments (dev/staging/prod) + +```python +# Policy for PROD deployment +{ + "id": 42, + "name": "production-safety", + "controls": [ # collection of rules. + {....} + ] +} +``` + +## Controls + +![Control Components](./docs/images/Control.png) + +A Control is a protection rule that evaluates agent interactions (inputs/outputs) and takes action based on configured criteria. It defines when to check, what to check, how to evaluate it, and what to do with the results. + +**Control = Scope (When) + Selector (What) + Evaluator (How) + Action (Decision)** + +### 1. Scope (When to Check) + +The **Scope** defines which steps trigger the control—acting as a filter to select specific sections of your agent workflow to monitor. + +**Fields:** +- `step_types`: List of step types (`['tool', 'llm_inference']`). If null, applies to all types. +- `step_names`: List of exact step names to target (e.g., `['search_db', 'send_email']`) +- `step_name_regex`: Regex pattern for step name matching (e.g., `"^db.*"` matches all "db_" prefixed steps) +- `stages`: When to evaluate - `['pre', 'post']` + - `'pre'`: Check before execution (block bad inputs, prevent prompt injection) + - `'post'`: Check after execution (filter bad outputs, redact PII) + +**Example 1: Apply to all tool steps before execution** +```json +{ + "scope": { + "step_types": ["tool"], + "stages": ["pre"] + } +} +``` + +**Example 2: Target specific database operations** +```json +{ + "scope": { + "step_names": ["query_database", "execute_sql", "db_lookup"], + "stages": ["pre"] + } +} +``` + +**Example 3: Use regex to match multiple steps** +```json +{ + "scope": { + "step_name_regex": "^db_.*", // Matches all steps starting with "db_" + "stages": ["pre", "post"] + } +} +``` + +**Example 4: Full scope configuration** +```json +{ + "scope": { + "step_types": ["tool", "llm_inference"], + "step_names": ["search_db", "query_api"], + "step_name_regex": "^db_.*", + "stages": ["pre", "post"] + } +} +``` + +--- + +### 2. Selector (What to Check) + +The **Selector** specifies which portion of the step's data to extract and pass to the evaluator for analysis. It uses a path specification to navigate the step object. + +**Field:** +- `path`: Dot-notation path to the data you want to evaluate + +**Common Paths:** +- `"input"` - Entire input to the step +- `"output"` - Step's output/result +- `"input.query"` - Specific parameter within input +- `"input.user_message"` - User message field +- `"name"` - The step/tool name itself +- `"context.user_id"` - Context metadata +- `"*"` - All available payload data + +**Example 1: Check tool output for PII** +```json +{ + "selector": { + "path": "output" + } +} +``` + +**Example 2: Validate specific input parameter** +```json +{ + "selector": { + "path": "input.sql_query" + } +} +``` + +**Example 3: Check user message in LLM input** +```json +{ + "selector": { + "path": "input.user_message" + } +} +``` + +**Example 4: Access context metadata** +```json +{ + "selector": { + "path": "context.user_id" + } +} +``` + +--- + +### 3. Evaluator (How to Check) + +The **Evaluator** receives the data extracted by the selector and evaluates it against configured rules, returning whether the data matches specified criteria. + +**Components:** +- `name`: Evaluator identifier (e.g., `"regex"`, `"list"`, `"galileo-luna2"`) +- `config`: Evaluator-specific configuration, validated against the evaluator's schema +- `metadata`: Optional evaluator identification (name, version, description) + +**Example 1: Regex evaluator to detect PII** +```json +{ + "evaluator": { + "name": "regex", + "config": { + "pattern": "\\b\\d{3}-\\d{2}-\\d{4}\\b" // Social Security Number pattern + } + } +} +``` + +**Example 2: List evaluator for banned terms** +```json +{ + "evaluator": { + "name": "list", + "config": { + "values": ["DROP TABLE", "DELETE FROM", "TRUNCATE"], + "case_sensitive": false + } + } +} +``` + +**Example 3: AI-powered toxicity detection with Luna-2** +```json +{ + "evaluator": { + "name": "galileo-luna2", + "config": { + "metric": "input_toxicity", + "operator": "gt", + "target_value": 0.5 + } + } +} +``` + +**Example 4: Complex regex for multiple PII types** +```json +{ + "evaluator": { + "name": "regex", + "config": { + "pattern": "(?:\\b\\d{3}-\\d{2}-\\d{4}\\b|\\b\\d{4}[\\s-]?\\d{4}[\\s-]?\\d{4}[\\s-]?\\d{4}\\b|[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,})" + } + } +} +``` + +--- + +### 4. Action (What to Do) + +The **Action** defines what happens when the evaluator matches/detects an issue. + +**Fields:** +- `decision`: The enforcement action to take + - `"allow"` - Continue execution (useful for allowlist controls) + - `"deny"` - Hard stop execution (blocks the request) + - `"warn"` - Log a warning but continue execution + - `"log"` - Log the match for observability only +- `metadata`: Optional additional context (JSON object) + +**Important: "Deny Wins" Semantics** + +Agent Control uses "deny wins" logic: if **any** enabled control with a `deny` action matches, the request is blocked regardless of other control results. This ensures fail-safe behavior. + +**Example 1: Block on match** +```json +{ + "action": { + "decision": "deny" + } +} +``` + +**Example 2: Warn without blocking** +```json +{ + "action": { + "decision": "warn" + } +} +``` + +**Example 3: Action with metadata** +```json +{ + "action": { + "decision": "deny", + "metadata": { + "reason": "PII detected in output", + "severity": "high", + "compliance": "GDPR" + } + } +} +``` + +--- + +### Complete Control Example + +Putting it all together - a control that blocks Social Security Numbers in tool outputs: + +```json +{ + "name": "block-ssn-output", + "description": "Prevent SSN leakage in tool responses", + "enabled": true, + "scope": { + "step_types": ["tool"], + "stages": ["post"] + }, + "selector": { + "path": "output" + }, + "evaluator": { + "name": "regex", + "config": { + "pattern": "\\b\\d{3}-\\d{2}-\\d{4}\\b" + } + }, + "action": { + "decision": "deny", + "metadata": { + "reason": "SSN detected", + "compliance": "PII protection" + } + } +} +``` + diff --git a/README.md b/README.md index fc72ac29..1e773b67 100644 --- a/README.md +++ b/README.md @@ -3,39 +3,32 @@ [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/) [![PyPI version](https://img.shields.io/pypi/v/agent-control-sdk.svg)](https://pypi.org/project/agent-control-sdk/) -[![CI](https://github.com/rungalileo/agent-control/actions/workflows/ci.yml/badge.svg)](https://github.com/rungalileo/agent-control/actions/workflows/ci.yml) -[![codecov](https://codecov.io/gh/rungalileo/agent-control/branch/main/graph/badge.svg)](https://codecov.io/gh/rungalileo/agent-control) +[![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) **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, policy-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. +AI agents interact with users, tools, and external systems in unpredictable ways. **Agent Control** provides an extensible, policy-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. ---- +![Agent Control Architecture](docs/images/Architecture.png) -## See It In Action -```python -import agent_control -from agent_control import control, ControlViolationError +## Why Do You Need It? +Traditional guardrails embedded inside your agent code have critical limitations: -# Initialize once at startup -agent_control.init( - agent_name="Customer Support Agent", - agent_id="support-agent-v1", - server_url="http://localhost:8000" -) +- **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:** Hardcoded checks can't adapt to new attack patterns or production data variations -# Protect any function with a decorator -@control() -async def chat(message: str) -> str: - return await llm.generate(message) -# Violations are caught automatically -try: - response = await chat(user_input) -except ControlViolationError as e: - print(f"Blocked by control '{e.control_name}': {e.message}") -``` +**Agent Control gives you RUNTIME control over what your agents CAN & CANNOT do.** +1. You can enable and change controls of your agent in runtime without deploying code through APIs. This enables instant risk mitigation for emerging threats. +2. For non-technical members, agent control provides an intuitive UI to manage the control configuration. +3. The package also comes with several common out of box templates for controls that can be adapted and with a lot of flexibility to define custom controls or integrate with external evaluators. +4. Easily reuse controls across agents in your organization. + +## Core Concepts +See the [Concepts guide](CONCEPTS.md) for a deep dive into Agent Control's architecture and design principles. --- @@ -51,6 +44,16 @@ except ControlViolationError as e: --- +### Examples + +- **[Examples Overview](examples/README.md)** — Working code examples and integration patterns +- **[Customer Support Agent](examples/customer_support_agent/)** — Full example with multiple tools +- **[LangChain SQL Agent](examples/langchain/)** — SQL injection protection with LangChain +- **[Galileo Luna-2 Integration](examples/galileo/)** — AI-powered toxicity detection +- **[CrewAI SDK Integration](examples/crewai/)** - Working example on integrating with third party Agent SDKs and using Agent Control along side their guardrails. + +--- + ## Quick Start ### Prerequisites @@ -63,7 +66,7 @@ except ControlViolationError as e: ### 1. Clone and Install ```bash -git clone https://github.com/rungalileo/agent-control.git +git clone https://github.com/agentcontrol/agent-control.git cd agent-control make sync ``` @@ -95,7 +98,7 @@ Dashboard is now running at `http://localhost:4000`. Install the SDK: ```bash -pip install agent-control +pip install agent-control-sdk ``` Use in your code: @@ -164,7 +167,7 @@ Controls are defined via the API or dashboard. Each control specifies what to ch "description": "Block Social Security Numbers in responses", "enabled": true, "execution": "server", - "scope": { "step_types": ["llm"], "stages": ["post"] }, + "scope": { "step_names": ["generate_response"], "stages": ["post"] }, "selector": { "path": "output" }, "evaluator": { "name": "regex", @@ -182,7 +185,7 @@ Controls are defined via the API or dashboard. Each control specifies what to ch "description": "Block toxic or harmful user messages", "enabled": true, "execution": "server", - "scope": { "step_types": ["llm"], "stages": ["pre"] }, + "scope": { "step_names": ["process_user_message"], "stages": ["pre"] }, "selector": { "path": "input" }, "evaluator": { "name": "galileo-luna2", @@ -200,7 +203,7 @@ See [docs/REFERENCE.md](docs/REFERENCE.md#evaluators) for full evaluator documen --- -## Architecture +## Agent Control Components Agent Control is built as a monorepo with these components: @@ -239,7 +242,7 @@ Agent Control is built as a monorepo with these components: | Package | Description | |:--------|:------------| -| `agent-control` | Python SDK with `@control()` decorator | +| `agent-control-sdk` | Python SDK with `@control()` decorator | | `agent-control-server` | FastAPI server with Control Management API | | `agent-control-engine` | Core evaluation logic and evaluator system | | `agent-control-models` | Shared Pydantic v2 models | @@ -298,15 +301,6 @@ For detailed development workflows, see [CONTRIBUTING.md](CONTRIBUTING.md). - **[UI Dashboard](ui/README.md)** — Web dashboard setup and usage - **[Evaluators](evaluators/README.md)** — Available evaluators and custom evaluator development -### Examples - -- **[Examples Overview](examples/README.md)** — Working code examples and integration patterns -- **[Customer Support Agent](examples/customer_support_agent/)** — Full example with multiple tools -- **[LangChain SQL Agent](examples/langchain/)** — SQL injection protection with LangChain -- **[Galileo Luna-2 Integration](examples/galileo/)** — AI-powered toxicity detection - ---- - ## Contributing We welcome contributions! To get started: diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md index de913824..598769bd 100644 --- a/docs/REFERENCE.md +++ b/docs/REFERENCE.md @@ -8,7 +8,7 @@ This document provides comprehensive technical reference for Agent Control. Each - [Introduction](#introduction) - [Concepts](#concepts) -- [Architecture](#architecture) +- [Architecture](#agent-control-architecture) - [Evaluators](#evaluators) - [SDK Reference](#sdk-reference) - [Server API](#server-api) @@ -135,62 +135,143 @@ Controls can scope to different step types: --- -## Architecture - -Agent Control is built as a monorepo with these components: - -``` -┌──────────────────────────────────────────────────────────────────┐ -│ Your Application │ -│ ┌────────────────────────────────────────────────────────────┐ │ -│ │ @control() decorator │ │ -│ │ │ │ │ -│ │ ▼ │ │ -│ │ ┌──────────┐ ┌─────────────────┐ ┌──────────────┐ │ │ -│ │ │ Input │───▶│ Agent Control │───▶│ Output │ │ │ -│ │ │ │ │ Engine │ │ │ │ │ -│ │ └──────────┘ └─────────────────┘ └──────────────┘ │ │ -│ └────────────────────────────────────────────────────────────┘ │ -└──────────────────────────────────────────────────────────────────┘ - │ - ▼ -┌──────────────────────────────────────────────────────────────────┐ -│ Agent Control Server │ -│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ -│ │ Controls │ │ Policies │ │ Evaluators │ │ Agents │ │ -│ │ API │ │ API │ │ Registry │ │ API │ │ -│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ -└──────────────────────────────────────────────────────────────────┘ - │ - ▼ -┌──────────────────────────────────────────────────────────────────┐ -│ Evaluator Ecosystem │ -│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ -│ │ Regex │ │ List │ │ Luna-2 │ │ Custom │ │ -│ │ Evaluator │ │ Evaluator │ │ Evaluator │ │ Evaluators │ │ -│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ -└──────────────────────────────────────────────────────────────────┘ +## Agent Control Architecture + +```mermaid +graph TB + subgraph "User Application Layer" + APP[Your AI Agent Application] + SDK[Agent Control SDK
@control decorator] + APP --> SDK + end + + subgraph "Agent Control Platform" + subgraph "Server Layer" + API[REST API Server
FastAPI] + AUTH[Authentication
API Keys] + API --> AUTH + end + + subgraph "Processing Layer" + ENGINE[Control Engine
Evaluation Logic] + REGISTRY[Evaluator Registry
Evaluator Discovery] + ENGINE --> REGISTRY + end + + subgraph "Evaluator Ecosystem" + BUILTIN[Built-in Evaluators
Regex, List, JSON, SQL] + LUNA[Luna-2 Evaluator
AI-powered Detection] + CUSTOM[Custom Evaluators
User Extensions] + end + + subgraph "Data Layer" + DB[(PostgreSQL
Controls & Observability)] + MODELS[Shared Models
Pydantic v2] + end + + subgraph "Management Layer" + UI[Web Dashboard
Next.js + React] + UIAPI[Dashboard API Client] + UI --> UIAPI + end + end + + %% SDK to Server connections + SDK -->|HTTP/REST| API + + %% Server to Engine connections + API --> ENGINE + API --> DB + + %% Engine to Evaluators connections + REGISTRY --> BUILTIN + REGISTRY --> LUNA + REGISTRY --> CUSTOM + + %% Engine to Models + ENGINE --> MODELS + API --> MODELS + + %% Dashboard connections + UIAPI -->|HTTP/REST| API + + %% Database connections + ENGINE --> DB + + %% External services + LUNA -.->|API Calls| GALILEO[Galileo Luna-2 API] + CUSTOM -.->|Optional| EXTERNAL[External APIs
DeepEval, etc.] + + classDef userLayer fill:#e1f5ff,stroke:#01579b,stroke-width:2px + classDef serverLayer fill:#f3e5f5,stroke:#4a148c,stroke-width:2px + classDef engineLayer fill:#fff3e0,stroke:#e65100,stroke-width:2px + classDef evaluatorLayer fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px + classDef dataLayer fill:#fce4ec,stroke:#880e4f,stroke-width:2px + classDef uiLayer fill:#e0f2f1,stroke:#004d40,stroke-width:2px + + class APP,SDK userLayer + class API,AUTH serverLayer + class ENGINE,REGISTRY engineLayer + class BUILTIN,LUNA,CUSTOM evaluatorLayer + class DB,MODELS dataLayer + class UI,UIAPI uiLayer ``` -### Components - -| Component | Package | Description | -|-----------|---------|-------------| -| SDK | `agent-control` | Python client library with `@control()` decorator | -| Server | `agent-control-server` | FastAPI service that stores and evaluates controls | -| Engine | `agent-control-engine` | Core evaluation logic (can run locally or server-side) | -| Evaluators | `agent-control-evaluators` | Extensible evaluators for different detection methods | -| Models | `agent-control-models` | Shared Pydantic models for type-safe communication | -| UI | `ui/` | Next.js web dashboard for control management | - -### Data Flow - -1. Agent initializes with `agent_control.init()`, registering with the server -2. Server returns the agent's assigned policy and controls -3. When a decorated function is called, the SDK evaluates `pre` controls -4. If all `pre` controls pass, the function executes -5. After execution, `post` controls evaluate the output -6. If any control with `deny` action matches, `ControlViolationError` is raised +## Component Overview + +### User Application Layer +- **Your AI Agent Application**: Any Python application using AI agents (LangChain, CrewAI, custom, etc.) +- **Agent Control SDK**: Python package with `@control()` decorator for protecting functions + +### Server Layer +- **REST API Server**: FastAPI-based server exposing control management endpoints +- **Authentication**: Optional API key authentication for production deployments + +### Processing Layer +- **Control Engine**: Core evaluation engine that processes control rules and evaluates data +- **Evaluator Registry**: Evaluator system for discovering and loading evaluators via entry points + +### Evaluator Ecosystem +- **Built-in Evaluators**: Out-of-the-box evaluators (regex, list matching, JSON validation, SQL injection detection) +- **Luna-2 Evaluator**: AI-powered detection using Galileo's Luna-2 API +- **Custom Evaluators**: User-defined evaluators extending the base `Evaluator` class + +### Data Layer +- **PostgreSQL**: Persistent storage for controls, agents, and observability data +- **Shared Models**: Pydantic v2 models shared across all components + +### Management Layer +- **Web Dashboard**: Next.js + React UI for managing agents and controls +- **Dashboard API Client**: Type-safe API client for frontend-backend communication + +## Data Flow + +### Agent Initialization +1. **Agent Registration**: Agent initializes with `agent_control.init()`, registering with the server +2. **Policy Assignment**: Server returns the agent's assigned policy and active controls + +### Control Execution Flow +1. **Function Invocation**: User calls a function decorated with `@control()` +2. **Pre-Stage Evaluation**: SDK evaluates `pre` controls before function execution +3. **Function Execution**: If all `pre` controls pass, the protected function executes +4. **Post-Stage Evaluation**: SDK evaluates `post` controls on the output +5. **Server Processing**: Server receives evaluation request and fetches active controls +6. **Engine Evaluation**: Engine runs applicable evaluators based on control configuration +7. **Decision Enforcement**: If any control with `deny` action matches, `ControlViolationError` is raised; otherwise execution continues + +### Control Management Flow +1. **User Configures**: Admin uses Web Dashboard or API to create/modify controls +2. **Server Stores**: Server validates and stores control configuration in database +3. **Runtime Updates**: Changes take effect immediately for new requests (no deployment needed) +4. **Observability**: All control executions are logged for monitoring and analysis + +## Key Features + +- **Runtime Configuration**: Update controls without redeploying applications +- **Extensible**: Evaluator architecture for custom evaluators +- **Fail-Safe**: Configurable error handling (fail open/closed) +- **Observable**: Full audit trail of control executions +- **Production-Ready**: API authentication, PostgreSQL, horizontal scaling support --- diff --git a/docs/images/Architecture.png b/docs/images/Architecture.png new file mode 100644 index 00000000..f8da96aa Binary files /dev/null and b/docs/images/Architecture.png differ diff --git a/docs/images/Control.png b/docs/images/Control.png new file mode 100644 index 00000000..2836ccba Binary files /dev/null and b/docs/images/Control.png differ diff --git a/docs/images/Policy.png b/docs/images/Policy.png new file mode 100644 index 00000000..ce2f198e Binary files /dev/null and b/docs/images/Policy.png differ