> ## Documentation Index
> Fetch the complete documentation index at: https://agentcontrol-abhi-agent-control-auth-contract-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Agent Control system architecture, component overview, and data flow.

## System Overview

```mermaid theme={null}
flowchart TD
    subgraph App["Your Application"]
        subgraph decorator["@control() decorator"]
            direction LR
            Input --> Engine["Agent Control Engine"] --> Output
        end
    end

    App --> Server

    subgraph Server["Agent Control Server"]
        direction LR
        Controls["Controls API"] ~~~  Evaluators["Evaluators Registry"] ~~~ Agents["Agents API"]
    end

    Server --> Ecosystem

    subgraph Ecosystem["Evaluator Ecosystem"]
        direction LR
        Regex["Regex valuator"] ~~~ List["List Evaluator"] ~~~ Luna["Luna-2 Evaluator"] ~~~ Custom["Custom Evaluators"]
    end
```

## Components

| Package                                              | Description                                |
| :--------------------------------------------------- | :----------------------------------------- |
| [`agent-control-sdk`](/sdk/python-sdk)               | Python SDK with `@control()` decorator     |
| [`agent-control-server`](/components/server)         | FastAPI server with Control Management API |
| [`agent-control-engine`](/components/engine)         | Core evaluation logic and evaluator system |
| [`agent-control-models`](/components/models)         | Shared Pydantic v2 models                  |
| [`agent-control-evaluators`](/components/evaluators) | Built-in evaluators                        |

### 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** — Plugin 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

***

## Data Flow

### Agent Initialization

1. **Agent Registration** — Agent initializes with `agent_control.init()`, registering with the server

### Control Execution

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Function as @control() Function
    participant SDK as Agent Control SDK
    participant Server as Agent Control Server
    participant Engine as Control Engine

    User->>Function: Call protected function
    Function->>SDK: Pre-stage evaluation
    SDK->>Server: Evaluate pre controls
    Server->>Engine: Run evaluators
    Engine-->>Server: Results
    Server-->>SDK: Pass / Deny

    alt All pre controls pass
        SDK->>Function: Execute function
        Function->>SDK: Return output
        SDK->>Server: Evaluate post controls
        Server->>Engine: Run evaluators
        Engine-->>Server: Results
        Server-->>SDK: Pass / Deny
        SDK-->>User: Return result
    else Any deny control matches
        SDK-->>User: ControlViolationError
    end
```

### Control Management

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

***

## Directory Structure

```bash theme={null}
agent-control/
├── sdks/python/     # Python SDK (agent-control)
├── sdks/typescript/ # TypeScript SDK (generated)
├── server/          # FastAPI server (agent-control-server)
├── engine/          # Evaluation engine (agent-control-engine)
├── models/          # Shared models (agent-control-models)
├── evaluators/      # Evaluator implementations (agent-control-evaluators)
├── ui/              # Next.js web dashboard
├── scripts/         # Build scripts
└── examples/        # Usage examples
```

## Key Design Decisions

* **Runtime Configuration** — Update controls without redeploying applications
* **Extensible** — Plugin 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