AGENT-33

Local-First Multi-Agent Orchestration Platform

_{Governance · Evidence · Workflows · Multi-tenant Isolation · Observability}

Local-First · Approval-gated automation · Audit trail by design · Multi-tenant

Quick Start  ·  Architecture  ·  API Reference  ·  Onboarding

Use Cases  ·  Walkthroughs  ·  Self-Improvement  ·  Operator Runbooks

---

At a Glance

AGENTS 6 Reference agent definitions

WORKFLOWS DAG Composable, with retries

TOOLS 7 Schema-validated builtins

SUBSYSTEMS 20+ Lifespan-wired services

LLM PROVIDERS 20+ Auto-registered from env

TENANCY Native Multi-tenant by design

---

Why AGENT-33

AGENT-33 is a local-first AI agent orchestration platform for teams that want real workflows, explicit governance, and a usable control plane instead of a pile of disconnected scripts. It combines an API runtime, workflow engine, memory stack, review/release controls, and a first-party frontend so you can run guarded automation from one system.

• Local-first runtime — FastAPI backend, Docker Compose bootstrap, Ollama-friendly model routing
• Contained Agent OS — optional Linux operator workspace with first-party tools, state, and stack connectivity
• Guardrailed automation — scopes, approvals, autonomy budgets, and review/release workflows
• Agent + workflow orchestration — invoke agents directly or compose repeatable DAG workflows
• Operational visibility — health, dashboard surfaces, traces, evaluations, and rollout telemetry
• Extensible platform — packs, tools, memory, webhook intake, and improvement loops

flowchart LR
    U[Operator / Client] -->|HTTP · WebSocket · SSE| API[FastAPI Surface]
    API --> AR[Agent Runtime]
    AR --> WF[Workflow Engine<br/>DAG · retries · checkpoints]
    AR --> SK[Skill Registry<br/>L0 / L1 / L2 disclosure]
    AR --> TG[Tool Governance<br/>allowlist · autonomy · approvals]
    AR --> MEM[(Memory<br/>pgvector + BM25 RRF)]
    WF --> TP[Trace Pipeline<br/>failure taxonomy · retention]
    TG --> TP
    AR --> TP

    style API fill:#0ea5e9,color:#fff
    style AR fill:#10b981,color:#fff
    style TG fill:#ef4444,color:#fff
    style TP fill:#f59e0b,color:#fff
    style MEM fill:#8b5cf6,color:#fff

Loading

For the full lifespan startup order, runtime modes (lite, standard, enterprise), and middleware chain, see docs/architecture/overview.md.

---

Repository Layout

• engine/ — FastAPI runtime, orchestration services, API routes, tests, Docker Compose stack
• frontend/ — AGENT-33 control plane UI served at http://localhost:3000
• core/ — orchestration specs, policy packs, protocol references, workflow materials
• docs/ — canonical operator, setup, onboarding, and release-readiness documentation

---

Quick Start

30-Second Try

Spin up the stack and confirm it's alive in under a minute:

cd engine && docker compose up -d
curl http://localhost:8000/health

Then continue below for the full operator setup (JWT minting, agent invocation, control plane).

Full Operator Setup

Prerequisites

• Docker Desktop or Docker Engine with Compose
• Python 3.11+
• curl
• Ollama reachable from the stack (http://host.docker.internal:11434 by default), or use the bundled/local override paths documented in the setup guides

1. Start the stack

cd engine
cp .env.example .env
docker compose up -d
curl http://localhost:8000/health

If you reuse an Ollama container from another Compose project:

docker compose -f docker-compose.yml -f docker-compose.shared-ollama.yml up -d

2. Open the control plane

• Frontend: http://localhost:3000
• API docs: http://localhost:8000/docs

Default local credentials from .env.example:

• username: admin
• password: admin

3. Mint a local JWT for API access

docker compose exec -T api python -c "import os,time,jwt; now=int(time.time()); payload={'sub':'local-admin','scopes':['admin','agents:read','agents:write','agents:invoke','workflows:read','workflows:write','workflows:execute','tools:execute'],'iat':now,'exp':now+3600}; print(jwt.encode(payload, os.getenv('JWT_SECRET','change-me-in-production'), algorithm=os.getenv('JWT_ALGORITHM','HS256')))"

Set the token in your shell:

export TOKEN="<paste-token-here>"

PowerShell:

$env:TOKEN = "<paste-token-here>"

4. Verify the first agent flow

List agents:

curl http://localhost:8000/v1/agents/ \
  -H "Authorization: Bearer $TOKEN"

Invoke the orchestrator:

curl -X POST http://localhost:8000/v1/agents/orchestrator/invoke \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "task": "Create a short rollout plan for adding cache metrics"
    },
    "model": "llama3.2",
    "temperature": 0.2
  }'

First 5-Minute Operator Path

1. Start the stack and confirm /health
2. Sign in to http://localhost:3000
3. Mint a local JWT or use the UI token flow
4. List agents with GET /v1/agents/
5. Invoke an agent or execute a minimal workflow
6. Explore the dashboard, traces, reviews, evaluations, and autonomy surfaces from the UI

For a fuller beginner path, use:

• Getting Started
• Operator Onboarding
• Walkthroughs

Security and Production Warning

Bootstrap auth is for local development only. Do not expose AGENT-33 publicly with default credentials or default secrets.

Before any shared, VPS, or production deployment:

• set AUTH_BOOTSTRAP_ENABLED=false
• rotate API_SECRET_KEY
• rotate JWT_SECRET
• rotate ENCRYPTION_KEY
• review SECURITY.md
• work through the Release Checklist

Documentation Map

Start here

• Getting Started
• Operator Onboarding
• Setup Guide
• Walkthroughs
• Use Cases
• Agent OS Runtime
• API Surface
• Release Checklist
• Documentation Index

Deep references

• Functionality and Workflows
• Production Deployment Runbook
• Operator Verification Runbook
• Horizontal Scaling Architecture
• Incident Response Playbooks

Who this is for

• Operators who need a guarded local or self-hosted AI control plane
• Platform teams building approval-aware automation and workflow execution
• Engineering teams running review, release, evaluation, and autonomy gates in one runtime
• Researchers and builders experimenting with packs, memory, training, and improvement loops

Roadmap

AGENT-33 is under active development. Near-term public direction:

• Ecosystem growth — broader pack catalog, community-contributed skills and tools, signed pack distribution
• MCP integrations — richer hosted MCP server surface and tighter MCP client interop with the agent runtime
• Public benchmarking — continued evaluation against SkillsBench with CTRF reporting and weekly full-tier runs
• Provider depth — first-class support for additional local-inference backends (llama.cpp, LM Studio, AirLLM) and embedding providers
• Operator UX — visual workflow builder polish, sub-agent execution trees, knowledge ingestion cron expansion

See CHANGELOG.md for release history.

Contributors

Every commit, issue, review, and Discussion thread makes the project better. Thank you.

Star History

License

Apache License 2.0. See LICENSE.

---

Documentation  ·  API Reference  ·  Architecture  ·  Changelog  ·  Presentation Suite  ·  Discussions

_{AGENT-33 v2.1.0 · Apache License 2.0 · Local-first multi-agent orchestration with built-in governance}