Ask three builders to define "agent architecture" and you'll get three different diagrams — usually because none of them defined it before picking a framework. Here's the version that holds up regardless of what you build on. An AI agent architecture is the plan for how your agent perceives a situation, reasons about it, acts on it, remembers it, and hands it back to a human. Get those five decisions right on paper, and the framework becomes a choice you make second, not first.
Skipping this is why agents demo well and break in production
Most teams skip straight to implementation: pick a framework — LangChain, eve, Flue — and start wiring up tool calls. The agent works in the demo, because the demo only exercises the path someone thought to test.
The problems that show up later all trace back to a decision nobody made on purpose. No memory strategy, so the agent forgets what it already asked.
No escalation plan, so it either fails silently or loops on an edge case it can't resolve. Every tool handed over on day one multiplies the ways it can pick the wrong one. Architecture is the name for making those decisions before the code does.
An agent decides; a chatbot just replies
A chatbot answers the message in front of it. An agent reads the situation — the history, the tools available, the goal — and decides what to do, which sometimes means doing nothing yet.
That distinction shows up as four things a plain chatbot doesn't have:
- Memory that persists across a session, or across many
- Tools it can call, not just text it can generate
- The ability to string multiple decisions together toward a goal
- A place anywhere from fully autonomous to a human checking every step
The range this covers is wide: a support agent that answers and opens tickets, a research agent that drafts a report, a coding agent that writes and runs its own code. All five layers below apply to each, just with different answers.
Every agent architecture reduces to five decisions
Regardless of what you're building, these are the five a framework can't make for you.
1. Perception — what it's actually allowed to see
Text, documents, images, API responses, memory from earlier sessions, the state of whatever environment it operates in. Naming this forces a distinction most teams skip: what the agent will actually have access to, versus what you're assuming it will.
2. Reasoning — how it decides
This is where an agent earns the name. An LLM call reasons about what it received and proposes a next step. A planning strategy breaks a goal into steps when one call isn't enough.
Memory retrieval pulls in whatever past context is relevant, and an evaluation step checks the output before anything happens because of it. Most agents that fail, fail here — hallucinating a fact, looping on the same sub-goal, or acting on a plan nobody actually reasoned through.
3. Action — what it's allowed to touch
Read actions — search, file access, a database query — are cheap to get wrong. Write actions — sending an email, opening a ticket, updating a record — are not.
Handing over every tool available on day one is the fastest way to confuse an agent; a narrow tool set it uses correctly beats a wide one it uses inconsistently. Each tool needs a description, a schema, and a defined failure mode before it goes anywhere near the agent.
4. Memory — what it's allowed to keep
| Type | What it holds | Example |
|---|---|---|
| In-context | Lives in the prompt window | The last few messages |
| Episodic | Records of past sessions | What this customer asked last month |
| Semantic | Facts and policies | Your refund policy |
| Procedural | How to do things | The pattern for using a specific tool |
Which of these your agent needs, and for how long, sets your cost, your context-window budget, and whether two sessions stay coherent with each other.
5. Communication — who it tells, and when
Structured output for systems that read it downstream. A human escalation point for when it shouldn't act alone. Agent-to-agent handoff for the parts one agent shouldn't own.
A notification for whoever needs to know it happened. Design this layer last, and it becomes a bolted-on setting instead of part of the architecture.
How real frameworks map to these layers
The five layers aren't an abstraction we invented. Open up the frameworks people are actually shipping agents on in 2026, and you'll find the same anatomy — just with different names and different opinions about where each layer should live.
Three worth knowing, because they represent three genuinely different philosophies:
eve (Vercel) — a layer is a folder
eve makes the architecture literal: an agent is a directory, and each layer gets its own file or folder.
Perception arrives through channels/ (Slack, Discord, Teams, web) and schedules/ for self-triggered runs. Reasoning is instructions.md for behavior, agent.ts for the model, and skills/ — Markdown playbooks loaded only when relevant.
Actions are tools/, one file per tool, with agent-written code confined to a sandbox. Memory comes from durable execution that checkpoints every step, so a session survives a crash or redeploy. Communication is subagents/, approval gates that pause the agent until a human signs off, and traces you can replay.
If you've written a blueprint, the mapping is nearly one-to-one — which is the point. eve turned the anatomy of an agent into a file convention.
Flue (Astro team) — a layer is a hook or a config
Flue is code-first where eve is filesystem-first: an agent is a TypeScript function composed with hooks. Its framing is the harness — the model supplies reasoning, and the harness supplies everything else. Reasoning is useModel plus instructions returned as plain text, with expertise in Markdown skills.
Memory is usePersistentState across sessions, on top of a durable stream that records every run. Actions are tools, MCP servers, and pluggable sandboxes (Daytona, E2B, Vercel Sandbox, or local).
Perception and communication run through channels — Slack, Teams, Discord, GitHub, WhatsApp, Telegram, even Stripe and Shopify events — plus webhooks and cron for headless operation with no human in the room.
Flue's philosophy is the sharpest statement of why architecture matters: you don't script what the agent does, you describe what it knows. That description is your architecture.
LangChain — a layer is a component you assemble
LangChain is the oldest and the most modular. Since its 1.0 rebuild around the agent loop, reasoning lives in that loop plus middleware, with LangGraph underneath for logic that needs explicit structure — branching, cycles, multiple agents coordinating.
Memory is LangGraph's per-step checkpointing, and in the Deep Agents package, a filesystem the agent uses as working memory.
Actions draw on the deepest integration bench in the industry, across both Python and JavaScript. Communication covers subagent delegation, human-in-the-loop insertion points where a person can approve or edit before the agent proceeds, and LangSmith for tracing and evals.
The perception layer is the interesting gap: LangChain doesn't hand you channels the way eve and Flue do. You wire your own front door — more work, more freedom, which is the LangChain trade in miniature.
The mapping, side by side
| Layer | eve | Flue | LangChain |
|---|---|---|---|
| Perception | channels/, schedules/, connections | Channels, webhooks, cron, events | You wire it (integrations, no channel layer) |
| Reasoning | instructions.md, agent.ts, skills/ | useModel + instructions, Markdown skills | Agent loop + middleware, LangGraph, Deep Agents |
| Action | tools/ (one file per tool), sandbox | Tools, MCP, pluggable sandboxes | Integration library, tool bindings |
| Memory | Durable execution, step checkpoints | usePersistentState, durable stream | LangGraph checkpoints, filesystem memory |
| Communication | subagents/, approvals, traces | Subagents, channels, any runtime | Subagents, approval gates, LangSmith |
What the convergence tells you
Three independent teams, three philosophies — folders, functions, and components — arrived at the same component list: instructions, tools, skills, subagents, sandboxes, durability, approvals, tracing. The 2023 era, when every framework had its own vocabulary, is over.
That's good news if you're designing rather than coding. It means your architecture is portable: a blueprint that names its inputs, reasoning strategy, tools, memory, and escalation points translates into any of these stacks.
The layers are the stable part; the framework is the implementation detail. Pick the framework second.
A blueprint is four answers, not a document
A blueprint that's actually usable answers four questions:
- Goal — what does success look like, and what's explicitly out of scope?
- Contract — what goes in, what comes out, in what format?
- Tools — which ones, in what order, allowed to do what?
- Escalation — what happens when it fails or gets stuck?
Answer those four before you open a framework's documentation, not after. This is exactly what Frameworkr's blueprint builder is for.
Frequently asked questions
Do I need to architect a simple chatbot? Probably not for a stateless Q&A bot. The moment it takes actions, uses tools, or remembers context across sessions, you do.
Which LLM should I use? Architecture is model-agnostic — design the structure first, then pick the model for latency, cost, and capability.
How detailed should my blueprint be? Detailed enough to answer what the agent does, what tools it touches, when it asks a human, and what it outputs. Four answers, same four as above.
A framework gives you a place for each layer, not what goes in it
A framework gives every layer above a place to live — a file, a hook, a component, as the mapping shows. What it doesn't give you is the content of those layers.
Which tools your agent genuinely needs, what belongs in its skills, where a human approval sits, whether the job is one agent or a delegating team — those decisions sit upstream of any framework. They're the ones that decide whether the project works.
Browse the tool catalog by architecture layer once your blueprint is clear. Don't start by picking an orchestration stack.
Design the five layers on paper first. The framework — eve, Flue, LangChain, or whatever ships next year — is the part you or your developer decides afterward, informed by what you've already named.
Your agent starts with a blueprint. Build yours free →