AI Agent Knowledge Architecture Overview

What (What This Article Covers)

This overview addresses two core questions:

1. What specific engineering problems is this domain actually solving?
2. How should you navigate this knowledge tree, and what kind of "runnable, auditable, and replayable" agent system will you be able to build after reading it?

In this context, an "AI Agent" refers to a specific class of "closed-loop systems": it treats the Large Language Model (LLM) as an untrusted reasoning component, utilizing a controllable runtime to weave reasoning, tool invocation, state persistence, error handling, permission isolation, and observability/auditing into a single, verifiable execution chain.

Problem (The Engineering Problems Solved)

Treating an agent as a simple script that performs "one completion + one tool call" will very quickly hit the hard boundaries of the real world:

1. Statelessness: The model itself does not persist state. Long-running tasks require external state machines, checkpoints, and recovery processes.
2. Side Effects: Tool calls will write files, send network requests, and mutate databases. Blind retries will cause duplicate commits and irreversible destruction.
3. Context Scarcity: A larger context window is not always better. Long contexts lead to attention degradation and the "lost in the middle" phenomenon, requiring dynamic assembly and compression strategies.
4. Untrusted Inputs: The model's output is just a string; it does not equal a "trusted instruction". You must implement schema validation, permission trimming, rate limiting, timeouts, idempotency, and auditing.
5. Long-Running Execution: Timeouts, zombie processes, retry storms, resource leaks, concurrent race conditions, and log explosions are inevitable at the scale of hours.
6. Multi-Agent Collaboration: Introduces challenges around responsibility boundaries, state synchronization, error propagation, tool pollution, permission delegation, and the ultimate attribution problem of "who is responsible for this side effect."

The goal of this domain is to deconstruct the agent into an understandable, implementable, debuggable, and verifiable engineering system. After reading this tree, you should be able to answer much deeper questions: If an agent needs to work continuously on a real machine for several hours, exactly what components guarantee its control loop, tool boundaries, state recovery, and security isolation?

Usage (What You Will Build)

You will be able to implement at least a "production-ready skeleton" with the following capabilities:

1. Unified Execution Loop: observe -> plan -> act -> verify -> commit -> loop/stop.
2. Tool Governance Pipeline: Every tool call passes through validation, permission checks, timeouts, retries, idempotency checks, and auditing.
3. State Persistence and Recovery: Task states, tool results, and critical decision points can be replayed without duplicating side effects.
4. Dynamic Context Assembly: Stable rule prefixes, priority on live environmental data, compressible history, and controllable retrieval.
5. Observability and Retrospection: Traces/spans, structured logging, failure distribution analysis, and replayable execution chains.
6. Sandbox and Isolation: When untrusted code executes, the "blast radius" is restricted to an acceptable threshold.

To ensure this isn't purely theoretical, this tree constantly grounds "abstract nouns" into concrete engineering objects:

1. A runnable runtime (processes, threads, event loops, schedulers).
2. A verifiable protocol (schemas, types, tool interfaces, error codes, retry strategies).
3. An auditable data stream (Write-Ahead Logs, event logs, traces, replays).
4. A set of isolatable execution environments (containers, user-space kernels, least privilege, zero-trust).

Principle (Deconstructing the Agent Components)

An agent can be understood through the lens of a "Control Loop + Constraint Layer":

1. Control Loop: Allows the system to run continuously and converge on a goal.
2. Constraint Layer: Ensures every step is controllable, traceable, rollbackable (or at least stoppable), and auditable.

1) The Control Loop (Closed Loop)

A minimal closed loop can be abstracted into this chain:

Observe -> Think/Plan -> Act -> Verify -> Commit -> Continue/Stop

The critical point is not the "loop" itself, but where you place the side effects:

1. Observation is Read-Only: Reading files, logs, web pages, or DB query results cannot produce side effects.
2. Action is Restricted: Only the runtime is allowed to invoke tools; the model never directly touches system capabilities.
3. Explicit Commits: Treat "writing files / mutating databases / sending requests" as explicit commit points, paired with idempotency and auditing.

2) The Tool Execution Layer (Translating Strings to Actions)

The tool execution layer is responsible for turning model outputs (strings/JSON) into real actions, but it must act simultaneously as a "translator" and a "gatekeeper":

1. Parsing: Strict parsing (JSON schema / strongly typed tools).
2. Validation: Parameter allowlists, path constraints, Regex/AST validation.
3. Authorization: Scopes, least privilege, sandboxing, network egress control.
4. Constraints: Timeouts, concurrency limits, rate limiting, resource quotas.
5. Idempotency: Idempotency keys + commit logs (WAL) to prevent replaying side effects.

3) Memory and Persistence (Keeping the Agent "Alive")

Continuous execution guarantees interruptions. The engineering problem is not "how to never crash," but "how to recover after a crash":

1. Short-Term Memory: The current task environment, open files, recent dialogue.
2. Long-Term Memory: A retrievable repository of facts (docs, code indexes, tickets, knowledge bases).
3. Task State: Progress, branches, commit logs of executed actions, next steps.
4. Recovery Protocol: Resuming from the state machine after a restart without duplicating side effects.

4) Context Feeding (Spending Tokens Wisely)

Context feeding is not about "stuffing more text in"; it's about "treating tokens as a schedulable resource":

1. Stable Prefixes: Keep rules and tool definitions as static as possible to aid caching and stabilize behavior.
2. Live Data Priority: The current file, error logs, call stacks, and unit test failure messages take precedence.
3. History Compression: Fold old dialogues into structured facts and decision points.
4. Controllable Retrieval: RAG is not "more is better"; it requires interpretable retrieval and noise reduction.

5) Isolation and Observability (Strong Power Requires Strong Constraints)

The more capable the agent, the larger its blast radius. These two cross-cutting layers must be designed in from day one:

1. Isolation: Process permissions, read-only/allowlisted filesystem mounts, network egress controls, containers/user-space kernels.
2. Observability: Structured logs, traces/spans, audit logs, and replay/debugging tools.

The Learning Path (The Directory is the Dependency Graph)

content/en/06-ai-agent is structured logically: "define boundaries first, establish the loop, then attach tools and constraints to the loop":

This order exists for a reason: establish "boundaries and loops" first, wire up "tools and sensors" second, and finally bolt on "constraints and ops for long-running execution". Many failed agent projects approach this backwards: they build a running demo first, and only later try to retrofit idempotency/permissions/observability, resulting in endless rewrites.

Overview Articles vs. Deep Dives

This 00-ai-agent-overview.md file serves only as the "map and boundaries"—it does not replace any deep-dive article. Moving forward, each top-level directory contains two types of content:

1. Parent Node Overviews: Explaining internal module boundaries, roadmaps, comparisons, and prerequisites.
2. Leaf Node Deep Dives: Focusing intensely on a single mechanism, covering What / Problem / Usage / Principle / Source / Design / Pitfalls / Debugging.

The parent maps the territory; the leaf explains the engine. The map avoids implementation details, and the detail pages avoid redrawing the map. This keeps the knowledge base maintainable and prevents duplicating definitions globally.

Acceptance Criteria for this Domain (Longer is Not Better)

Acceptance is not based on "word count," but on whether the content can support real engineering:

1. System Level: Does the directory order reflect real-world engineering dependencies? (Otherwise, you risk constant refactoring).
2. Article Level: Does a single article thoroughly dissect a mechanism? (Mechanics, implementation paths, failure modes, error-proofing).
3. Engineering Level: Can it prevent real production accidents? (Timeouts, retries, idempotency, permissions, isolation, observability, auditing).

Therefore, the refactoring of this domain will first stabilize the foundational prerequisites (definitions, boundaries, action paradigms, loop theories), and only then advance into model routing, memory, tool invocation, MCP, multi-agent swarms, security isolation, and ops.

Source Verification

Before any article in this domain is rewritten, a research dossier is generated and stored at:

.agents/runs/06-ai-agent/research/articles/<article>.md

Its purpose is not to "stack links," but to lock down critical facts and primary sources, ensuring the main text never invents mechanisms or asserts conclusions without evidence.

Minimal Implementation Checklist (Turning this Tree into Code)

If you are building a runnable agent runtime from scratch, use this checklist to self-audit. It intentionally avoids naming specific frameworks, focusing solely on the "objects and boundaries you must implement."

1) Tasks and the State Machine

1. Task: Objectives, inputs, constraints, deadlines, budgets.
2. Step: Replayable action units with explicit inputs and outputs.
3. TaskState: Current step, completed steps, next candidates, failure counts.
4. Checkpoint: Persisting state to disk before and after side effects, supporting recovery and replay.

2) Tools and Governance

1. Tool (Interface): Name, schema, execution function, timeout, permission scope.
2. ToolResult: Structured data + raw output + truncation info.
3. Gate (Governance Pipeline): parse -> validate -> authorize -> execute -> record.
4. WAL (Write-Ahead Log): Every side effect writes an immutable record (Who, when, targeting which resource, did what, with what result).

3) Context and Memory

1. ContextAssembler: Assembling rules, live environment data, history, and retrieved snippets into a controllable input.
2. MemoryStore: Document/code indexes, retrieval interfaces, noise reduction strategies.
3. Compressor: Folding history into structured facts and decision points.

4) Observability and Auditing

1. Trace: One task -> multiple invocations -> multiple tool steps.
2. Span: Every model call and tool call is a span.
3. AuditLog: Used retrospectively to answer "what exactly happened?"

5) Isolation and Permissions

1. Filesystem: Read-only mounts, allowlisted paths, blocking writes outside the workspace.
2. Network: Default deny, allowlisting by domain/port/destination.
3. Processes: Resource quotas (CPU/RAM), timeouts, and forced garbage collection.

Common Pitfalls (Traps That Cause Endless Rewrites)

1. Building the demo first, adding governance later: You will discover that every "patch" requires changing the core interface, leading to massive rewrites.
2. Treating the model as the executor: Letting the model directly concatenate and execute shell commands is equivalent to piping untrusted input directly into syscalls.
3. Logging text only: Text logs cannot be queried or analyzed; you must use structured fields and trace IDs.
4. Believing "more context solves it": Context management is a structural problem, not a capacity problem.
5. Treating multi-agent as concurrency: Multi-agent swarms don't give you "faster execution," they give you "infinitely more complex attribution and synchronization."

This is why this domain uses "boundaries, loops, governance, persistence, context, isolation, and observability" as its primary thread, rather than following a popular framework's documentation.

Next step recommendation: Read through the four articles in 01-Cognition and Enlightenment first, then return here to implement the "Minimal Implementation Checklist" item by item.