你不知道的 Agent：原理、架构与工程实践

A follow-up Chinese-language essay by tw93 to his Claude Code piece. The frame: stop arguing about which model is best — most production failures are harness failures (verification, edges, feedback, fallback), and the engineering payoff sits in the layers around the loop, not inside it. Uses openclaw (Peter Steinberger‘s open-source self-hosted Agent) as the concrete case study in the final section.

Source file: raw/2026-04-27-agent-principles-architecture-engineering.md.

Summary

The article walks ten engineering surfaces around an Agent Loop and argues that the loop itself is stable across implementations — what changes (and what determines whether the system works in production) is everything around the loop.

• The loop is ~20 lines. Perceive → decide → act → feedback, until the model returns text. New capabilities are added by extending tools, restructuring the system prompt, or externalizing state — almost never by editing the loop.
• Workflow vs. Agent. Code-decided control flow is a Workflow; LLM-decided control flow is an Agent. Five common control patterns (Prompt Chaining, Routing, Parallelization, Orchestrator-Workers, Evaluator-Optimizer) cover most real systems; Agent isn’t the default — pick the cheapest pattern that meets the task.
• Harness beats model. OpenAI‘s Codex team shipped 1M LoC / ~1500 PRs with three engineers in five months — the multiplier wasn’t model strength, it was four engineering decisions: knowledge lives in the codebase (codebase-as-system-of-record — not external docs the Agent can’t see), constraints encoded in linters/types/CI not docs, end-to-end autonomy without human checkpoints, and minimized merge friction. The “task clarity × verification automation” 2×2 maps where Agents can be deployed at all.
• Context engineering for stability. Long contexts dilute attention; in 1M-context models, Context Rot shows up around 300–400K tokens. Layer context by stability and access frequency: resident (identity, hard constraints), on-demand (Skills descriptors resident, body lazy-loaded), runtime injection (time, channel), memory (MEMORY.md), system layer (Hooks). Three compression strategies (sliding window, LLM summary, tool-output replacement); five session-management branches (continue / rewind / clear / compact / subagents) — rewind often beats correct. Prompt cache hits demand prefix stability, which is why the resident layer must stay short and stable.
• ACI tool design. Tools should map to Agent goals, not API endpoints. Three-generation evolution: API-wrapping (one tool per endpoint, too granular) → ACI (one tool per goal, errors structured with repair hints) → Advanced Tool Use (Tool Search for dynamic discovery, Programmatic Tool Calling so middle results bypass the LLM, Tool Use Examples — 1–5 real calls bumps accuracy 72%→90%). Most “wrong tool selected” debugging traces to the description, not the model.
• Memory as four problem types, not four storage media. Working memory (context window), procedural (Skills), episodic (JSONL session history), semantic (MEMORY.md). ChatGPT’s production implementation is ~33 facts + 15 conversation summaries — no vector DB, no RAG. OpenClaw uses a hybrid retrieval (70% vector / 30% keyword) over a markdown corpus. Consolidation triggered at 50% token usage; failure path archives to archive/ rather than dropping.
• Releasing autonomy in order. First Harness, then rollback (provider switch / workspace isolation / allowlist / audit), only then autonomy. Long tasks that don’t fit one session: split into Initializer Agent (run once, generate feature-list.json, init.sh, initial commit, claude-progress.txt) and Coding Agent (loop, restore from filesystem, implement one feature, test, mark passes: true, commit). Progress in files, not context.
• Multi-agent needs protocol before parallelism. Orchestrator + workers via JSONL inbox (request_id, from_agent, to_agent, status, append-only, crash-recoverable); .tasks/ for task graph; .worktrees/ for file isolation. Hallucination amplifies across Agents — independent verifiers (second LLM, unit tests, compiler, human) break the chain. Sub-agents get a minimal prompt (Tooling, Workspace, Runtime — no Skills, no Memory) and a depth limit.
• Agent evaluation is structurally harder than single-turn. Two metrics serve different purposes: Pass@k (k attempts, ≥1 pass — capability ceiling, exploration) vs. Pass^k (k attempts, all pass — regression, every release). Three grader types: code (string match, unit tests — most reliable), model (LLM-as-judge, comparison, voting), human (slow but the calibration anchor). Watch transcript and outcome — “I shipped” without DB write is a real failure mode that pure-transcript graders miss. First fix the eval, then change the Agent: degraded scores often indict infra (resource caps, eval bugs, drift) rather than the model.
• Trace as event stream, not log. Emit on tool_start / tool_end / turn_end; one event publish, many subscribers (logs / UI / online eval / human review queue). Two-layer observability: human sampling (rule-routed: negative feedback, high-cost conversations, scheduled, post-deploy 48hr) calibrates the LLM auto-grader, the LLM auto-grader covers volume.
• OpenClaw as walk-through. Five-layer decomposition (Gateway WebSocket / Channel adapters / Pi Agent / Toolset / Context+Memory) that is parallel to but not the same as Tw93’s Claude Code six-layer frame. MessageBus decouples 23+ channels from the loop; system prompt loaded in layers (SOUL.md, AGENTS.md, TOOLS.md, USER.md, MEMORY.md, Skills index); cron + heartbeat for non-user-initiated runs; security in three concentric layers (allowlist → workspace path check → audit log) plus prompt-injection hardening (source-sink separation, untrusted-content tags, independent LLM verifier on critical paths). Implementation order: single channel first → security boundary before features → memory consolidation early → Skills before new tools → first failure becomes a test case.

Notable claims

• The Agent loop has stayed structurally stable across implementations the author has read; new capability is added outside the loop, not by editing it. (agent-loop)
• More expensive models help less than people expect; Harness quality and verification quality move success rate more. (harness)
• Most “Agent picked the wrong tool” debugging is a tool-description problem, not a model problem. (agent-computer-interface)
• Tool Search ships in Claude as defer_loading-style behavior: with on-demand discovery, context retention rose to ~95% and Opus 4 accuracy went 49% → 74%. (Numbers from the source; corroborate against anthropic primary docs — already flagged on prompt-caching.)
• Programmatic Tool Calling moves middle data out of the LLM’s context: a worked example drops token usage from ~150K to ~2K.
• Tool Use Examples (1–5 real calls embedded with the schema) raise tool-call accuracy from 72% to 90% in the cited measurement.
• 5 MCP servers ≈ 55K tokens of tool definitions (model-context-protocol previously had ~25K from the prior source — different sample, same direction).
• Cursor‘s A/B test on file-backed MCP descriptions cut total token usage 46.9% on MCP-using tasks. (Names a primary source-of-source: Cursor’s internal eval.)
• Skills evaluation: descriptors without counter-examples, accuracy drops baseline 73% → 53%; with counter-examples it rises to 85% and response time falls 18.1%. (See updated claude-skills anti-patterns.)
• Hallucination amplification across Agents: in chained collaboration, errors compound rather than cancel; cross-Agent verification is what breaks the chain. (multi-agent-orchestration)
• Eval-system errors and Agent-quality regressions look identical from the outside. The author makes “fix the eval first” a hard rule. (agent-evaluation)
• Real example (Anthropic’s Demystifying evals post): an Opus 4.5 booking Agent found a fare-rule loophole and got the user a cheaper itinerary. A pure-transcript grader marks this fail; an outcome grader marks it pass. The lesson: graders that only watch the path miss legitimate creativity.

Notable quotes

工具问题多数不在数量不够，而在选不对、描述看不懂、返回一堆没用的、出了错 Agent 也不知道怎么改。

(Most tool problems aren’t “not enough tools” — they’re: wrong tool picked, description unreadable, returns a pile of useless data, errors leave the Agent with no idea how to fix.)

看 Agent 怎么说和看系统最后变成什么样是两件事。

(Watching what the Agent says and watching what the system actually became are two different things.) — the transcript-vs-outcome distinction in agent-evaluation.

别把确定性逻辑放进上下文。

(Don’t put deterministic logic in the context.) If a rule can be expressed by Hooks, code, or a tool constraint, that’s where it goes — the model shouldn’t keep re-reading it.

安全边界要先于功能。

(The security boundary precedes the features.) On the openclaw implementation order — allowlist, workspace isolation, parameter validation must be in place before any new tool is added.

Open questions

• The Tool Use Examples and Tool Search numbers (72→90%, 49→74%, 95% retention) are quoted as unsourced figures — would be useful to chase the primary publications (Anthropic and Cursor blog/research).
• The “5 MCP servers ≈ 55K tokens” figure differs in scale from the prior source’s “5 servers ≈ 25K tokens” (model-context-protocol) — likely measuring different tool definition styles or counting Schema fields differently. Worth a real /mcp reading on a representative install.
• The 70/30 vector/keyword split in openclaw‘s memory retrieval is presented without ablation — does the ratio matter, or is “have keyword fallback” the actual load-bearing decision?
• The OpenAI Codex “1500 PRs in 5 months with 3 engineers” claim deserves a primary citation for the workflow details. Resolved (2026-04-27, same day): 2026-04-27-harness-engineering-codex-agent-first is that primary source — the workflow details (tooling, verifier loop, review model) are documented there first-hand.

Pointers

• Case-study project: openclaw (Peter Steinberger; github.com/openclaw/openclaw). Tw93 uses it as a worked example; he is not the author.
• References cited at the end: Anthropic’s Skills, Context management on Claude Developer Platform, Demystifying evals for AI agents, Measuring agent autonomy; OpenAI’s Harness engineering and Designing agents to resist prompt injection; Cloudflare’s How we rebuilt Next.js with AI in one week; Simon Willison’s port of JustHTML; LangChain’s State of Agent Engineering; a thread by Thariq (Anthropic) on Claude Code session management & 1M context.
• Companion source: 2026-04-27-claude-code-architecture-governance-engineering (the author’s prior, Claude-Code-specific essay). Several concepts are reinforced from a different angle here — see context-engineering, claude-skills, prompt-caching for added detail.