Server

# From the repo root
uv sync

# Start database (PostgreSQL)
cd server
docker-compose up -d

# Run migrations
make alembic-upgrade

# Run the server
make run
# Or: uv run uvicorn agent_control_server.main:app --reload

# Build the package
cd server
uv build

# Install the built package
uv pip install dist/agent_control_server-*.whl

# Run the server
agent-control-server

# Database
AGENT_CONTROL_DB_URL=postgresql+psycopg://user:password@localhost/agent_control
# AGENT_CONTROL_DB_URL=sqlite+aiosqlite:///./agent_control.db

# Server settings
HOST=0.0.0.0
PORT=8000
DEBUG=false

# Authentication
AGENT_CONTROL_API_KEY_ENABLED=true
AGENT_CONTROL_API_KEYS=your-api-key-here,another-key-here
AGENT_CONTROL_ADMIN_API_KEYS=your-admin-key-here

# Observability
OBSERVABILITY_ENABLED=true
OBSERVABILITY_FLUSH_INTERVAL_SECONDS=10

# Luna-2 Evaluator (optional)
GALILEO_API_KEY=your-galileo-api-key

# Prometheus metrics
PROMETHEUS_METRICS_PREFIX=agent_control_server

curl -H "X-API-Key: your-api-key" http://localhost:8000/api/v1/agents/...

from agent_control import AgentControlClient

async with AgentControlClient(api_key="your-api-key") as client:
    await client.health_check()

export AGENT_CONTROL_API_KEY="your-api-key"

from agent_control import AgentControlClient

async with AgentControlClient() as client:
    await client.health_check()

AGENT_CONTROL_API_KEY_ENABLED=false

GET /health
GET /metrics
GET /api/v1/evaluators

POST /api/v1/agents/initAgent
GET /api/v1/agents/{agent_name}
GET /api/v1/agents/{agent_name}/controls

# Create control
PUT /api/v1/controls
Body: { "name": "my-control", "data": {...} }

# List controls (cursor-based)
GET /api/v1/controls?cursor=123&limit=100

# Get control
GET /api/v1/controls/{control_id}

# Update control metadata
PATCH /api/v1/controls/{control_id}
Body: { "name": "new-name", "enabled": true }

# Get control data
GET /api/v1/controls/{control_id}/data

# Update existing control data
PUT /api/v1/controls/{control_id}/data
Body: { "data": {...} }

# Validate control data without saving
POST /api/v1/controls/validate
Body: { "data": {...} }

# Delete control
DELETE /api/v1/controls/{control_id}

POST /api/v1/agents/{agent_name}/controls/{control_id}

POST /api/v1/evaluation

POST /api/v1/observability/events
POST /api/v1/observability/events/query
GET /api/v1/observability/stats?agent_name=...&time_range=5m
GET /api/v1/observability/stats/controls/{control_id}?agent_name=...&time_range=5m

make alembic-revision MESSAGE="description"
make alembic-upgrade
make alembic-downgrade

make test
uv run pytest tests/test_controls.py
uv run pytest --cov=agent_control_server

make lint
make lint-fix
make typecheck

docker build -f server/Dockerfile -t agent-control-server .

docker run -p 8000:8000 \
  -e AGENT_CONTROL_DB_URL=postgresql+psycopg://user:password@host:5432/agent_control \
  -e AGENT_CONTROL_API_KEY_ENABLED=true \
  -e AGENT_CONTROL_API_KEYS=your-key-here \
  -e AGENT_CONTROL_ADMIN_API_KEYS=your-admin-key-here \
  agent-control-server

cd server
uv build
pip install dist/agent_control_server-*.whl
agent-control-server