diff --git a/core/quickstart.mdx b/core/quickstart.mdx index 998d7ee..1bf4ccb 100644 --- a/core/quickstart.mdx +++ b/core/quickstart.mdx @@ -4,155 +4,72 @@ description: Install Agent Control, start the server, and protect your first age icon: "rocket" --- -Protect your AI agent in 4 simple steps. +Protect your AI agent in 3 steps: start the server, create a control, and run your agent. ## Prerequisites - **Python 3.12+** - - **Docker** - -**Quick setup (no repo cloning required)** - Copy this into your terminal or directly paste into your coding agent to start the Agent Control server, UI: +## Step 1: Start the Server and Install the SDK + +Run the one-liner to start the Agent Control server and dashboard, then install the SDK: ```bash curl -L https://raw.githubusercontent.com/agentcontrol/agent-control/refs/heads/main/docker-compose.yml | docker compose -f - up -d ``` -Then, install sdk in your virtual env: - ```bash -uv venv -source .venv/bin/activate +uv venv && source .venv/bin/activate uv pip install agent-control-sdk ``` -**What this does:** - -- ✅ Starts Agent Control server at `http://localhost:8000` -- ✅ Starts UI dashboard at `http://localhost:8000` -- ✅ Installs Python SDK (`agent-control-sdk`) - -**Next:** Jump to [Step 3: Register your agent](#step-3-register-your-agent) - - - - -**Alternatively**, for local development with the Agent Control repository, clone the repo and follow all steps below. - +- **Server + UI running at `http://localhost:8000`** ✅ +- **Python SDK installed** ✅ -## Step 1: Start the Agent Control Server - -Startup AgentControl server manually for local development. +> 💡 **Verify the server:** Open [http://localhost:8000/health](http://localhost:8000/health) — you should see `{"status": "healthy", "version": "..."}`. -### Local development (cloning the repo) + -Prerequisites: +If you want to contribute to Agent Control or run from source, clone the repository instead: +**Additional prerequisites:** - **uv** — Fast Python package manager (`curl -LsSf https://astral.sh/uv/install.sh | sh`) - - **Node.js 18+** — For the web dashboard (optional) ```bash - -# Clone the repository (contains the server) - +# Clone the repository git clone https://github.com/agentcontrol/agent-control.git cd agent-control # Install dependencies - make sync # Start the Agent Control server (boots Postgres + runs migrations) - make server-run # Start the UI (in a separate shell) - make ui-install make ui-dev ``` - **Server runs at `http://localhost:8000`** ✅ - - **UI runs at `http://localhost:4000`** ✅ -> 💡 **Verify the server:** Open [http://localhost:8000/health](http://localhost:8000/health) — you should see `{"status": "healthy", "version": "..."}`. - -## Step 2: Install the SDK - -In your agent application project: - -```bash -uv pip install agent-control-sdk -``` - -## Step 3: Register Your Agent + -Agent must be registered with the server. You should also add `@control` decorator around tools and LLM call functions. +## Step 2: Create a Control -Here is a contrived example. Reference our [Examples](/examples/overview) for real world examples for specific frameworks. +You can create controls through the [UI dashboard](/core/ui-quickstart) or programmatically with the SDK. Here we'll use the SDK to create a control that blocks SSN patterns in agent output: ```python - -# my_agent.py +# setup_control.py — run once to configure your control import asyncio -import agent_control -from agent_control import control, ControlViolationError - -# Protect any function (like LLM calls) - -@control() -async def chat(message: str) -> str: - # In production: response = await LLM.ainvoke(message) - # For demo: simulate LLM that might leak sensitive data - if "test" in message.lower(): - return "Your SSN is 123-45-6789" # Will be blocked! - return f"Echo: {message}" - -# Initialize your agent - -agent_control.init( - agent_name="awesome_bot_3000", # Unique name - agent_description="My Chatbot", -) - -async def main(): - try: - print(await chat("test")) # ❌ Blocked - except ControlViolationError as e: - print(f"❌ Blocked: {e.control_name}") - -asyncio.run(main()) -``` - -## Step 4: Add Controls - -The easiest way to add controls is through the UI — see the [UI Quickstart](/core/ui-quickstart) for a step-by-step guide. Alternatively, use the SDK as shown below or call the API directly. - -Run following setup script to create controls to protect your agent. - -```python -# setup.py - Run once to configure agent controls - -import asyncio -from datetime import datetime, UTC -from agent_control import AgentControlClient, controls, agents -from agent_control_models import Agent +from agent_control import AgentControlClient, controls async def setup(): - async with AgentControlClient() as client: # Defaults to localhost:8000 - # 1. Register agent first - agent = Agent( - agent_name="awesome_bot_3000", - agent_description="My Chatbot", - agent_created_at=datetime.now(UTC).isoformat(), - ) - await agents.register_agent(client, agent, steps=[]) - - # 2. Create control (blocks SSN patterns in output) + async with AgentControlClient() as client: control = await controls.create_control( client, name="block-ssn", @@ -168,172 +85,84 @@ async def setup(): "action": {"decision": "deny"}, }, ) - - # 3. Associate control directly with agent - await agents.add_agent_control( - client, - agent_name=agent.agent_name, - control_id=control["control_id"], - ) - - print("✅ Setup complete!") - print(f" Control ID: {control['control_id']}") + print(f"✅ Control created: {control['control_id']}") asyncio.run(setup()) ``` -Now, run your agent code. - -**🎉 Done!** Your agent now blocks SSN patterns automatically. - -> [**!NOTE**] -> **Authentication Note:** Authentication is disabled by default in the server .env (`AGENT_CONTROL_API_KEY_ENABLED=false`). If you enable it, this setup script needs an admin API key because it creates a control and attaches it to an agent. `agents.register_agent()` accepts a regular or admin key, but `controls.create_control()` and `agents.add_agent_control()` require a key listed in `AGENT_CONTROL_ADMIN_API_KEYS`. -> -> In the example .env, the placeholders are: -> -> - **Regular API key(s):** `AGENT_CONTROL_API_KEYS` (e.g., "my-ui-key") -> - **Admin API key(s):** `AGENT_CONTROL_ADMIN_API_KEYS` (e.g., "my-admin-key") -> -> **Replace these defaults before any shared or production deployment.** - -**With authentication enabled:** - ```bash -curl -L https://raw.githubusercontent.com/agentcontrol/agent-control/refs/heads/main/docker-compose.yml | AGENT_CONTROL_API_KEY_ENABLED=true AGENT_CONTROL_API_KEYS="my-ui-key" AGENT_CONTROL_ADMIN_API_KEYS="my-admin-key" AGENT_CONTROL_SESSION_SECRET="some-long-random-string" CORS_ORIGINS="http://localhost:4000" docker compose -f - up -d +python setup_control.py ``` +## Step 3: Protect Your Agent -### What Is Happening Under the Hood - -![Agent Control Architecture](/images/Architecture.png) - -1. Your app calls `chat("test")` - -2. Function executes and returns `"Your SSN is 123-45-6789"` - -3. `@control()` decorator sends output to Agent Control server - -4. Server checks the output against all controls -5. `block-ssn` control finds SSN pattern → matches -6. Server returns `is_safe=False` with the matched control -7. SDK raises `ControlViolationError` and blocks the response - -Key Benefits: - -- ✅ Controls are managed **separately** from your code - -- ✅ Update controls **without redeploying** your agent - -- ✅ Same controls can protect **multiple agents** - -- ✅ View analytics and control execution in the dashboard - -## Performance - -| Endpoint | Scenario | RPS | p50 | p99 | -|----------|----------|-----|-----|-----| -| Agent init | Agent with 3 tool steps | 509 | 19 ms | 54 ms | -| Evaluation | 1 control, 500-char content | 437 | 36 ms | 61 ms | -| Evaluation | 10 controls, 500-char content | 349 | 35 ms | 66 ms | -| Evaluation | 50 controls, 500-char content | 199 | 63 ms | 91 ms | -| Controls refresh | 5-50 controls per agent | 273-392 | 20-27 ms | 27-61 ms | - -- Agent init handles both create and update identically (create-or-update operation). -- All four built-in evaluators (regex, list, JSON, SQL) perform within 40-46 ms p50 at 1 control. -- Moving from 1 to 50 controls increased evaluation p50 by about 27 ms. -- Local laptop benchmarks are directional and intended for developer reference. They are not production sizing guidance. - -_Performance tested on Apple M5 (16 GB RAM), Docker Compose (`postgres:16` + `agent-control`). 2 minutes per scenario, 5 concurrent users for latency (p50, p99), 10-20 for throughput (RPS). RPS = completed requests per second. All scenarios completed with 0% errors._ - -## Configuration - -### Environment Variables +Add the `@control()` decorator to any function you want to protect. Agent Control will intercept the output and check it against your controls. -| Variable | Default | Description | -|----------|---------|-------------| -| `AGENT_CONTROL_URL` | `http://localhost:8000` | Server URL for SDK | -| `AGENT_CONTROL_API_KEY` | — | API key for authentication (if enabled) | -| `DB_URL` | `postgresql+psycopg://agent_control:agent_control@localhost:5432/agent_control` | Database connection string (SQLite: `sqlite+aiosqlite:///./agent_control.db`) | -| `GALILEO_API_KEY` | — | Required for Luna-2 AI evaluator | - -### Server Configuration - -The server supports additional environment variables: - -- `AGENT_CONTROL_API_KEY_ENABLED` - Enable API key authentication (default: `false`) -- `AGENT_CONTROL_API_KEYS` - Valid API keys for runtime/read access when auth is enabled -- `AGENT_CONTROL_ADMIN_API_KEYS` - Admin API keys required for control-plane mutations -- `LOG_LEVEL` - Logging level (default: `INFO`) - -See [Server Docs](/components/server) for complete server configuration. +```python +# my_agent.py ---- +import asyncio +import agent_control +from agent_control import control, ControlViolationError -## Agent Control Components +agent_control.init( + agent_name="my_chatbot", + agent_description="My first protected agent", +) -Agent Control is built as a monorepo with these components: +@control() +async def chat(message: str) -> str: + # In production: response = await llm.ainvoke(message) + if "test" in message.lower(): + return "Your SSN is 123-45-6789" # Will be blocked! + return f"Echo: {message}" -- **[Server](/components/server)** - FastAPI server handling control evaluation, agent registration, and analytics -- **[Engine](/components/engine)** - Evaluation engine that orchestrates control checks and applies actions -- **[Models](/components/models)** - Shared data models and schemas used across all components -- **[Evaluators](/components/evaluators)** - Built-in and AI-powered evaluators (regex, list, JSON, SQL, Luna-2) -- **[UI](/components/ui)** - Next.js dashboard for managing controls, agents, and viewing analytics -- **SDKs** - Python and TypeScript client libraries for integrating with your agents +async def main(): + # This will be allowed + print(await chat("hello")) # Output: Echo: hello ---- + # This will be blocked — output contains an SSN pattern + try: + print(await chat("test")) + except ControlViolationError as e: + print(f"❌ Blocked by: {e.control_name}") -## Development - -### Directory Structure - -```text -agent-control/ -├── sdks/python/ # Python SDK (agent-control) -├── sdks/typescript/ # TypeScript SDK (generated) -├── server/ # FastAPI server (agent-control-server) -├── engine/ # Evaluation engine (agent-control-engine) -├── models/ # Shared models (agent-control-models) -├── evaluators/ # Evaluator implementations (agent-control-evaluators) -├── ui/ # Next.js web dashboard -├── scripts/ # Build scripts -└── examples/ # Usage examples +asyncio.run(main()) ``` -### Makefile Commands - -The project uses a Makefile for common tasks: - -| Command | Description | -|---------|-------------| -| `make sync` | Install dependencies for all workspace packages | -| `make test` | Run tests across all packages | -| `make lint` | Run ruff linting | -| `make lint-fix` | Run ruff with auto-fix | -| `make typecheck` | Run mypy typechecking | -| `make check` | Run all quality checks (test + lint + typecheck) | -| `make server-run` | Start the server | -| `make server-` | Forward commands to server (e.g., `make server-alembic-upgrade`) | -| `make sdk-` | Forward commands to SDK (e.g., `make sdk-test`) | -| `make engine-` | Forward commands to engine (e.g., `make engine-test`) | - ---- +```bash +python my_agent.py +``` -## Next Steps +**🎉 Done!** Your agent now blocks SSN patterns automatically. -- **Add more controls:** See [Controls](/concepts/controls#defining-controls) for examples and guidance +### What Is Happening Under the Hood -- **Explore evaluators:** See [Evaluators](/concepts/evaluators/overview) or create custom evaluators. See [DeepEval example](/examples/deepeval) for custom evaluator examples +![Agent Control Architecture](/images/Architecture.png) -- **Production setup:** Enable authentication — see the [Reference](/core/reference#authentication) +1. Your app calls `chat("test")` +2. The function returns `"Your SSN is 123-45-6789"` +3. The `@control()` decorator sends the output to the Agent Control server +4. The server checks the output against all controls associated with this agent +5. `block-ssn` finds an SSN pattern → match +6. The server returns `is_safe=False` +7. The SDK raises `ControlViolationError` and blocks the response -- **Check examples:** See [Examples](/examples/overview) for real-world patterns +Key Benefits: -> **💡 Pro Tip:** Start with simple regex controls, then graduate to AI-powered evaluators for complex safety checks. +- ✅ Controls are managed **separately** from your code +- ✅ Update controls **without redeploying** your agent +- ✅ Same controls can protect **multiple agents** +- ✅ View analytics and control execution in the [dashboard](/core/ui-quickstart) -## What’s Next +## What's Next + + Manage agents and controls visually through the dashboard. + + Learn about controls, selectors, evaluators, and actions. @@ -342,4 +171,8 @@ The project uses a Makefile for common tasks: See working integration examples with LangChain, CrewAI, and more. + + Server configuration, authentication, and deployment options. + + diff --git a/core/ui-quickstart.mdx b/core/ui-quickstart.mdx index 85896e3..aba6f37 100644 --- a/core/ui-quickstart.mdx +++ b/core/ui-quickstart.mdx @@ -6,22 +6,21 @@ icon: "browser" The Agent Control dashboard lets you manage [controls](/concepts/controls) and monitor agent activity — no code changes required. -## Prerequisites +## Open the Dashboard -Before starting the UI, make sure the **Agent Control server** is already running. If you haven't set it up yet, follow the [Quickstart](/core/quickstart) first. +If you followed the [Quickstart](/core/quickstart), the dashboard is already running. Open [http://localhost:8000](http://localhost:8000) in your browser. -You also need: +You should see an empty state — this is expected before any controls are created. -- **Node.js 20+** (CI uses 20; 18+ may work) -- **pnpm 9+** — install from [pnpm.io](https://pnpm.io/) or run `corepack enable && corepack prepare pnpm@latest --activate` +![Dashboard with no controls at startup](/images/no-controls-at-startup.png) -> **Note:** If you started the server using **One-line setup** from the [Quickstart](/core/quickstart), the UI is already running at [http://localhost:4000](http://localhost:4000). You can skip the setup steps below and jump directly to [viewing the dashboard](#create-controls-from-the-ui). + -## Start the UI Server +If you cloned the `agent-control` repository and started the server with `make server-run`, you need to start the UI separately: - - -From the root of the `agent-control` repository, run the following commands in a **separate terminal**: +**Prerequisites:** +- **Node.js 20+** (CI uses 20; 18+ may work) +- **pnpm 9+** — install from [pnpm.io](https://pnpm.io/) or run `corepack enable && corepack prepare pnpm@latest --activate` ```bash cd ui @@ -29,21 +28,13 @@ pnpm install pnpm dev ``` -The dashboard is now running at [http://localhost:4000](http://localhost:4000). +The dashboard will be running at [http://localhost:4000](http://localhost:4000). Keep the Agent Control server (`make server-run`) and the UI (`pnpm dev`) running in separate terminal windows. The dashboard communicates with the server at `http://localhost:8000` by default. - - -Open [http://localhost:4000](http://localhost:4000). You should see an empty state — this is expected before any controls are registered. - -![Dashboard with no controls at startup](/images/no-controls-at-startup.png) - -The dashboard reflects the server's current configuration. Controls appear here automatically once you create them. - - + ## Create Controls from the UI @@ -81,14 +72,6 @@ Click **Save** to register the control. It takes effect immediately — no redep -## Regenerate API Types (Optional) - -If you update the server API and need fresh UI types, regenerate them from the running server: - -```bash -pnpm fetch-api-types # fetches from http://localhost:8000/openapi.json -``` - ## Monitoring The monitoring dashboard shows real-time control activity across all agents: