George K.

Posted on Nov 3 Originally published at barcelonacodeschool.com

AI Agent Architecture Explained: 7 Essential Layers

#ai #agents #automation #architecture

See what sits around the model, where control should live and how a request becomes a traceable, approved action.

Published 13 October 2026 · Barcelona Code School

AI agent architecture is the system around a model that turns a goal into controlled, observable work.

A practical design has seven layers: entry and identity, orchestration and policy, model reasoning, tools, state and memory, approval and execution, and observability and evaluation. The model may choose a next step, but code and downstream systems must enforce permissions, limits, approvals and safe stopping.

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

1. Entry · Request + identity
2. Control · Policy + routing
3. Model · Bounded judgment
4. Tools · Typed read/write APIs
5. State · Run + selected memory
6. Approval · Authorize + execute
7. Evidence · Trace + eval

Deterministic controls surround the model loop; evidence spans the full run.

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

4-week live bootcamp · Barcelona or online

Go from one workflow to a complete AI automation system

In the AI Agent & Automation Bootcamp you build a no-code Virtual AI Department with n8n, RAG, connected agents and human approvals — live with an instructor and a small group.

See the bootcamp programme →

Not sure it fits? Take the free AI Career Roadmap test

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.

A guardrail prompt is not an authorization system. Enforce identity, scope, limits and final write permission in code and in the downstream service.

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 Bootcamp

Frequently 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.

Sources

Continue learning

Build an AI agent step by step

Compare BCS AI learning paths