AI Agent Architecture Explained: 7 Essential Layers
See what sits around the model, where control should live and how a request becomes a traceable, approved action.
Key takeaways
- The model is one component, not the whole agent system.
- Every boundary should pass structured data with an explicit owner.
- Keep deterministic business rules outside probabilistic model judgment.
- Separate read tools from write tools and gate consequential actions.
- Design failure states, traces and tests before increasing autonomy.
The seven layers of an AI agent
Architecture is less about choosing a fashionable framework and more about deciding where data, judgment and authority live. The diagram below is a reference model, not a universal product stack.
Figure 1. A controlled AI agent architecture
Text equivalent: an authenticated request enters a policy and orchestration layer. The model receives bounded context and may select a typed tool. State preserves transaction facts, while optional long-term memory is separately governed. Write actions cross an approval and authorization boundary before execution. Every step produces trace data and structured outcomes for debugging and evaluation.
1. Entry and identity
The entry layer accepts a goal from a user, event or scheduled job. It establishes who requested the work, which organisation and record it belongs to, and what scope was granted. Input validation, authentication and rate limits begin here.
2. Policy and orchestration
This layer decides what path is allowed: a deterministic workflow, an agent loop, a human handoff or a refusal. It owns retry limits, timeouts, stop conditions and budgets. Use a fixed workflow when the steps are known; reserve model-directed routing for real ambiguity.
3. Model and instructions
The model interprets context, proposes a plan or chooses a tool. Its instructions define the role, goal, constraints and completion condition. The model can recommend an action, but should not be the final authority on identity, permissions or irreversible business rules.
4. Tools and knowledge
Tools give the system ground truth and the ability to act. Give each tool a narrow purpose, typed parameters, clear error responses and minimum privileges. Separate reads from writes: searching a CRM is not the same permission as changing a customer record.
5. Run state and memory
Run state holds facts needed to complete this transaction: identifiers, tool results, approval status and the next allowed step. Long-term memory persists selected information for future runs. Do not turn every conversation or hidden reasoning token into memory; define purpose, consent, retention and deletion.
6. Approval and execution
This is the authority boundary. A person reviews high-impact, sensitive or irreversible actions. After approval, deterministic code re-checks authorization, validates the payload and performs the write with an idempotency key. A timeout is not proof that a write failed.
7. Observability and evaluation
A trace should connect the request, model decision, tool call, approval, execution result and terminal status without exposing unnecessary sensitive data. Evaluation cases then test whether the system completed the task, used allowed tools and stopped safely.
Define the contracts before choosing a framework
A framework can run the loop, but it cannot decide your business boundary. Start with the records that cross each layer.
{
"run_id": "case-1042",
"actor_id": "user-27",
"goal": "prepare a customer reply",
"scope": ["customer:read", "draft:create"],
"state": "awaiting_approval",
"proposed_action": {
"tool": "message.send",
"arguments_hash": "sha256:..."
},
"approval": null,
"attempt": 1,
"trace_id": "trace-8f2"
}The model may prepare proposed_action. The execution service checks the authenticated actor, current scope, approval object and destination state before any send.
| Boundary | Input contract | Output contract | Owner |
|---|---|---|---|
| Entry → control | Goal, identity, tenant, scope | Accepted, refused or routed request | Application |
| Control → model | Instructions, bounded context, allowed tools | Structured decision or clarification | Agent runtime |
| Model → tool | Tool name and schema-valid arguments | Typed result or typed error | Tool service |
| State → memory | Approved memory candidate | Stored, rejected or expired record | Data owner |
| Proposal → execution | Action, scope, approval, idempotency key | Receipt, known failure or uncertain outcome | Downstream system |
| Run → evidence | Events with trace ID | Redacted trace and evaluation outcome | Operations |
How to design the architecture
- Name one business outcome. Define the trigger, terminal success state, non-goals and the human owner.
- Choose the least autonomous path. Use rules for known steps and introduce model choice only where ambiguity makes it useful.
- Define state and schemas. Specify required fields, provenance, lifecycle and which outputs downstream code may trust.
- Build narrow tools. Split reads from writes, grant minimum scope and return machine-readable errors.
- Place approval gates. Require a person for sensitive, consequential or irreversible actions; bind approval to the exact payload.
- Design recovery. Set timeouts, attempt limits, idempotency keys, destination checks and a human escalation package.
- Add traces and evals. Measure task completion, policy compliance, tool correctness, cost and latency against representative cases.
Permissions, approval and recovery
| Situation | Architecture control | Safe result |
|---|---|---|
| Untrusted text asks for a hidden action | Treat retrieved content as data; tool allowlist and downstream authorization remain active | Instruction is ignored or run stops |
| Model requests an unauthorized tool | Runtime checks tool policy and actor scope | Denied event is traced |
| High-impact write proposed | Human approval bound to tool, arguments and expiry | No write before approval |
| Tool returns malformed data | Schema validation; no silent coercion | Retry bounded or human escalation |
| Write times out | Check destination using idempotency key before retry | No blind duplicate |
| Agent exceeds step or cost limit | Deterministic stop condition | Partial evidence handed to a person |
| Trace contains sensitive fields | Redaction, access control and retention policy | Useful evidence without unnecessary exposure |
Architecture test matrix
| Test | Expected evidence | Pass condition |
|---|---|---|
| Valid read-only request | Identity, route, tool result, final status | Correct answer; no write permission used |
| Missing or invalid input | Validation event | Rejected before model/tool call |
| Prompt injection in retrieved text | Content source and denied action | No scope expansion or secret disclosure |
| Unauthorized write | Policy decision and actor scope | Write is blocked |
| Approval rejected or expired | Approval status | No execution; terminal safe state |
| Tool timeout after possible write | Idempotency key and destination check | No duplicate transaction |
| Malformed model output | Schema error | Bounded repair or escalation |
| Step/cost limit reached | Usage and stop reason | Run stops with a useful handoff |
| Trace review | Linked events, redaction and outcome | Owner can explain what happened |
Success criteria
- Every run has an authenticated actor, a scope and a terminal status.
- Model output crosses schema validation before code trusts it.
- Read and write permissions are separate.
- High-impact writes require explicit approval.
- Retries cannot silently duplicate side effects.
- A trace reconstructs the run without storing unnecessary sensitive data.
- Evaluation includes expected failures, not only happy paths.
Learn to turn architecture into a working system
Understanding the layers is the first step; the useful skill is connecting them into a process that survives real inputs, permissions and failures. Barcelona Code School's AI Agent & Automation Bootcamp focuses on visual business automation with n8n: workflows, integrations, human approvals, testing and portfolio projects. It is not a LangGraph or low-level Python framework course.
Explore the AI Agent & Automation BootcampFrequently asked questions
What are the main components of AI agent architecture?
A useful production view has seven layers: entry and identity, policy and orchestration, model reasoning, tools, state and memory, approval and execution, and observability and evaluation. The exact implementation varies, but each boundary needs a clear contract and owner.
Is an AI agent just an LLM with tools?
A model with instructions and tools is the smallest useful agent loop. A dependable application also needs authentication, state, authorization, approval rules, error handling, logs and tests around that loop.
Where should business rules live in an AI agent?
Deterministic rules such as permissions, spending limits, required fields and irreversible-action approvals should be enforced in code or downstream systems. Do not rely on the model to remember or correctly apply security policy.
Does every AI agent need long-term memory?
No. Keep run state only for values needed to finish the current transaction. Add durable memory only when a defined future task needs it, with consent, retention, correction and deletion rules.
How do you test an AI agent architecture?
Test each layer and the boundaries between layers: invalid input, unauthorized tools, untrusted content, malformed model output, timeouts, duplicate retries, rejected approvals and incomplete traces. A test passes only when the system reaches the expected safe state.