AI Agent Guide Interactive
Overview · 01 Architecture & Glossary · 2 Interactive Labs + Quick Reference

AI Agent Engineering Architecture Map

When a production Agent loops indefinitely, fabricates a stack trace, or rolls back a service without approval, the hardest part is rarely “is the model smart enough?” It is pinpointing whether the failure lives in Context, RAG, Tool Calling, Harness, or Checkpoint recovery. Tracing one real incident across 6 layers makes every boundary unmistakable.

30-Second TL;DR
01
An Agent is not a “smarter model”—it is a stateful control loop wrapped around a stateless LLM. Context assembly, guardrails, tool execution, and checkpoints all run in your code.
02
Many production outages come from conflating adjacent layers: storing mutable user preferences in RAG, adding MCP without Harness guardrails, or resuming crashed workers from a text summary instead of a checkpoint.
03
You do not need a full RAG stack before shipping a minimal working Agent. Nail LLM constraints and a bounded loop first, then add retrieval, memory, and evals where real bottlenecks appear.
Jump to the Glossary & Roadmap Matrix →

Before You Build an Agent: The 3-Tier Architecture Spectrum

The most common engineering mistake is wrapping a 20-line deterministic script in an autonomous Agent loop. As Anthropic emphasizes in Building Effective Agents ↗, start with the simplest architecture that works, and only introduce an open-ended loop when execution paths cannot be hardcoded upfront. Primary Source · Anthropic Engineering

LEVEL 01 · SINGLE CALL
Single LLM + Structured Output

Fixed input, single-turn output constrained by Prompt rules, JSON Schema validation, and optional retrieval.

Best for: Ticket triage, field extraction, summaries.
Strength: Lowest latency, predictable cost, trivial to eval.
LEVEL 02 · CODE PIPELINE
Deterministic Workflow

Multi-step chaining, routing, or parallelization where every branch is explicitly controlled by application code.

Best for: Invoice OCR → rule checks → ERP posting.
Strength: 100% auditable, predictable execution path.
LEVEL 03 · AUTONOMOUS LOOP
Autonomous Agent Loop

Open-ended tasks where the model dynamically chooses the next tool based on live environmental feedback.

Best for: Unknown 500 incident triage, cross-repo bug fixes.
Cost: Requires Harness guardrails, checkpoints, and tracing.

Anatomy of a 2-Turn Production Agent Run

Suppose an on-call engineer sends one prompt to an internal ops Agent: “Checkout API started returning 500s after today’s v2.14.2 deploy. Find the root cause and prepare a rollback plan.” This is a genuine Level 03 task: the model must inspect live logs first (Turn 1) before proposing a rollback guarded by human approval (Turn 2).

Inspect the payloads across both turns and the LLM’s boundary becomes obvious: it does only one thing—read the current token sequence and decide whether to answer or request a tool call. Fetching logs, enforcing permissions, executing commands, and saving checkpoints are all deterministic application code.

Quick Check During this checkout-500 investigation, which layer actually executes kubectl logs and git diff?
Lab 01 · Lifecycle Stepper

How One Agent Task Travels Through 6 Layers

Click any node in the architecture diagram or step through sequentially to inspect inputs, outputs, and live payloads. Toggle the Harness guardrail off to trigger an uncontrolled rollback.

Simulated Trace · Single Incident
Task “Diagnose v2.14.2 checkout 500s and prepare a rollback plan”
Guardrail Policy
Active Loop Turn Turn 1 / 2 (Read-Only Triage)
Cumulative Context Tokens 3,200 / 16,000
Write Side-Effect State No Writes (Safe)
Turn 1 tool_result appended to Context → enters Turn 2 LLM T1 · CONTEXT+RAG Context & Docs Rules + Runbook T1 · LLM CORE Turn 1 Triage Read-only log call T1 · TOOL / MCP Tool Runtime Truncate & append T2 · LLM LOOP Turn 2 Action Proposes rollback T2 · HARNESS Guardrails Blocks write / HITL 06 · STATE / EVAL State & Tracing Checkpoint + Metrics
Layer Responsibility STEP 01 / 06

Layer Input
Layer Output
Live Payload X-Ray Payload
JSON · Step 01

Separate the Information Plane from the Execution Plane

Most architecture confusion disappears once you split every Agent component across two orthogonal planes: one controls what the model sees (Information Plane), and the other controls what the program does and how it recovers (Execution Plane).

INFORMATION PLANE (Controls what enters the model window) Prompt Constraints Role, rules, schema Context Window Budget, ordering, JIT RAG Grounding Shared docs + citations Memory Store User prefs, mutable Compaction Shrink token history EXECUTION & CONTROL PLANE (Controls side effects, limits & recovery) Tool Calling Dispatch & stop bounds MCP Protocol Standard tool transport Harness Auth, HITL, sandbox Checkpoints Resume & idempotency Eval & Tracing Regression & root cause
Figure 1: Two orthogonal planes of an AI Agent system. Information layers ensure the model sees accurate evidence; execution layers ensure the runtime cannot go rogue or duplicate side effects.
Lab 02 · Concept Boundaries

4 Frequently Confused Pairs: What Breaks When You Mix Them Up?

Select a pair to inspect its engineering boundary, then toggle between the Misuse Anti-Pattern and Clean Separation to inspect realistic production failure logs.

Simulated Outage Drills
Production Scenario

        

Strip Away the Framework: The 35-Line Minimal Agent Loop

Regardless of language or orchestration framework, every production single-Agent runtime boils down to the same loop: assemble Context → call LLM → gate with Harness → execute Tool → persist Checkpoint, stopping as soon as the model finishes or hits a hard budget.

Reference Code · 6-Layer Minimal Agent Loop Skeleton (TypeScript)
TypeScript · Minimal 6-layer collaboration skeleton
async function runAgentTask(taskId: string, userGoal: string) {
  // 01 + 02. Context Assembly: load essential rules, grounded RAG docs, and scoped memory
  const evidence = await retrieveRunbook(userGoal);
  const memory = await loadOnCallPreferences(taskId);
  const messages: Message[] = buildContext({ userGoal, evidence, memory });

  for (let step = 1; step <= MAX_STEPS; step++) {
    // 03. LLM Reasoning: stateless call returning text or structured tool calls
    const reply = await callModel({ messages, tools: declaredTools });
    messages.push(reply.assistantMessage);

    if (reply.stopReason === "end_turn") {
      await saveCheckpoint(taskId, { step, status: "done", messages });
      return reply.finalText;
    }

    for (const call of reply.toolCalls) {
      // 04. Harness Guardrails: validate schema, permission tier, and human approval
      const decision = await harness.check(call, { step, budgetRemaining: MAX_STEPS - step });
      if (!decision.allowed) {
        messages.push(toolError(call.id, decision.reason));
        continue;
      }

      // 05. Tool / MCP Execution with idempotency key; truncate output to fit budget
      const output = await executeTool(call.name, call.args, { idempotencyKey: `${taskId}:${step}:${call.id}` });
      messages.push(toolResult(call.id, truncateForBudget(output)));
    }

    // 06. Durable Checkpoint (execution plane) + optional Compaction (information plane)
    await saveCheckpoint(taskId, { step, status: "running", messages });
    if (estimateTokens(messages) > COMPACT_THRESHOLD) compactOldTurns(messages);
  }
  throw new Error("Exceeded MAX_STEPS budget");
}

Runnable standalone TypeScript scripts for individual modules live in the same repository under examples/ ↗.

Recommended Path: Full RAG Is Not a Prerequisite for Your First Agent
Start with Module 1 (LLM Engineering Foundations) to master prompt boundaries, structured output, context budgets, and regression gates. From there, jump straight to Module 2 (Agent Core Mechanics) if your priority is safe tool execution, or to Module 3 (RAG Retrieval & Grounding) if your primary bottleneck is knowledge-base recall and citation accuracy.

Glossary & Chapter Navigator Matrix

Filter 12 core engineering terms across Model & Information, Agent Runtime, and Engineering Guardrails—each with a one-sentence definition, concrete example, and direct chapter link.

Prompt Engineering Model & Info

Constraining single-call behavior with explicit task boundaries, sampling controls, and few-shot counterexamples instead of guessing phrasing.

Example: Set temperature to 0 with 2 edge-case examples so a ticket classifier stops inventing labels.
Module 1 · CH 02 Open Interactive Chapter →
Structured Output Model & Info

Turning free-form text into a typed contract using JSON Schema, runtime validation (Zod), and bounded retries on schema or business errors.

Example: Enforce { severity, team, reason } on triage output and retry once with validation feedback if a field is missing.
Module 1 · CH 03 Open Interactive Chapter →
Context Engineering Model & Info

Curating, ordering, and lazy-loading everything that enters the token window so high-signal facts are not drowned by noise.

Example: Load 200 error lines from the failing service instead of dumping logs from 30 unrelated microservices.
Module 1 · CH 04 Open Interactive Chapter →
RAG (Retrieval-Augmented Generation) Model & Info

Chunking and indexing external documents so the model grounds answers in verifiable, source-cited evidence rather than stale weights.

Example: Retrieve section 3 of the internal Checkout Rollback Runbook and cite the exact file and line.
Module 3 · CH 15–19 Start with Chunking →
Memory (Working & Long-Term) Model & Info

Persisting user- or team-scoped preferences and evolving state across sessions with explicit write, update, and expiration rules.

Example: Remember that the payments team requires posting a notice in #release-ops before any rollback.
Module 2 · CH 10 Module 2 · Upcoming
Context Compaction Model & Info

Folding verbose earlier turns and tool outputs into compact summaries when a long run approaches the context window limit.

Example: Compress 6 turns of raw log dumps (12,000 tokens) into a 300-token list of ruled-out causes and confirmed clues.
Module 2 · CH 10 Module 2 · Upcoming
Tool Calling & Agent Loop Agent Runtime

Declaring tool schemas, letting the model request calls, executing them in host code, and feeding results back until a stop condition fires.

Example: Call getDeployDiff, spot a DB pool change, then call queryErrorLogs to confirm saturation.
Module 2 · CH 06 Module 2 · Upcoming
Workflow vs. Agent Agent Runtime

Deciding which steps belong in a deterministic code pipeline (Workflow) and which open-ended branches justify a model-driven loop (Agent).

Example: Keep invoice OCR → validation → posting as a fixed Workflow; use an Agent loop for open-ended incident triage.
Module 2 · CH 07 Module 2 · Upcoming
MCP & Skills Agent Runtime

MCP ↗ standardizes how Agents connect to external tool servers; Skills package task-specific SOPs and scripts for on-demand loading.

Example: Connect to GitHub via MCP to fetch PR diffs, then load a “DB Migration Review Skill” only when SQL files change.
Module 2 · CH 13 Module 2 · Upcoming
Checkpoints & Idempotency Agent Runtime

Persisting durable step state and idempotency keys so timeouts, disconnects, or crashes resume cleanly without duplicating side effects.

Example: Worker restarts while awaiting approval at step 4 and resumes at step 4 without creating a second incident ticket.
Module 2 · CH 11 Module 2 · Upcoming
Harness (Execution Guardrails) Guardrails

Enforcing permission tiers, human-in-the-loop approval, sandboxing, and step/token budgets in code so model mistakes stay contained.

Example: Auto-allow read-only log queries; block kubectl rollback until an on-call engineer clicks Approve.
Module 2 · CH 09 Module 2 · Upcoming
Eval & Trajectory Tracing Guardrails

Measuring pass rates, constraint adherence, cost, and latency against fixed test suites so fixing one bug does not silently break ten others.

Example: Run 30 regression cases before merging any system prompt change and block CI if pass rate drops below 95%.
Module 1 · CH 05 / Module 3 · CH 19 Open Prompt Regression →

With the 6 layers and term boundaries mapped out, the next chapter starts at the very front of the pipeline: turning vague natural-language instructions into constrained, reproducible Prompt Engineering contracts.