Reference Architectures Overview

Each reference architecture describes a production-shaped deployment: the components, the data flow, the failure modes and the trade-offs that led to the shape. They are starting points to be adapted, not blueprints to be copied verbatim.

How each page is structured

1. When to use it — the conditions under which this shape is the right answer.
2. Diagram — components and the direction of data flow.
3. Components — what each piece is responsible for.
4. Failure modes — what breaks first, and what the blast radius is.
5. Trade-offs — what you are giving up by choosing this.

Choosing between them

If your constraint is…	Start with
Data residency, or a single large customer per deployment	Single-Tenant Agent Platform
High ingest volume with retrieval-heavy agents	Event-Driven RAG Pipeline

Assumptions common to all architectures

• Agent revisions are immutable and promoted, never rebuilt per environment.
• Secrets are resolved at cold start from the workspace secret store, never baked into artefacts.
• Every MCP server is pinned to an exact version per environment.
• Traces are sampled in production, not disabled — an unobservable agent cannot be operated.

Note

Cost figures are deliberately omitted. They move too quickly to keep accurate here, and the dominant term is almost always model token spend rather than platform infrastructure.