Architecture

​

System Overview

​

Components

​

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

​

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

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