> For the complete documentation index, see [llms.txt](https://levon.gitbook.io/agent-engineering/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://levon.gitbook.io/agent-engineering/readme.md).

# 导读

假设运维 Agent 收到指令给客户发送“系统维护完毕”通知。它成功把邮件推给了网关，却在本地写下“发送成功”的前一毫秒准时崩溃。

重启后，Agent 睁开眼只看见一项未完成的任务。怀着对工作的极致敬业态度，它决定再发一次。在没有幂等与状态审计的系统里，**Agent 越勤奋，你的灾难就越壮观**——十分钟后，客户收件箱里整整齐齐躺着 300 封一模一样的通知，而 Agent 依然困惑为什么任务总是不算完。

能调用工具只是演示的胜利。在带副作用的真实世界里，真正困难的是：历史越来越长时给 Model 看什么，程序中断后怎样继续，副作用不明时能不能重试，用户批准后命令又能碰到什么。这本书从一个最小 Tool Calling Loop 出发，一层层补上持久化、Context、故障恢复、Sandbox 和 Tracing，直到一次 Agent 运行可以被解释、限制和验证。

## 适合谁，怎样学

你只需要会一点 Python、Git 和命令行。Tool Calling、Context、JSONL、幂等、Trace、Sandbox 等术语，不要求提前懂；本书会等它们真正派上用场时再解释。

本书以 Agent Runtime / AI Systems 为主要技术深度，同时保留真实应用落地。本书不把框架名称或一次成功演示当作证据，每个关键结论都要经过实际材料检查：

* 用官方文档和固定版本的源码确认真实实现；
* 用最小代码跑通关键路径；
* 主动制造截断、崩溃、重复执行和越界访问；
* 通过主动回忆检查能否独立解释和迁移。

📖 **在线阅读**：<https://levon.gitbook.io/agent-engineering/>

## 源码依据

源码参考不追求把热门框架全部讲一遍，而是分成三组，让每组项目回答自己最擅长的问题：

* **Coding Agent Runtime**：[Pi](https://github.com/earendil-works/pi)、[OpenClaw](https://github.com/openclaw/openclaw)、[Hermes](https://github.com/NousResearch/hermes-agent)、[Codex](https://github.com/openai/codex)、[OpenCode](https://github.com/anomalyco/opencode) 与 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)，主要用于观察 Agent Loop、Session、Context、Tool、权限和安全边界。DeepSeek Harness 仍处于 Developer Preview，本书只针对核验过的固定版本讨论；
* **Agent 框架与接口**：[OpenAI Agents SDK](https://github.com/openai/openai-agents-python)、[Claude Agent SDK Python](https://github.com/anthropics/claude-agent-sdk-python) 与 [LangGraph](https://github.com/langchain-ai/langgraph)，主要用于观察通用 Agent Loop、Session、Handoff、Guardrail、状态图和长任务恢复；
* **可观测性与评估**：[Phoenix](https://github.com/Arize-ai/phoenix) 与 [Inspect AI](https://github.com/UKGovernmentBEIS/inspect_ai)，主要用于观察 Trace、Span、Dataset、Solver、Scorer 和 Evaluation。

[Claude Code](https://github.com/anthropics/claude-code) 也会作为重要的产品行为参考，但其核心 Runtime 没有开源。书中只根据官方文档、设置、插件和示例研究它的权限、Hooks、Sandbox、Memory、Subagent 与 Workflow，不把这些外部行为说成已经核验过的内部实现。

## 阅读路线

| 阶段          | 课程                                                     | 状态           |
| ----------- | ------------------------------------------------------ | ------------ |
| 一：判断与行动     | 第 1～3 课：是否需要 Agent、Runtime 与 Tool Calling Loop；第 0 课选读 | 已完成          |
| 二：状态、可靠性与控制 | 第 4～7 课：持久化、Context、故障恢复与 Sandbox                      | 已完成          |
| 三：看见与验证     | 第 8～9 课：Trace，以及合并回归检查的 Agent Evaluation               | 第 8 课已完成     |
| 四：编排与长任务    | 第 10 课：Workflow、Routing、Handoff、少量 Subagent、后台任务与恢复    | 待第 9 课验证后开始  |
| 五：生产运行      | 第 11 课：并发、队列、限流、成本、部署、监控与回滚                            | 待第 10 课验证后开始 |
| 可选分支        | RAG、MCP/A2A、Browser、Voice、多模态与专用 Sandbox               | 按实际问题选择      |

第 9～11 课是当前唯一详细规划的未来主线，不提前创建空章节。Recorded-session Replay、完整 OpenTelemetry 平台和大规模 Multi-Agent 都在真实问题出现后再补。

完整目录见 [SUMMARY.md](https://github.com/unix2dos/agent-engineering-book/tree/main/SUMMARY.md)。

## 代码与综合实践

教学代码按对应课程放在 `examples/`：

* [`lesson_03_tool_calling_loop.py`](https://github.com/unix2dos/agent-engineering-book/tree/main/examples/lesson_03_tool_calling_loop.py)：最小 Tool Calling Loop；
* [`lesson_04_session_memory.py`](https://github.com/unix2dos/agent-engineering-book/tree/main/examples/lesson_04_session_memory.py)：Session、Checkpoint 与长期记忆；
* [`lesson_05_context_compaction.py`](https://github.com/unix2dos/agent-engineering-book/tree/main/examples/lesson_05_context_compaction.py)：JSONL Transcript、Compaction 与 Prompt View；
* [`lesson_06_tool_reliability.py`](https://github.com/unix2dos/agent-engineering-book/tree/main/examples/lesson_06_tool_reliability.py)：Execution Ledger、幂等与故障恢复。

[阶段一～二综合实践](https://github.com/unix2dos/agent-engineering-book/tree/main/exercises/phase-1-capstone/README.md)会把有停止条件的 Agent Loop、受限工作区工具、Transcript、Prompt View、Ledger 和故障恢复串成一个可以运行的小系统。

[SQLite 专项练习](https://github.com/unix2dos/agent-engineering-book/tree/main/exercises/session-storage-sqlite/README.md)连接第 4 课的存储选择与第 6 课的可靠执行，从状态查询开始，验证索引、事务和唯一约束什么时候比继续扩写 JSONL 代码更省事。

[第 7 课安全边界练习](https://github.com/unix2dos/agent-engineering-book/tree/main/exercises/lesson-07-safety/README.md)先证明 `cwd=workspace` 不是 Sandbox，再逐层加入 Tool Policy、Approval、执行 Backend 与 Elevated。

[第 8 课 Trace 练习](https://github.com/unix2dos/agent-engineering-book/tree/main/exercises/lesson-08-tracing/README.md)先把一次 Agent Run 组织成具有共同 `trace_id` 和父子关系的 Span。

后续课程继续扩展同一个综合 Agent：第 9 课加入固定任务与回归检查，第 10 课加入编排和长任务，第 11 课再处理生产运行。RAG 与 MCP 只在这个项目确实需要知识检索或外部能力时加入。

这些代码是教学实现，不宣称覆盖生产系统的并发、分布式事务、租户隔离和高可用要求。

## 单一真实源（SSOT）与发布规范

本仓库是唯一持续维护的权威源（Single Source of Truth）。历史发布的 Blog 文章仅作为外部快照和引流入口保留，除修正失效链接和关键事实错误外，不再全量同步正文；新 Blog 仅在阶段收官或特定话题独立成篇时发布。GitBook 镜像仅用于排版展示，不作为并行写作来源。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://levon.gitbook.io/agent-engineering/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.