Architecture

This page describes how the SMELT engine works under the hood. It is background reading - none of it is required to use SMELT Studio, which runs all of this for you as a hosted product.

When a workflow runs, blocks are dispatched through these layers - from the Wire API gateway through NATS to the agent workers and back.

System diagram

Layer summary

• Ingress - FastAPI: validates requests, stamps trace IDs, publishes to NATS (e.g. tasks.new). Rate limiting and JWT/API key authentication at the edge. No business logic.
• Event bus - NATS JetStream: durable at-least-once delivery, consumer groups, replay for debugging.
• Orchestrator - Python asyncio: consumes messages, runs a Pydantic state machine (TaskStatus), dispatches WorkItem, collects WorkResult. Supports multi-step chains and retry logic. No LangGraph dependency.
• Worker agents: nine run. Five carry a model: PlannerAgent (goal decomposition into a sequenced sub-task DAG with dependencies), ResearchAgent (tenant-scoped pgvector retrieval, then synthesis over what it retrieved), ReasoningAgent (chain-of-thought with self-consistency voting and critique loop), ActionAgent (httpx tool executor with SSRF rejection and a PendingApproval human-in-the-loop gate), and ValidatorAgent (output quality assurance with rubric evaluation and critique loop). Four more carry none: ContentSafetyAgent, and the knowledge workers RetrieveAgent, IngestAgent and PurgeAgent. Workflow steps communicate over the bus; sub-agent delegation runs in-process inside the supervising agent’s worker and is recorded on the same run trace.
• Memory: Redis (working / TTL), Postgres (episodic run history), pgvector (semantic retrieval with deduplication). Treating these as one database is an explicit anti-pattern.
• Rust router: NATS and tonic gRPC for hot-path fan-out. Python calls Rust where throughput matters.
• Observability: OpenTelemetry spans per LLM call (model, tokens, latency, credits) with structlog binding trace_id, agent_id, task_id. Jaeger for trace visualisation.
• SMELT Studio: hosted workflow platform with visual builder, real-time execution monitoring, task timeline, and trace views.
• Deployment: SMELT runs on Azure Container Apps. A deploy rolls a new revision without dropping traffic. The API layer runs several replicas; the agent workers run a fixed pool, so heavy fan-out queues rather than adding workers.

Technology stack

The stack SMELT runs on:

Start in SMELT Studio or read Getting Started.