AI agent architecture

AI Agent Architecture

Most "AI agent" writing is about prompting a model to do more. This page is about the other half: the architecture that keeps an agent's actions safe, reviewable, and reversible once it's wired up to real infrastructure — not a chatbot demo.

The problem with giving an agent real access

An agent that can only answer questions is easy to reason about. An agent that can act — publish something, change infrastructure, resolve an incident — needs a system around it, not just a better prompt. My approach, covered at a higher level on AI Automation & Agent Systems, comes from treating an agent pipeline the way I'd treat a data pipeline: versioned, observable, and built to fail loudly rather than silently.

The patterns I build around

• Approval gates on anything irreversible. An agent can propose or stage an action, but publishing, deploying, or resolving something flagged as an anomaly routes through an explicit human approval step before it takes effect.
• Identity and scope checks before write actions. Verifying what the agent is actually about to act on — not just trusting the plan it generated — before any state-changing call.
• Immutable artifacts. What gets approved is hashed, so what executes is provably identical to what a human signed off on, not a re-generated version of it.
• One-shot execution, not silent retries. No generic "force" or "bypass" path around an approval gate, and no batch repeat of a sensitive action without a fresh approval.
• Append-only audit trails. Every agent action that matters is logged in a way that can't be quietly edited after the fact, so "automated" never becomes "unaccountable."
• A dedicated review surface for drift. My own internal AI agent operations system has a human-review UI specifically for actions an agent takes that get flagged as drifting from what was expected — reviewed before they're considered resolved, not after.

Where the reasoning layer ends and orchestration begins

I keep these as two separate layers rather than one blob of agent logic. Claude / Claude Code handles the parts that need judgment and reasoning — reading state, deciding what to do, drafting the action. n8n handles the deterministic glue around it: scheduling, integration calls, moving data between systems, and enforcing the approval gate itself as a concrete workflow step rather than something the agent could talk itself out of. Keeping the gate outside the reasoning layer is deliberate — a step a deterministic workflow enforces is a step an agent can't quietly skip.

A concrete example: Traffic OS

Traffic OS's publishing pipeline is the clearest public example of this architecture in production: per-channel credential isolation, live channel identity verification before any write action, an immutable hash of each approved artifact, a creative approval step, a final publishing approval step, one-shot canary publishing controls, and an append-only audit history — with no generic bypass path around any of it. See the reviewer & compliance overview for the full breakdown.

When I don't let the agent publish

An approval gate is only worth having if it can say no. My daily blog pipeline has several: evidence, facts, narrative, privacy and site QA, plus a single, constrained repair attempt. I put it through a strict acceptance test for publishing without me. It needed all three runs to be eligible and produced two. I didn't loosen the gates to make it three, so production stays on human approval. The full account is inmy AI system passed 2 of 3 tests to publish alone. Two real failures I have written up: the first production failure of Traffic OS, and a quieter one,a silent bug that stalled my content pipeline.

Work with me

If you're designing or reviewing an AI agent system that needs to take real actions safely — not just answer questions — see Projects for more of what I've built, or get in touch via the contact page.