Reference

This page centralizes the technical reference for Agent Control. For concepts and architecture, see the Concepts section.

SDKs

Agent Control provides official SDKs for Python and TypeScript.

SDK	Install	Docs
Python	`pip install agent-control-sdk`	Python SDK
TypeScript	`npm install agent-control`	TypeScript SDK

SDK development

The SDK source lives in a uv workspace. To work with the SDKs locally:

cd sdk/

uv sync             # Install dependencies
uv run pytest       # Run tests
uv run ruff check . # Lint
uv run mypy .       # Type-check

Concepts (Reference)

A Control is a single rule that defines what to check and what to do when a condition is met.

Control = Scope + Condition + Action

Control associations are direct links between controls and agents.

Controls → Agents

Check stages:

Stage	When	Use Case
`pre`	Before execution	Block bad inputs, prevent prompt injection
`post`	After execution	Filter bad outputs, redact PII

Selectors:

Path	Description	Example Use
`input`	Step input (tool args or LLM input)	Check for prompt injection
`output`	Step output	Check for PII leakage
`input.query`	Tool input field	Block SQL injection
`name`	Step name (tool name or model/chain id)	Restrict step usage
`context.user_id`	Context field	User-based rules
`*`	Entire step	Full payload analysis

Actions:

Action	Behavior
`deny`	Block the request/response, raise `ControlViolationError`
`steer`	Raise `ControlSteerError` with steering context for correction and retry
`observe`	Record the match for audit and observability without blocking execution

Priority semantics:

Deny wins — if any deny control matches, execution is blocked.
Steer second — if any steer control matches (and no deny), steering context is returned.
Observe — non-blocking observability action that does not affect execution.

You can read more in Concepts

Server API

The Agent Control server exposes a RESTful API for managing agents and controls.

Base URL

Default: http://localhost:8000/api/v1

Endpoints

Agents:

Method	Endpoint	Description
`GET`	`/agents`	List all agents
`POST`	`/agents/initAgent`	Register a new agent
`GET`	`/agents/{agent_name}`	Get agent details
`PATCH`	`/agents/{agent_name}`	Update agent
`GET`	`/agents/{agent_name}/controls`	List controls for agent
`POST`	`/agents/{agent_name}/controls/{control_id}`	Add control to agent
`DELETE`	`/agents/{agent_name}/controls/{control_id}`	Remove control from agent

Controls:

Method	Endpoint	Description
`PUT`	`/controls`	Create control
`GET`	`/controls`	List controls
`GET`	`/controls/{control_id}`	Get control
`PATCH`	`/controls/{control_id}`	Update control
`DELETE`	`/controls/{control_id}`	Delete control

System:

Method	Endpoint	Description
`GET`	`/health`	Health check (no auth required)

See more in Server Docs

Authentication

Agent Control supports API key authentication for production deployments.

Configuration

Authentication is controlled by environment variables:

Variable	Default	Description
`AGENT_CONTROL_API_KEY_ENABLED`	`false`	Master toggle for authentication
`AGENT_CONTROL_API_KEYS`	—	Comma-separated list of valid API keys
`AGENT_CONTROL_ADMIN_API_KEYS`	—	Comma-separated list of admin API keys

Usage

Include the API key in the X-API-Key header:

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

With the Python SDK:

from agent_control import AgentControlClient

# Via constructor

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

# Or via environment variable

# export AGENT_CONTROL_API_KEY="your-api-key"

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

Access Levels

Endpoint	Required Level
`/health`	Public (no auth)
All `/api/v1/*`	API key required

Key Rotation

Agent Control supports multiple API keys for zero-downtime rotation:

Add new key to AGENT_CONTROL_API_KEYS (e.g., key1,key2,new-key)
Deploy the server
Update clients to use the new key
Remove the old key from the variable
Redeploy

Configuration Reference

See Configuration for full environment variables, server settings, and database setup.

Troubleshooting

Server connection issues

# Check if server is running

curl http://localhost:8000/health

# Expected: {"status":"healthy","version":"0.1.0"}

Import errors

# Install the SDK from workspace root

make sync

# Or install directly

pip install -e sdks/python

Authentication errors

If you get 401 Unauthorized:

Check if auth is enabled: AGENT_CONTROL_API_KEY_ENABLED
Verify your API key is in AGENT_CONTROL_API_KEYS
Ensure the X-API-Key header is set correctly

Database connection issues

# Check if PostgreSQL is running

docker ps | grep postgres

# Restart the database

cd server && docker compose down && docker compose up -d

# Re-run migrations

make alembic-upgrade

Control not triggering

Verify the control is enabled
Check scope.step_types matches your step type (llm vs tool)
Check scope.stages is correct (pre for input, post for output)
Verify the selector path matches your data structure
Test the evaluator pattern/values independently

Luna-2 evaluator errors

Ensure the Galileo package is installed: pip install agent-control-evaluator-galileo (or pip install agent-control-evaluators[galileo])
Ensure GALILEO_API_KEY is set
Check network connectivity to Galileo API
Verify the metric name is valid
Check on_error setting if failures are silently allowed

Evaluator not found — If galileo.luna2 doesn’t appear in list_evaluators():

Verify the Galileo package is installed
Check server logs for evaluator discovery messages

Getting Started

Concepts

How-to Guides

Integrations

Third-Party Agents

Examples

Reference

SDKs

SDK development

Concepts (Reference)

Server API

Base URL

Endpoints

Authentication

Configuration

Usage

Access Levels

Key Rotation

Configuration Reference

Troubleshooting

Server connection issues

Import errors

Authentication errors

Database connection issues

Control not triggering

Luna-2 evaluator errors

​SDKs

​SDK development

​Concepts (Reference)

​Server API

​Base URL

​Endpoints

​Authentication

​Configuration

​Usage

​Access Levels

​Key Rotation

​Configuration Reference

​Troubleshooting

​Server connection issues

​Import errors

​Authentication errors

​Database connection issues

​Control not triggering

​Luna-2 evaluator errors

​Related

SDKs

SDK development

Concepts (Reference)

Server API

Base URL

Endpoints

Authentication

Configuration

Usage

Access Levels

Key Rotation

Configuration Reference

Troubleshooting

Server connection issues

Import errors

Authentication errors

Database connection issues

Control not triggering

Luna-2 evaluator errors

Related