Reference · How it works

01

Glossary

The terms used on this page, in one line each.

Agent: A model given a job, a prompt and some tools. Here: triage (classify) and resolver (look up and draft).
Tool call: The model asking the platform to run a function, such as “get this order”, instead of guessing.
Structured output: The model answers by filling a JSON schema, so the platform can check the answer field by field.
Proposal: Something an agent wants to do to the outside world (send a reply, refund). Nothing happens until a person approves.
Risk tier: How dangerous an action is: 0 read, 1 draft, 2 send to a customer, 3 move money. Higher tiers need a human.
Guard: A deterministic check on the agent's output, run before anything is proposed.
Gateway: The single door between an agent and data: it only opens for the tools the agent was granted.
Database role: A database login with its own permissions. The agents' role simply has no permission to refund or send.
RLS: Row level security: Postgres rules about who may read which rows. The dashboard can read runs, not customers.
Queue: A waiting list of work. A ticket is queued, then a worker picks it up; nothing is lost if a worker stops.
Idempotent: Doing it twice has the same effect as doing it once: a repeated message, approval or retry changes nothing.
Backoff: Waiting longer after each failed attempt (5s, 10s, 20s), so a struggling service is not hammered.
Dead letter queue: Where a job goes after its last failed attempt, to wait for a person instead of being lost.
Fallback: When one model provider fails, the next one in the chain answers instead.
Circuit breaker: After repeated failures a provider is skipped for a while, then tested with a single call.
Trace: The complete record of one ticket's processing: every model call, tool call and decision, in order.
Evaluation: Running the agents on tickets with known right answers and scoring the result.
Gate: The rule that decides whether a change may be merged, based on the evaluation.
LLM judge: A second model that grades the first one's reply against a written rubric.
Realtime: The database pushes every change to the dashboard, which is why it updates by itself.

02

Stack and code map

What it is built with, and where each idea lives in the repository.

Core: Python 3.12, FastAPI, psycopg 3, Pydantic
Models: Mistral and Anthropic over plain HTTP; offline stand-in for keyless runs
Data: Supabase: Postgres 17, Realtime, row level security
Automation: n8n: intake webhook, contact form, traffic, daily report, error handler
Tracing: Langfuse, self-hosted, via its ingestion API; datasets and scores for evals
Approvals: Dashboard and Telegram inline buttons
Dashboard: Next.js 16, React 19, Tailwind 4
Quality: pytest, ruff, golden-suite evaluation gate in GitHub Actions
Deployment: Google Cloud: Cloud Run, Terraform (in progress)

Code map

core/src/agentdesk/api.pyHTTP API: tickets, decisions, dead-letter retries, fault injection, /meta, /stats, /simulate
core/src/agentdesk/worker.pyWorker threads, LISTEN/NOTIFY wake-up, lease reclaim, dead letters
core/src/agentdesk/pipeline.pyTriage → resolve → guards → proposals, idempotent and atomic
core/src/agentdesk/llm/Mistral and Anthropic adapters, the offline stand-in, the router with retry, fallback and breakers
core/src/agentdesk/gateway.pyGranted tools, bound to the ticket's sender
core/src/agentdesk/guards.pyBlocks and flags on agent output
core/src/agentdesk/approvals.pyThe only code that refunds or sends
core/src/agentdesk/telegram.pyApproval cards, digest, deduplicated alerts
core/src/agentdesk/evals/Golden suite runner, assertions, judge
core/evals/golden.yamlThe evaluation cases
supabase/migrations/Schema, roles, grants and RLS: where governance is enforced
n8n/build.pyThe n8n workflows, authored as data
dashboard/This Next.js app, live through Supabase Realtime
.github/workflows/ci.ymlLint, tests and the evaluation gate on every push

03

Where things live

The n8n folder, the Langfuse project and the local services, one click away.