Concepts

Agency runs AI agents as persistent, auditable backend processes — not one-off chat scripts. Tagline: intelligence as a process, not a script.

Django + PostgreSQL hold application state; LangGraph/LangChain drive each invoke. Code and the Framework pages are the source of truth for signatures and behaviour.

Repos

Product, host, and umbrella roles: Architecture.

Domain lifecycle

Provider → Model → Agent (+ Tools) → Mission
     → Execution → Thread → Run(s) → Checkpoint
                          ↘ Interruption (HITL) → resume → new Run

  • Provider — inference backend (kind: ollama, openai, fal, or openai-compatible). URL plus the name of the API-key env var; the secret stays in Compose .env. Boot seeds Ollama, OpenAI (gpt-4o-mini / gpt-4o), and FAL. Uncustomized Veronica uses Ollama when it is chat-ready, otherwise gpt-4o-mini.

  • Model — LLM row under a Provider (Agent.model FK). Temperature and Ollama num_ctx live in metadata.

  • Execution — business intent.

  • Thread — persistent timeline / LangGraph thread_id.

  • Run — one technical attempt; interrupted Runs stay interrupted; resume creates a new Run.

  • Interruption — durable HITL; workers are not held open waiting.

  • Celery Task ≠ Execution/Run — transport only.

Narratives: Execution Runtime, Agent Runtime, Celery and Agency lifecycle. Tutorials: Tutorials.

Realtime

DB commit → signals → Channels projection.

  • Messenger — conversation · Monitor — run telemetry · Catalog — explorer CRUD

Details: Realtime, contract Connections.

Knowledge

  • RAG (agency.corpus) — Tenant → Workspace → Document → Chunk → vector store

  • miner — Scrap → Block (ingest; not the RAG index)

UI

Schema-driven Agency desktop. Backend owns domain + producers; agency-ui owns rendering (UI). Mission Control is the desktop app for Agents, Missions, and Executions — not the whole SPA (Mission Control). Operator chrome also includes the Media player (images / YouTube) and Map (dark chart + satellite pane); kiosks are agency.display, not those windows.

Principles (short)

  1. Database is the source of truth; WebSockets are projections.

  2. Execution ≠ Run; resume = new Run on the same Thread.

  3. HITL is explicit and auditable.

  4. Keep agency-django free of host-only logic.

Longer product vision (Spanish, workspace): agency-workspace/CONTEXT.md. Doc surface map: workspace README.md (Documentation architecture). Single-file HTML: ./dev doc → /static/documentation-single/.