Image & video production
The visual layer
of your next product.
Explore Higgsfield for image and video creation. Keep asset generation separate from publishing so you can inspect each result.
Explore Higgsfield Affiliate linkFrankX / AI architecture
Your next idea.
Built as a system.
Open the architecture. Inspect the code. Deploy a starting point you can make your own.
FrankX retrieval and agent-team starters sit beside maintained cloud references. Every preview names the setup work that remains.
Explore the systems01 / Intelligence campusOriginal AI-generated editorial artwork
Inside the build
From the idea
to the moving parts.
Choose a system. Follow its boundaries. Select a component to see what it owns, then open the source or deployment setup.
FrankX · MIT starter
Give every answer a source.
Ingest documents, retrieve relevant passages, and stream an answer with citations. Inspect the seams before you connect your own data.
Deploy to Vercel Inspect the sourceBefore you deploy
- Vercel account
- Supabase project + schema.sql
- Your OpenAI API key
Architecture previewReact Flow / source-backed
Loading the architecture canvas… The component list below remains available.
Connects to: Document ingestion · Retrieve + rerank
Connects to: Document store
Connects to: Grounded response
Connects to: Retrieve + rerank
Output boundary
Selected component / Next.js
Chat interface
app/page.tsx sends your query and a per-request provider key. The UI renders streamed text and source references.
What this preview shows. The diagram describes the linked implementation. It does not run a model or show live telemetry. Starter scope: add authentication, document permissions, rate limits, and retrieval evaluation before serving private data.
The tools behind the system
Build the workflow.
Make the output worth seeing.
Connect automation to a real app, then bring image and video production into the workflow when the work calls for it.
The Higgsfield link is an affiliate link. If you buy through it, I may earn a commission at no extra cost to you.
The visual layer
Automation
n8n + workers
Provision the editor, queue, database, and workers. Add your workflows after setup.
Open n8n deploymentLocal AI
n8n + Ollama + Qdrant
Inspect n8n’s Docker Compose starter and included chat workflow. Review its production limits before hosting it.
Get the self-hosted starterChoose your next move
Start with code.
Get help with the hard decisions.
Open starters give you an inspectable foundation. For a workflow bundle or a review of your own architecture, follow the dedicated offer.
01 / Workflow bundle
System Architect Starter Kit
Inspect the n8n and content workflow offer, its contents, and launch availability.
02 / Architecture reviewFind the decision to close first.
Review model access, loop boundaries, retrieved context, and where a long run lives.
03 / Work with FrankBring your own system.
Discuss an architecture workshop, implementation sprint, or advisory engagement.
Request-scoped
Own the experience
Streaming UI, authentication, API entry, preview delivery. Anything a person is actively waiting on.
Durable runtime
Run persistent work
Workers, queues, databases, MCP services, long jobs. Anything that outlives the request that started it.
Managed service
Rent the hard parts
Model endpoints, governed data, hosted evaluation. Buy these where their governance or scale earns the dependency.
Where a long run lives
The platform question is one question, and it is not which logo.
An agent loop that runs for eleven minutes is a different deployment problem from a completion that returns in two seconds. Every platform below answers it; they differ in what they hand you and what they leave you operating.
Official source atlas
Start from maintained architecture, then adapt it deliberately.
Filtered by the same seven planes the field guide uses below. Pick the plane you cannot currently name an owner for — that is where the next incident comes from.
VercelExperience
Streaming agent interface
A Next.js agent surface with streamed responses, tool results, authentication, persistence, and model routing.
Use it for: Public AI products, internal copilots, and fast product iteration.
Request-scoped
- Next.js
- AI SDK
- Model gateway
- Postgres
OpenTelemetryObservability
Agent observability pipeline
Vendor-neutral traces, metrics, and logs that connect frontend requests to model calls, tools, workers, and failures.
Use it for: Cross-cloud systems that need one evidence trail across Vercel, Railway, and GCP.
Runs either way
- Application
- OTel SDK
- Collector
- Backend
promptfooEvaluation
Declarative eval harness
A YAML matrix of prompts, providers, and test cases, scored by deterministic assertions or model graders and diffed side by side in CI.
Use it for: Deciding whether a prompt or model change helped, before it reaches users.
Runs either way
- Test cases
- Providers
- Assertions
- Results viewer
GoogleOrchestration
Multi-agent team with ADK
ADK composes coordinator, specialist, sequential, parallel, loop, and graph workflows in code.
Use it for: Teams standardizing agent roles, tools, sessions, and evaluation on Google Cloud.
Runs either way
- Web client
- Coordinator agent
- Specialist agents
- Tools + model
OpenAIOrchestration
Tool-using agent service
Agents, handoffs, guardrails, sessions, human-in-the-loop controls, and tracing composed as a backend service.
Use it for: Python agent services that need explicit handoffs and inspectable traces.
Runs either way
- Client
- Agent service
- Tools
- Trace
RailwayOrchestration
Persistent agent worker plane
Long-running workers, queues, databases, and service-to-service networking behind a separately deployed web experience.
Use it for: Background research, ingestion, browser jobs, and workloads that should not live inside a request lifecycle.
Durable runtime
- Vercel API
- Queue
- Railway worker
- Database
TemporalOrchestration
Durable agent workflow
Retries, timeouts, durable state, signals, and human approvals separated from model calls and web requests.
Use it for: Long-running business processes where silent failure is unacceptable.
Durable runtime
- Event
- Workflow
- Activities
- Approval
Model Context ProtocolTool surface
MCP tool and context plane
A governed boundary for exposing tools and context to agents without coupling every integration to one model provider.
Use it for: Shared enterprise tools, GitHub operations, and replaceable model runtimes.
Runs either way
- Agent
- MCP client
- MCP server
- System of record
Google CloudContext and retrieval
RAG on Agent Platform and AlloyDB
A Google Cloud reference design that stores embeddings in AlloyDB with pgvector, retrieves context in the application, sends contextualized prompts to an LLM on Agent Platform, and evaluates quality separately.
Use it for: Governed knowledge assistants and data-heavy enterprise workloads.
Managed service
- Frontend
- AlloyDB vector search
- Agent Platform LLM
- Screened response
LiteLLMModel access
Unified model gateway
One OpenAI-compatible endpoint in front of many providers, with virtual keys, budget hooks, load-balanced routing that falls back on failure, and per-request spend written to one ledger.
Use it for: Systems that need to swap or lose a provider without touching every call site.
Runs either way
- Client
- Gateway
- Router + fallback
- Provider
Deploy lanes
Templates are scaffolding, not decisions.
Official starting points for the lanes above. Deploying one buys you a working lane — the seams between planes, and what crosses them, still belong to you.
Vercel
Next.js AI chatbot
The canonical request-scoped agent surface — streaming UI, auth, persistence, and a model gateway, cloned into your own repository.
v0 by Vercel
Generate the experience plane
Prompt-to-component for the surface in front of your loop. Export the code into your repository; the boundaries stay yours to draw.
Vercel
AI template gallery
Maintained starters for the request-scoped lane, filterable by stack and use case.
Railway
Template marketplace
Durable-runtime starters — workers, queues, Postgres, and the services that outlive a request.
Use the reference. Keep your architecture.
Fork the maintained implementation, replace its boundaries one at a time, and keep deployment, observability, security, and rollback evidence beside the code.
Definition
What is AI architecture?
AI architecture is the arrangement of the parts that surround a model — how requests reach it, what context it is given, which tools it may call, who approves side effects, and how the whole run is measured. The model is one component. Architecture is the decision about everything else.
This page is about software architecture for systems that call language models. It is not about designing buildings, and it is not about accelerator silicon — two different fields that share the phrase. If you are here to decide how to structure an application that calls a model in production, you are in the right place.
The reason architecture carries so much weight is that model quality is the part you least control and least differentiate on. Everyone can reach a frontier model. What separates a system that survives contact with users from one that does not is the boundaries around it: what the model is allowed to see, what it is allowed to do, and what happens when it is wrong.
Reference architecture
Seven planes, and the seams between them.
Every production system that calls a model has these planes, whether or not anyone drew them. Naming them is useful because failures are almost never located where they are observed — and because each seam is a boundary where something changes character. Read it from the base up: nothing above works if the plane under it is unreliable.
- 07
Experience
Stream partial work, and let a human interrupt it or approve it.
- Streaming UI
- Interruption
- Approval
human boundary — approval and interruption live here or nowhere - 06
Observability
Record every model call, tool call, and token as one traceable run.
- Traces
- Spans
- Cost + latency
evidence boundary — below this line you are guessing - 05
Evaluation
Decide whether a change made the system better, before users do.
- Offline suites
- Trajectories
- Online sampling
correctness boundary — the loop is only as good as what grades it - 04
Orchestration
Choose the shape: fixed workflow, one agent loop, or many.
- The loop
- Durable execution
- Handoffs
privilege boundary — the loop decides what gets called with real permissions - 03
Tool surface
Expose capability with schemas, scopes, and an audit trail.
- MCP servers
- Schemas
- Scopes
trust boundary — everything returned from here is untrusted input - 02
Context and retrieval
Put the right tokens in the window, and leave the rest out.
- Hybrid search
- Rerank
- Memory
relevance boundary — retrieval failures arrive disguised as model failures - 01
Model access
Reach a model, survive it being slow, wrong, or gone.
- Gateway
- Routing
- Fallback
- Cache
Tool results need an explicit trust boundary. A search result, a fetched page, or a database row may contain instructions written by someone outside your system. Treat retrieved content as data and enforce action permissions in application code. A fluent proposal does not establish authority to act.
The orchestration decision
Workflow, one agent, or many?
Build a fixed workflow when you can name every step before the request arrives. Build an agent loop when the steps are unknown but the task is one coherent piece of work. The test is not how capable the model is — it is whether you can enumerate the path in advance.
| Shape | Use when | Cost you accept | How it fails |
|---|---|---|---|
| Fixed workflow | You can name every step before the request arrives. | No adaptation when the input is not what you planned for. | Stays confident and goes silently wrong once reality drifts from the graph. |
| Single agent loop | The steps are unknown but the task is one coherent piece of work. | Latency and spend grow with the length of the loop. | The loop loses track of its own earlier decisions as the window fills. |
| Parallel sub-agents | Breadth-first gathering, where each lookup is independent of the others. | A merge step you have to design, and results that can contradict. | Duplicated work, and summaries that disagree with no way to adjudicate. |
| Sequential sub-agents | Work that mutates shared state and must not interleave. | Throughput. You gave up the parallelism on purpose. | Slow enough that someone proposes parallelising the writes again. |
Multi-agent designs should be compared on the workload they serve. Start with the heuristic: parallelise reads, serialise writes. Independent gathering can reduce latency, but still needs limits on cost, rate, and inconsistent evidence. Concurrent writes require isolation, conflict detection, and reconciliation. Serialize shared mutations until that contract is tested. This is a design recommendation, not a claim that concurrent writes are impossible.
Protocol layer · verified 20 August 2026
MCP became stateless. Most guidance has not caught up.
The Model Context Protocol revision dated 2026-07-28 removed protocol-level sessions, theMcp-Session-Idheader, and the initializehandshake. Servers that need cross-call state now mint explicit handles and pass them as ordinary tool arguments.
This matters architecturally rather than cosmetically. A stateless protocol core means an MCP server can sit behind ordinary HTTP infrastructure — load balancers, caches, retries — without session affinity. It also means any design that assumed a connection lifecycle now has to carry that state somewhere explicit.
Removed
Sessions, the initialize/initialized handshake, ping, logging/setLevel, and SSE stream resumability.
Added
server/discover for version and capability negotiation, and subscriptions/listen in place of resource subscriptions.
Required
A resultType field on every result. Results from earlier servers that omit it are treated as complete.
Deprecated
Roots, Sampling, and Logging, under a policy guaranteeing a minimum twelve-month window.
Two additions are easy to miss and worth designing around. Caching became a protocol concern: list and read results now carry ttlMs and cacheScope, and servers are asked to return tools in a deterministic order specifically so client-side and prompt caches stay stable. And tracing became one too: OpenTelemetry trace context propagates through _meta keys, so a tool call can join the same trace as the request that caused it.
Source: MCP specification 2026-07-28, Key Changes. Read in full on 20 August 2026. The previous revision was 2025-11-25.
Security baseline · verified 20 August 2026
The risks are ranked, and the ranking moved.
The OWASP GenAI LLM Top 10 2026 was published in August 2026. Prompt Injection remains first, with Excessive Agency at third. Address excessive agency through scoped tool permissions, approval boundaries, and monitoring. Prompt instructions alone do not enforce those controls.
- LLM01Prompt Injection
- LLM02Sensitive Information Disclosure
- LLM03Excessive Agency
- LLM04Supply Chain
- LLM05Data and Model Poisoning
- LLM06Unbounded Consumption
- LLM07Misinformation
- LLM08Hidden Context Exposure
- LLM09Vector and Embedding Weaknesses
- LLM10Improper Output Handling
Three of these are architectural rather than behavioural, and they are the three worth designing for on day one. Excessive Agency is decided by how narrowly you scope tool permissions. Unbounded Consumption is decided by whether loop limits live in code or in a prompt. Hidden Context Exposure — broadened this year beyond system-prompt leakage — is decided by what you put in the window in the first place.
Source: OWASP GenAI LLM Top 10 2026, with the entry list read from the project repository on 20 August 2026. Note that the GenAI Security Project also publishes a separate list for agentic applications; they are frequently conflated.
Field catalog
Where these systems actually break.
Sorted by what an operator sees first, because the observed symptom and the real cause almost never sit in the same plane.
Answers degrade as the conversation grows
- Looks like
- The model was fine for ten turns and then started contradicting itself.
- Actual cause
- The window filled with its own transcript. Early decisions fell out of attention.
- What fixes it
- Compact deliberately: summarise closed sub-tasks, keep decisions, drop the reasoning that produced them.
Retrieval looks healthy, answers are wrong
- Looks like
- Search returns plausible documents and the answer still misses.
- Actual cause
- Chunking split the answer across boundaries, or the reranker never saw the right candidate.
- What fixes it
- Measure retrieval separately from generation. A generation eval cannot see a recall problem.
A tool result changes the agent’s goal
- Looks like
- The agent does something nobody asked for, citing a document.
- Actual cause
- Injection. Retrieved and tool-returned text was treated as instruction, not data.
- What fixes it
- Keep untrusted content out of the instruction position, and gate side effects behind approval.
Costs move without a deploy
- Looks like
- Spend rises on a week with no releases.
- Actual cause
- Cache misses, retry storms, or a loop whose exit condition depends on model output.
- What fixes it
- Budget per run, not per month. Cap loop iterations in code rather than in the prompt.
Evals pass, production regresses
- Looks like
- Green suite, unhappy users.
- Actual cause
- The suite grades final answers while the failure is in the trajectory.
- What fixes it
- Grade the path as well as the destination, and keep a sample of real traffic in the loop.
Contested ground
What the field has not settled.
Most architecture writing presents the current moment as more settled than it is. These are live disagreements between people who have shipped real systems, and you should expect to make your own call rather than find a consensus to adopt.
Do multi-agent systems help or fracture?
Anthropic has published a multi-agent research architecture where sub-agents run in parallel with isolated context. Cognition has argued the opposite case — that parallel sub-agents make independent decisions which then conflict. Both report real results on real systems. The published performance numbers on each side are not independently reproducible, so we do not repeat them here; the workload distinction in the table above is the part that transfers.
Long context or retrieval?
As context windows grow, the argument that retrieval is a workaround gets louder. The counter-argument that has not been answered: you cannot apply access control to a context window. If different users are entitled to different documents, retrieval is not an optimisation, it is the enforcement point.
How much should a framework do?
One camp keeps the agent loop small enough to read in one sitting and treats frameworks as indirection. The other argues that durable execution, checkpointing, and replay are genuinely hard and not worth rebuilding. This one usually resolves on operational maturity rather than taste: if you already run durable workflows, the framework buys less than it costs.
Questions
Frequently asked
What is AI architecture?
AI architecture is the arrangement of the parts that surround a model: how requests reach it, what context it is given, which tools it may call, who approves side effects, and how the whole run is measured. The model is one component. Architecture assigns boundaries, ownership, and recovery behavior to the surrounding system.
Should I build a workflow or an agent?
Start with a fixed workflow when you can name the required steps before the request arrives. Consider an agent loop when the path is unknown but the task is one coherent piece of work. A fixed path makes execution easier to bound and test. Compare latency, total cost, and task outcomes on your workload before choosing.
When is a multi-agent system worth the coordination cost?
Parallel agents can help when the work is read-heavy and each unit is independent, such as separate lookups or documents. Measure the quality and latency gain against coordination cost. Parallel writes to shared state require explicit isolation, conflict detection, and reconciliation; serialize them by default until that contract is tested.
What changed in the Model Context Protocol in 2026?
The 2026-07-28 revision removed protocol-level sessions, the Mcp-Session-Id header, and the initialize handshake, making MCP stateless. Servers that need cross-call state now mint explicit handles passed as ordinary tool arguments. It also added server/discover, replaced resource subscriptions with subscriptions/listen, required a resultType field on every result, and deprecated Roots, Sampling, and Logging.
What are the biggest security risks in an AI system?
The OWASP GenAI LLM Top 10 2026, published in August 2026, ranks Prompt Injection first, Sensitive Information Disclosure second, and Excessive Agency third. Address excessive agency through scoped tool permissions, approval boundaries, and monitoring. Prompt instructions alone do not enforce those controls.
Why do retrieval systems fail even when search looks healthy?
Because retrieval and generation are usually measured together. A generation eval grades the final answer, so it cannot distinguish an answer that was wrong from an answer whose evidence was never retrieved. Measure recall separately. Ingestion and chunking sit upstream of anything the model does, so a failure there reaches you disguised as a generation failure.
Specifications cited on this page were read end to end on 20 August 2026. Where a claim is our position rather than a sourced fact, it says so in the sentence. Where a widely repeated number could not be traced to a primary source, it has been left out rather than repeated.
Reading path
Where this goes deeper.
This page is the map. Each of these takes one plane of it and goes down a level.
04 · Orchestration
The agentic engineering master guide
The full curriculum behind the orchestration decision — primitives, skills, and subagent state machines.
03 · Tool surface
Anatomy of a production skill
What a capability has to carry before it is safe to expose to a loop.
03 · Tool surface
The A2A agent card
The other protocol in this layer, and where it stops overlapping with MCP.
01 · Model access
First agent primer
Start here if the loop itself is still unfamiliar. Everything above assumes it.
Applied
Deployable blueprints
The reference designs from the atlas above, worked through to something you can stand up.
Applied
The architect learning path
The sequenced route through this material if you are building the skill rather than one system.
Run it
Seven planes map the system. Four decisions produce a verdict.
The architecture review asks four questions about the decisions that are expensive to reverse. Answer them for your own system and you get a report naming which are made, which are still open, and which to close first — or install the same rubric into the coding agent that already has the repository open, and let it grep for the evidence instead of asking you.