Architecture
System overview
Section titled “System overview”Alquimia Platform has two layers:
┌─────────────────────────────────────────────────────────────┐│ External clients ││ (HTTP, SSE, Slack, WhatsApp, Email) │└──────────────────────┬──────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────┐│ alquimia-runtime ││ ││ Auth · Registry · Event ingestion · SSE streaming ││ Redis (state) · PostgreSQL (persistence) · S3 (blobs) │└──────────────────────┬──────────────────────────────────────┘ │ CloudEvents ▼┌─────────────────────────────────────────────────────────────┐│ alquimia-core ││ ││ Controller · Stages · Worklog · Execution loop ││ Tools · Memory · Evaluation · Shields · Knowledge │└─────────────────────────────────────────────────────────────┘alquimia-runtime handles HTTP, authentication, session state, and event routing. It delegates all agent reasoning to alquimia-core, which executes the agent step by step and emits a complete audit trail.
Runtime topology
Section titled “Runtime topology”The runtime exposes a single HTTP API and runs in one of two roles from the same container image:
| Role | Responsibility | HTTP exposure |
|---|---|---|
| Master | Receives external requests, manages registry and context, publishes events | Full API |
| Worker | Consumes events, executes inference, emits results back to the bus | Health probes only |
In production, you run one or more master replicas and one or more worker replicas. The master publishes events to an event bus; workers consume them and run the core engine. Workers are stateless, so you can scale them to match throughput.
A single-process all mode is available for local development or small deployments where separate master and worker containers are impractical.
The execution pipeline
Section titled “The execution pipeline”Every inference request flows through a three-stage pipeline inside the core engine:
Incoming request │ ▼┌─────────────┐│ Preprocess │ Shields · attachment normalization · safety checks└──────┬──────┘ │ ▼┌─────────────┐│ Process │ Tool discovery · LLM calls · tool execution loop└──────┬──────┘ │ ▼┌─────────────┐│ Answer │ Memory flush · context persistence · final response└─────────────┘Each stage emits commands for work it needs done and processes responses as they arrive. The pipeline continues until a final response is produced or an unrecoverable error occurs.
Async inference flow
Section titled “Async inference flow”Inference is non-blocking. The master does not execute agents directly; it hands work to workers through the event bus.
- A client posts a request to the master.
- The master validates authentication and the agent registry entry, then publishes an inference event to the event bus.
- The master immediately returns a task identifier to the client.
- A worker consumes the event and runs the agent through the core engine.
- The worker writes progress records to a state store.
- The client opens a streaming endpoint using the task identifier and receives progress events until the final response arrives.
Client Master Event bus Worker State store │ │ │ │ │ │ POST │ │ │ │ │──────────>│ │ │ │ │ │ publish │ │ │ │ │─────────────>│ │ │ │ task_id │ │ │ │ │<──────────│ │ │ │ │ │ │ consume │ │ │ │ │─────────────>│ │ │ │ │ │ execute │ │ GET │ │ │ write │ │ stream │ │ │─────────────>│ │──────────>│ │ │ │ │ │ read │ │ │ │ │<───────────────────────────────────────────│ │ SSE │ │ │ │ │<──────────│ │ │ │This design decouples request acceptance from execution. Long-running agents with many tool calls do not block HTTP connections, and workers can be scaled independently.
Event bus
Section titled “Event bus”All master-to-worker communication uses a signed event bus. Events carry a standard envelope and an integrity signature. Workers reject any event with a missing or invalid signature, preventing unauthorized execution requests.
The event bus also carries intermediate results such as tool outputs, shield verdicts, and memory flushes back into the execution pipeline.
State and persistence
Section titled “State and persistence”| Store | Purpose | Typical backend |
|---|---|---|
| State store | Task progress, session context, distributed locks | Redis |
| Persistent store | Audit worklog, knowledge base metadata, webhooks | PostgreSQL |
| Blob store | Uploaded files, audio, large attachments | S3-compatible object store |
| Vector store | RAG chunks and embeddings | Qdrant, Redis, or in-memory |
Knowledge and shields
Section titled “Knowledge and shields”Agents retrieve context from multiple knowledge source types through a single abstraction:
| Search mode | Behavior |
|---|---|
rag | Retrieve semantically similar chunks for every inference |
on_demand | Expose a search tool the agent invokes explicitly |
direct | Expose file-listing and reading tools over topic files |
brain | Query a registered Boltzmann Brain with per-module authorization |
Shields are pre-inference classifiers that run in the preprocess stage. They can observe, flag, or block requests before the LLM is invoked. The built-in prompt-injection detector is fail-closed, so a classification failure defaults to blocking.
Key design decisions
Section titled “Key design decisions”Event bus for coordination. Decoupling masters and workers through an event bus makes the system horizontally scalable and resilient to slow or failing workers.
Signed events. Every event is signed before publishing and verified before dispatch. This prevents a compromised worker or misconfigured client from injecting unauthorized execution commands.
Registry-driven configuration. Agent configurations are stored in a registry and can be distributed as OCI artifacts. This enables version-controlled, portable agent packages that can be validated and promoted independently of the runtime.
Observability by default. Every inference run carries shared dimensions such as agent, agentspace, session, user, and task identifiers. These dimensions propagate through metrics, traces, and logs for cross-signal correlation.
Related pages
Section titled “Related pages”- Event-driven execution — the typed command/response system
- Agents & configuration — how agent specs work
- Memory & context — short-term, long-term, and knowledge-base memory
- Tools & integrations — MCP, Llama Stack, A2A, and Python modules
- Observability — metrics, traces, logs, and correlation
- Auditability & compliance — the worklog as evidence