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

# 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](/concepts) section.

***

## SDKs

Agent Control provides official SDKs for Python and TypeScript.

| SDK            | Install                         | Docs                                  |
| -------------- | ------------------------------- | ------------------------------------- |
| **Python**     | `pip install agent-control-sdk` | [Python SDK](/sdk/python-sdk)         |
| **TypeScript** | `npm install agent-control`     | [TypeScript SDK](/sdk/typescript-sdk) |

### SDK development

The SDK source lives in a [uv](https://github.com/astral-sh/uv) workspace. To work with the SDKs locally:

```bash theme={null}
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.

```text theme={null}
Control = Scope + Condition + Action
```

**Control associations** are direct links between controls and agents.

```text theme={null}
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:

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. **Observe** — non-blocking observability action that does not affect execution.

You can read more in [Concepts](/concepts/overview)

***

## 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](/components/server)

***

## 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:

```bash theme={null}
curl -H "X-API-Key: your-api-key" http://localhost:8000/api/v1/agents
```

With the Python SDK:

```python theme={null}
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](/core/configuration) for full environment variables, server settings, and database setup.

***

## Troubleshooting

### Server connection issues

```bash theme={null}

# Check if server is running

curl http://localhost:8000/health

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

```

### Import errors

```bash theme={null}

# 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

```bash theme={null}

# 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](/components/server)
* [Engine](/components/engine)
* [Models](/components/models)
* [Evaluators](/components/evaluators)
* [UI Dashboard](/components/ui)