← Back to Issue 8: The Agent Awakens

Agent Architecture Blueprint

How an AI agent thinks, acts, observes, and learns from mistakes

Illustration companion to Issue 8: The Agent Awakens

1

Agent Architecture — The Full Pipeline

A complete view of how an AI agent processes a request from start to finish. Follow the arrows from the user's prompt through reasoning, tool use, and back again.

USER "Fix the failing test in auth.js" System Prompt Role Available Tools Constraints Context Defines WHO the agent is & WHAT it can do Large Language Model (Claude) Context Window System History Current Available 200K tokens ~ 500 pages of text Reasoning The test expects /api/auth/login... Output: Tool Call OR Text { "tool": "edit_file", "path": "auth.js", "old_text": "..." } Tool Router parses JSON Tool Belt Read File See file contents Edit File Change text in a file >_ Run Command Execute shell commands Search Code Find patterns in code Web Search Look up info online Write File Create new files OBSERVATION Result goes back to LLM The ReAct Loop 1 THINK 2 ACT 3 OBSERVE 4 REPEAT final answer Fixed! The test was checking the wrong endpoint. Changed /api/login to /api/auth/login. All tests pass. RESPONSE
The agent is an LLM in a loop. It receives input, reasons about what to do, calls a tool, observes the result, and decides whether to call another tool or respond. This Think-Act-Observe cycle is the beating heart of every AI agent.
2

The Context Window — What the Agent Remembers

Everything the agent knows lives inside the context window — a long sequence of tokens. Every message, every tool call, every result gets appended. Here is what the context looks like mid-task:

Context Window Capacity: 200,000 tokens System Prompt 2K Conversation History (previous turns) 15K User msg 50 Think... 200 Tool call: read auth.js 100 Result: file contents 800 Think... 300 Tool call: edit auth.js 150 Success 50 Tool call: run tests 100 All pass 200 Response 150 Remaining space ~181K tokens System prompt History User / Success Reasoning Tool calls Tool results Final response Used so far: ~19,100 tokens out of 200,000 Every tool call and its result gets added to the context. This is why agents eventually "forget" — the window fills up! Long tasks need careful context management: summarize old results, keep the important parts, let go of the rest.
3

Tool Call Anatomy — One Tool Call, Step by Step

When the LLM decides to use a tool, it outputs a structured JSON object. Here is exactly what happens during a single edit_file call:

What the LLM outputs: { "tool" : "edit_file" , "path" : "auth.js" , "old_text" : "fetch('/api/login')" , "new_text" : "fetch('/api/auth/login')" } What happens: 1 JSON parsed by the tool router 2 edit_file tool receives the parameters 3 File auth.js is read from disk 4 old_text found and replaced with new_text 5 Updated file written back to disk 6 Success/failure returned to the LLM What the LLM receives back: Tool Result: Successfully replaced "fetch('/api/login')" with "fetch('/api/auth/login')" in auth.js This result is appended to the context window as an observation Then what? The LLM sees the result and decides: call another tool (e.g., run tests to verify) or respond to the user if the task is done.
4

Error Recovery — Learning from Failure

The true power of an agent is not that it never makes mistakes — it is that it can recognize failure and try a different approach. Here is an agent recovering from an error:

1 Agent edits auth.js Changes the API endpoint 2 Runs tests FAIL test failed! 3 Agent reads the error message "expected 200, got 404 at /api/auth/login" 4 Agent reasons about the error "404 means the route doesn't exist. I need to check the router config, not just the test file." 5 Agent makes a different edit Fixes the route in router.js instead 6 Runs tests again ALL PASS DONE This is what separates agents from autocomplete. An agent can recognize failure, reason about WHY it failed, and try a different approach. recovery path
5

Agent vs. Chatbot vs. Autocomplete

Three levels of AI assistance. Each one builds on the last, adding more perception, more action, and more autonomy.

Dimension Autocomplete e.g. Copilot (early) Chatbot e.g. ChatGPT Agent e.g. Claude Code Sees (perception) Current line of code + nearby lines for context Conversation thread + pasted code snippets Conversation + Files + Tools + command outputs + search results Does (action) Predicts next token(s) Tab to accept Responds to messages Human copy-pastes the code Reasons + Acts + Observes Directly edits, runs, verifies Can fix errors? No Doesn't see errors Can suggest fixes Human must apply them Fix AND verify Edits code, runs tests, confirms Autonomy Zero Low High Feedback loop? None One-shot prediction Manual Human pastes errors back Automatic (ReAct) Think-Act-Observe in a loop Increasing capability and autonomy
An agent is not a different model — it is the same LLM, wrapped in a loop, with access to tools. The intelligence comes from the model. The agency comes from the architecture: the ability to act on the world, observe the results, and keep going until the task is done.