Reference

SDK and Server API reference for Agent Control.

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 + Selector + Evaluator + 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
allow	Permit execution (no effect if a deny control also matches)
warn	Log a warning but allow execution
log	Silent logging for monitoring only

Priority semantics:

1. Deny wins — if any deny control matches, execution is blocked.

2. Steer second — if any steer control matches (and no deny), steering context is returned.

3. Allow/warn/log — observability actions that do not block 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:

1. Add new key to AGENT_CONTROL_API_KEYS (e.g., key1,key2,new-key)

2. Deploy the server

3. Update clients to use the new key

4. Remove the old key from the variable

5. 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:

1. Check if auth is enabled: AGENT_CONTROL_API_KEY_ENABLED

2. Verify your API key is in AGENT_CONTROL_API_KEYS

3. 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

1. Verify the control is enabled

2. Check scope.step_types matches your step type (llm vs tool)

3. Check scope.stages is correct (pre for input, post for output)

4. Verify the selector path matches your data structure

5. Test the evaluator pattern/values independently

Luna-2 evaluator errors

1. Ensure the Galileo package is installed: pip install agent-control-evaluator-galileo (or pip install agent-control-evaluators[galileo])

2. Ensure GALILEO_API_KEY is set

3. Check network connectivity to Galileo API

4. Verify the metric name is valid

5. 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

Related

• Server
• Engine
• Models
• Evaluators
• UI Dashboard