ACP Docs
Swagger UI Dashboard

Getting Started

Get up and running with AI Control Plane in under 5 minutes.

1. Clone and Deploy

# Clone the repository
git clone https://github.com/Anil175/ai-control-plane.git
cd ai-control-plane

# Start all services (12 containers)
docker compose up -d

# Verify everything is running
docker compose ps

2. Get Your API Key

Open the dashboard at http://localhost:3000 and generate an API key, or use the seed key from the bootstrap script.

3. Register Your First Agent

curl -X POST http://localhost:8000/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-agent",
    "description": "A simple support agent",
    "model": "gpt-4o",
    "system_prompt": "You are a helpful support agent.",
    "tools": ["knowledge-base"],
    "tags": ["support", "v1"]
  }'

4. Run Your Agent

curl -X POST http://localhost:8000/api/v1/agents/AGENT_ID/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "How do I reset my password?",
    "parameters": { "temperature": 0.7 }
  }'

The run executes asynchronously. Poll the run status or check the dashboard for real-time updates.

Core Concepts

Understand the building blocks of AI Control Plane.

Agents

The central entity. An agent has a name, model, system prompt, tool bindings, and safety policies. Agents are versioned — every config change creates an immutable snapshot.

Runs

A single execution of an agent. Each run tracks input, output, token usage, cost, latency, and a step-by-step trace of tool calls and LLM interactions.

Tools

External capabilities (REST APIs, functions, databases) that agents can invoke. Registered in the Tool Registry with input schemas for validation.

Policies

Declarative safety rules attached to agents. Enforce token limits, restrict tool access, require human approval, filter content, and define escalation behavior.

Budgets

Spending limits per agent, team, or globally. Define daily/weekly/monthly caps with configurable actions: block, throttle, or alert-only when exceeded.

Memory

Persistent context across runs. Four types: session (within a conversation), episodic (event-based), long-term (facts), and semantic (embeddings via pgvector).

Events

Every state change emits a Kafka event. Events power real-time dashboards, audit trails, alerting, and external integrations via consumers.

Schedules

Cron-based automation for recurring agent tasks. Managed by the scheduler worker with health monitoring and manual trigger support.

API Reference

Key endpoints organized by module. For full details, parameter schemas, and response formats, see the interactive Swagger UI.

Base URL: https://api.ai-control-plane.in ·  Auth: Authorization: Bearer API_KEY

Agents(5 endpoints)

MethodPath
GET/api/v1/agents
POST/api/v1/agents
GET/api/v1/agents/:id
PUT/api/v1/agents/:id
DELETE/api/v1/agents/:id

Runtime(5 endpoints)

MethodPath
POST/api/v1/agents/:id/run
GET/api/v1/agents/:id/runs
GET/api/v1/agents/:id/runs/:runId
GET/api/v1/agents/:id/runs/:runId/steps
DELETE/api/v1/agents/:id/runs/:runId

Tools(3 endpoints)

MethodPath
GET/api/v1/tools
POST/api/v1/tools
POST/api/v1/tools/:id/test

Memory(2 endpoints)

MethodPath
GET/api/v1/memory
POST/api/v1/memory/search

Budgets(4 endpoints)

MethodPath
GET/api/v1/budgets
POST/api/v1/budgets
GET/api/v1/budgets/usage
GET/api/v1/budgets/alerts

Schedules(3 endpoints)

MethodPath
GET/api/v1/schedules
POST/api/v1/schedules
POST/api/v1/schedules/:id/trigger

Analytics(3 endpoints)

MethodPath
GET/api/v1/analytics/summary
GET/api/v1/analytics/timeseries
GET/api/v1/analytics/agents

Audit(2 endpoints)

MethodPath
GET/api/v1/audit
GET/api/v1/audit/runs/:runId

Deployment

Deploy ACP to any cloud with Docker Compose.

Docker Compose (Recommended)

The default deployment uses Docker Compose with 12 containers including the API, Gateway, 3 Celery workers, Dashboard, TimescaleDB, Redis, Kafka, and Zookeeper.

# Production deployment
git clone https://github.com/Anil175/ai-control-plane.git
cd ai-control-plane

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Deploy
docker compose up -d

# Run database migrations
docker compose exec api python -m shared.migrations.run

# Seed initial data
docker compose exec api python seed.py

Architecture

API
FastAPI on port 8000
Gateway
Go/Chi on port 8080
Dashboard
Next.js on port 3000
Database
TimescaleDB on port 5432
Cache
Redis on port 6379
Events
Kafka on port 9092

Security

Security is built into every layer of the AI Control Plane.

Authentication

All API requests require a Bearer token. API keys are hashed with bcrypt and stored in the database. Keys can be scoped to specific agents or operations.

Gateway Rate Limiting

The Go gateway enforces per-IP and per-key rate limits before requests reach the API. Configurable burst and sustained rates.

Policy Enforcement

Safety policies are evaluated before every tool call. Policies can block specific tools, enforce token limits, require human approval, and filter outputs.

Audit Logging

Every agent decision, tool invocation, and state change is recorded in the audit ledger. Immutable, timestamped, and queryable.

Network Isolation

Docker Compose creates isolated networks. The database and workers are not exposed to the public internet. Only the gateway and dashboard accept external traffic.

Event Sourcing

All state transitions emit Kafka events. This provides a complete, replayable history and enables integration with external SIEM systems.