mcp server
aiagentsystem
Open-source Chinese AI Agent Systems textbook and engineering lab: runtimes, MCP/A2A, durable execution, evaluation, security, and 80 fault-injection labs.
Set up
Runs on your computer. Pick your agent and operating system.
This project does not publish an install method we can turn into a config. Follow the README instead.
README
synced Oct 26, 2026AI Agent Systems：从模型、Runtime、协议到生产可靠性
下载主书 PDF / EPUB / HTML（v1.0.0 离线包） · 从目录在线阅读中文正文 · 浏览 80 个实验 · 查看完整 Release
这是一套面向工程师、研究者与高校课程的简体中文开源 AI Agent 系统教材与实验工程。它不把 Agent 简化为“LLM 加一个循环”，而是围绕下面这条系统主线展开：
Agent System = Model + Context + Tools + State + Runtime + Evidence + Governance
全书把模型接口、Context Engineering、Tool/RAG/Memory、MCP/A2A、Runtime/Harness、Durable Execution、Coding/Browser/Data/Research Agent、Multi-Agent、Evaluation、Security、Recovery、Production、Post-training 与 Self-improvement 连接成一套可以阅读、运行、故障注入和审计的知识体系。
当前公开基线为内容版本 v1.0.0 / Build System 1.1.2，知识、协议与研究观察截止到 2026-09-11（Asia/Shanghai）。本项目目前只维护简体中文，不提供未经持续校验的翻译版本。
先读、先跑还是先下载
| 目标 | 推荐入口 | 你会得到什么 |
|---|---|---|
| 离线阅读主书 | 下载 BOOK.zip | 主书 PDF/EPUB/HTML、实验手册 PDF/EPUB/HTML、离线网站；解压后主书 PDF 位于 book/build/ai-agent-systems-course-v1.0.0.pdf |
| 在 GitHub 阅读 | 中文目录与 40 章正文 | 无需安装环境，按七篇结构逐章阅读 Markdown 正文 |
| 运行实验 | 下载 CODE-LABS.zip | Runtime 源码、40 个章节示例、80 个 Core Labs、测试、集成轨道与生产案例 |
| 使用实验手册 | 下载 BOOK.zip | 解压后实验手册 PDF 位于 workbook/build/agent-systems-lab-workbook-v1.0.0.pdf |
| 授课或分享 | 下载 SLIDES.zip | 90 页 PPTX 以及幻灯片源文件 |
| 获取全部交付物 | 下载 ALL-DELIVERABLES.zip | 书籍、源码、Labs、Slides、QA evidence、构建元数据与内部组件校验清单 |
| 审计发布 | SHA256SUMS.txt · SBOM | 全部非清单资产的 SHA-256、CycloneDX SBOM 与 GitHub/Sigstore provenance |
GitHub Release 当前采用可审计压缩包分发 PDF，而不是把生成物提交到 main。这样可以让 PDF、EPUB、网站、校验和、SBOM 与构建 provenance 保持在同一个版本边界内。所有固定版本链接都指向 v1.0.0，不会在后台静默变成其他内容。
这套项目解决什么问题
很多 Agent 教程能演示一次工具调用，却没有回答系统进入真实环境之后最困难的问题：
- 模型提出的 tool call 与真实副作用之间，谁拥有最终执行权？
- 上下文、记忆和检索如何带着来源、版本、预算与删除语义进入模型？
- timeout 发生时，动作究竟是
COMMITTED、NOT_APPLIED还是UNKNOWN？ - Agent 崩溃、重启、重复审批或并发写入后，如何恢复而不重复产生不可逆副作用？
- MCP、A2A、OpenAI Agents、LangGraph、Google ADK、Microsoft Agent Framework 的协议或 Runtime 边界如何验证？
- Coding/Browser Agent 的能力应该如何用轨迹、独立 verifier 和真实 benchmark 衡量？
- 从实验 fixture 到官方 SDK、真实 provider、真实环境和生产声明，中间分别缺少什么证据？
因此，每章都尽量保持同一条工程闭环：
系统问题 → 概念与不变量 → 形式化模型 → 关键实现 → 正常路径
→ 故障注入 → 独立验证 → 证据等级 → 上游实现与研究边界
本仓库是教材、实验与参考实现 monorepo，不是面向 PyPI 发布的通用 Agent SDK，也不把安装成功、模型自述或预设 fixture 分数冒充生产证据。
项目规模与已经验证的范围
| 内容 | 当前 v1.0.0 源码合同 |
|---|---|
| 中文正文 | 40 章 + 13 附录，分为 7 篇 |
| Core Labs | 80 个：40 条正常路径 + 40 条故障注入路径 |
| Python 示例 | 69 个：40 个章节入口 + 29 个支撑示例 |
| 自动化测试 | 237 项；覆盖率由 make coverage 的质量门实时验证 |
| 主书 | PDF 以当前源码构建结果为准 + EPUB + HTML |
| 实验手册 | PDF 以当前源码构建结果为准 + EPUB + HTML |
| 网站构建物 | 134 个 HTML 页面（当前源码构建合同） |
| 教学幻灯片 | 90 页 PPTX；本轮仅完成结构核验，本机 LibreOffice 的中文字形渲染尚未通过视觉验收，使用前请在目标软件中抽检 |
| 外部来源锁 | 114 项；唯一 URL 数由 source-lock QA 实时核验 |
| Scoped L5 外部证据 | 6 项：MCP、A2A、OpenAI Agents、LangGraph、Google ADK、MAF |
表中数量描述当前源码；只有在同一 commit 的 hosted canonical CI、校验和与 Release 上传全部完成后，下载区资产才继承这些数字。当前工作树的本地证据与待运行项以验证报告为准，历史 CI 不自动证明新改动。
详细状态及每一种 PASS 能证明到哪里，见 EXPERIMENT_STATUS.md 与 v1.0.0 验证报告。
推荐学习路径
- 第一次系统学习 Agent：按第 1–20 章顺序阅读，并逐章运行 A/B 实验；先建立 Model—Runtime—Effect—Evidence 的边界。
- Agent 平台与应用工程师：重点阅读第 7–19、26–36、40 章，结合
src/agentlab/与生产 API 案例。 - 协议与框架工程师：重点阅读第 13、21–28 章，再进入
integrations/的官方实现证据轨道。 - 评测、安全与可靠性研究者：重点阅读第 18、23、29–34、39 章以及附录 C、E。
- 课程教师：使用主书 + 80-Lab Workbook + 90 页 Slides；A/B 配对适合课堂演示“正确路径—失效机制—验收证据”。
四十章正文与实验导航
每章都对应两个可运行实验：A 是正常路径，B 是故障注入。正文、实验说明、命令、预期输出、验收条件和证据上限都可以从下表直接打开。
第一篇 · 基础：从模型接口到可调试 Agent
| 章 | 核心问题 | 正文 | 实验 |
|---|---|---|---|
| 01 | 决策、授权、执行、观察与验证如何构成受治理行动系统 | 阅读 | 01A 正常 · 01B 故障 |
| 02 | 概率生成如何经过 syntax/schema/semantic/authorization 成为意图 | 阅读 | 02A 正常 · 02B 故障 |
| 03 | Context 如何作为带 provenance、tenant、trust 与预算的运行时视图 | 阅读 | 03A 正常 · 03B 故障 |
| 04 | 类型化 item、call identity 与 append-only trajectory 如何保持因果关系 | 阅读 | 04A 正常 · 04B 故障 |
| 05 | 候选计划怎样经过 DAG、能力与预算检查才进入执行 | 阅读 | 05A 正常 · 05B 故障 |
| 06 | Reducer、事件重放、Checkpoint CAS 与副作用边界如何支持恢复 | 阅读 | 06A 正常 · 06B 故障 |
第二篇 · 知识、工具、记忆与协议
| 章 | 核心问题 | 正文 | 实验 |
|---|---|---|---|
| 07 | Tool schema、前置条件、后置条件与风险标签如何设计 | 阅读 | 07A 正常 · 07B 故障 |
| 08 | Tool Runtime 如何处理权限、超时、重试、幂等与副作用 | 阅读 | 08A 正常 · 08B 故障 |
| 09 | RAG 如何建立检索、证据、引用和生成之间的边界 | 阅读 | 09A 正常 · 09B 故障 |
| 10 | Hybrid / Agentic RAG 如何把检索变成可评估的决策过程 | 阅读 | 10A 正常 · 10B 故障 |
| 11 | 长期记忆如何写入、检索、合并、过期和删除 | 阅读 | 11A 正常 · 11B 故障 |
| 12 | Skills 与 Procedural Memory 如何版本化和安全复用 | 阅读 | 12A 正常 · 12B 故障 |
| 13 | MCP 的 Host/Client/Server、transport 与 capability 边界 | 阅读 | 13A 正常 · 13B 故障 |
第三篇 · Runtime、Durable Execution 与 Harness
| 章 | 核心问题 | 正文 | 实验 |
|---|---|---|---|
| 14 | Agent Loop 如何从 while 循环升级为有界状态机 | 阅读 | 14A 正常 · 14B 故障 |
| 15 | 流式、并发、中断、取消与 backpressure 如何正确传播 | 阅读 | 15A 正常 · 15B 故障 |
| 16 | Human-in-the-Loop 如何绑定不可变动作并安全恢复 | 阅读 | 16A 正常 · 16B 故障 |
| 17 | Sandbox、权限与资源配额如何限制 Agent 爆炸半径 | 阅读 | 17A 正常 · 17B 故障 |
| 18 | Checkpoint、Journal、CAS 和 hash-chain 如何支持崩溃恢复 | 阅读 | 18A 正常 · 18B 故障 |
| 19 | Harness 如何组合 workspace、tool、policy、approval 与 verifier | 阅读 | 19A 正常 · 19B 故障 |
| 20 | Coding Agent 如何形成“读—改—测—验证”的最小闭环 | 阅读 | 20A 正常 · 20B 故障 |
第四篇 · 专用 Agent 与真实环境
| 章 | 核心问题 | 正文 | 实验 |
|---|---|---|---|
| 21 | Codex、Pi、Claude Code 类 Coding Harness 的责任边界 | 阅读 | 21A 正常 · 21B 故障 |
| 22 | OpenHands 与远程 Agent Server 如何隔离运行环境和会话 | 阅读 | 22A 正常 · 22B 故障 |
| 23 | Browser / Computer Use Agent 如何观察、行动和验证页面状态 | 阅读 | 23A 正常 · 23B 故障 |
| 24 | Data Agent 如何约束 SQL/Python 并留下可审计分析证据 | 阅读 | 24A 正常 · 24B 故障 |
| 25 | Research Agent 如何维护来源、引用、冲突和报告证据链 | 阅读 | 25A 正常 · 25B 故障 |
| 26 | LangGraph / ADK / MAF 的 Graph Runtime 共同抽象 | 阅读 | 26A 正常 · 26B 故障 |
第五篇 · Workflow、Multi-Agent 与互操作
| 章 | 核心问题 | 正文 | 实验 |
|---|---|---|---|
| 27 | A2A 的 AgentCard、Task、状态与跨 Agent 互操作 | 阅读 | 27A 正常 · 27B 故障 |
| 28 | Multi-Agent 的分工、隔离、调度、聚合与成本控制 | 阅读 | 28A 正常 · 28B 故障 |
第六篇 · Evaluation、Benchmark、Observability、安全与可靠性
| 章 | 核心问题 | 正文 | 实验 |
|---|---|---|---|
| 29 | Agent Evaluation 如何同时评价结果、轨迹、成本与安全 | 阅读 | 29A 正常 · 29B 故障 |
| 30 | SWE-bench、OSWorld、PaperBench、MLE-bench 能证明什么 | 阅读 | 30A 正常 · 30B 故障 |
| 31 | Trace、Metrics、Evidence 与 AgentOps 如何形成可观测闭环 | 阅读 | 31A 正常 · 31B 故障 |
| 32 | Prompt Injection、委托权限和最小权限如何系统化防护 | 阅读 | 32A 正常 · 32B 故障 |
| 33 | 外部副作用在 UNKNOWN 结果下如何协调、补偿和恢复 | 阅读 | 33A 正常 · 33B 故障 |
| 34 | Token、延迟、并发、缓存与成本如何联合优化 | 阅读 | 34A 正常 · 34B 故障 |
| 35 | 生产 Agent API 如何处理租户、幂等、审批和审计 | 阅读 | 35A 正常 · 35B 故障 |
第七篇 · 生产工程、训练与持续演进
| 章 | 核心问题 | 正文 | 实验 |
|---|---|---|---|
| 36 | Docker、本地开发、CI 与发布证据如何形成部署基线 | 阅读 | 36A 正常 · 36B 故障 |
| 37 | SFT/RL/Post-training 如何塑造 Agent 的工具与决策能力 | 阅读 | 37A 正常 · 37B 故障 |
| 38 | 多模态、语音、机器人与实时 Agent 如何扩展观察/动作空间 | 阅读 | 38A 正常 · 38B 故障 |
| 39 | Self-Improving Agent 如何优化、评估、门禁和回滚 | 阅读 | 39A 正常 · 39B 故障 |
| 40 | 把 Runtime、协议、审批、恢复、评测与部署合成 AgentOps 闭环 | 阅读 | 40A 正常 · 40B 故障 |
十三个附录
| 附录 | 内容 | 入口 |
|---|---|---|
| A | 统一实验环境、调试与复现 | 阅读 |
| B | 上游开源项目版本锁与源码阅读索引 | 阅读 |
| C | Agent Systems 故障模型与排错速查 | 阅读 |
| D | 术语、不变量与状态词典 | 阅读 |
| E | 2026 AI Agent 研究版图、理论前沿与开放问题 | 阅读 |
| F | 行业状态、产业影响与 2026–2030 发展判断 | 阅读 |
| G | 第一篇六章思考题与实践题参考答案 | 阅读 |
| H | 第二篇七章思考题与实践题参考答案 | 阅读 |
| I | 第三篇七章思考题与实践题参考答案 | 阅读 |
| J | 第四篇六章进阶问题参考答案 | 阅读 |
| K | 第五篇两章进阶问题参考答案 | 阅读 |
| L | 第六篇七章进阶问题参考答案 | 阅读 |
| M | 第七篇五章进阶问题参考答案 | 阅读 |
运行第一个实验
核心实验支持 macOS、Linux、WSL2，支持 x86_64 与 arm64，需要 Python 3.11–3.13。80 个 Core Labs 使用确定性 fixture，不要求 API Key、Docker、浏览器或外网。
git clone https://github.com/william-lbn/aiagentsystem.git
cd aiagentsystem
# 安装锁定依赖并检查环境
make bootstrap
make bootstrap-check
# 第 1 章：正常路径
PYTHONPATH=src uv run python examples/chapters/ch01_foundation.py
# 第 1 章：故障注入路径
PYTHONPATH=src uv run python examples/chapters/ch01_foundation.py --fault
进一步验证：
make labs # 运行 80 个 Core Labs
make test # 运行 233 项 pytest
make examples # 运行 69 个 Python 示例
make validate # 完整本地质量门与出版验证
每个 Lab 文档都包含环境、入口、调试断点、命令、实际输出、PASS 条件和结果解释。想先看完整机制，可从 Lab 01A、Lab 18B：Journal 故障、Lab 33B：副作用恢复故障 或 Lab 40A：端到端 AgentOps 开始。
从教学 fixture 到真实外部证据
项目用分级证据防止实验结论越界：
| 等级 | 含义 |
|---|---|
| L1 | 本地确定性机制断言成立 |
| L2 | 独立 oracle 或系统检测到故障 |
| L3 | 系统识别并 fail-closed / containment |
| L4 | 完成可验证的恢复或协调 |
| L5 | 真实 pinned 上游实现完成行为、故障、独立 verifier 与证据包 |
v1.0.0 已保存 6 项范围明确的官方实现证据：
- MCP 与 A2A SDK / wire-contract 轨道；
- OpenAI Agents SDK、LangGraph、Google ADK 与 Microsoft Agent Framework Runtime 轨道；
- SWE-bench Lite 与 WebArena 目前只有固定执行合同，未在 v1.0.0 发布分数；
DEFINED、NOT_EXECUTED与EXTERNAL_NOT_RUN_IN_THIS_RELEASE均不是通过状态。
审计总表见 L5 External Evidence Audit。运行真实 provider 的实验时，可以通过环境变量提供 OPENAI_API_KEY；仓库不会要求、打印或提交真实 Key。请从 .env.example 开始，并始终在提交前运行索引安全门禁。
代码与工程地图
book/zh/ 40 章中文正文、13 个附录、唯一目录源
book/assets/diagrams/ 80 个 DOT 权威图源及可审查 SVG
src/agentlab/ Runtime、Tool、State、Checkpoint、Journal、Eval 等核心实现
examples/chapters/ 40 个与章节逐一对应的可执行入口
examples/ 29 个支撑性工程示例
labs/core/ 80 个 A/B Core Labs 文档与验收证据
integrations/ 官方 SDK、上游框架、协议和 benchmark 复现轨道
production/agentops_service/ FastAPI + SQLite 的生产风格 AgentOps 案例
tests/ 单元、故障语义与端到端测试
scripts/ 构建、QA、发布、校验和与可复现性门禁
推荐从这些实现入口开始读代码：
- Runtime 主循环、工具注册与执行、模型与决策结构
- 第三篇 Runtime 机制：有界循环、结构化并发、路径能力门禁、插件回滚与 Coding Workspace
- 第四篇专项 Agent 机制：Session/事件持久化、真实 loopback HTTP、只读 SQL、证据绑定与 durable graph
- 第五篇协调机制：任务绑定委派、A2A durable task、所有权/权限、预算事务与幂等 join
- Checkpoint、Journal、事件模型
- Workflow、Tracing、Evaluation
- Memory、Retrieval、Security
- 生产风格 AgentOps Service
构建书籍、网站、实验手册与幻灯片
仓库采用 Single Source, Multiple Artifacts。course.toml 保存版本和工具链元数据，book/zh/SUMMARY.md 是章节顺序的唯一来源，正文、Lab 与代码都是 canonical source。
先检查 Pandoc、XeLaTeX、Graphviz、Poppler、CJK 字体和 Rust/Cargo：
make toolchain
make build
默认 make build 使用已验证的 Pandoc compatibility 路径。有 Quarto 1.11.1 时可运行 canonical 路径：
make build-canonical
make validate-canonical
正式发布由 digest-pinned container 和 tag-triggered GitHub Actions 构建，生成校验和、CycloneDX SBOM 与 GitHub artifact attestation。详细出版架构见 Build System 1.1.2，发布操作见 RELEASING.md。
验证发布资产
Release 中的 SHA256SUMS.txt 使用 basename 覆盖除自身外的每一个下载资产。下载完整 Release 后可以执行：
gh release download v1.0.0 --repo william-lbn/aiagentsystem
shasum -a 256 -c SHA256SUMS.txt
# 对任一下载资产验证 GitHub/Sigstore provenance
gh attestation verify BUILD-METADATA.json --repo william-lbn/aiagentsystem
v1.0.0 的发布保证是：锁定 container 中的 canonical 构建、同一 host 上两次隔离冷环境的 format-aware clean rebuild、结构与语义 QA、SHA-256、SBOM 与 provenance。它不宣称不同宿主系统上的第三方 PDF/EPUB 出版器输出逐字节一致；APT/CTAN 供应链也明确记录为 non-hermetic-recorded。
开源协作
- 许可证与第三方边界：LICENSE · LICENSING.md · THIRD_PARTY_NOTICES.md
- 贡献、行为准则与治理：CONTRIBUTING.md · CODE_OF_CONDUCT.md · GOVERNANCE.md
- 安全报告：SECURITY.md；请勿把漏洞或真实凭据提交到公开 Issue
- 使用支持：SUPPORT.md
- 学术引用：CITATION.cff
- 版本变更：CHANGELOG.md · RELEASE_NOTES.md
欢迎提交勘误、失败复现、上游 SDK 兼容性证据和能够提高 claim level 的真实实验。对“已运行”“已恢复”“可复现”或“达到 L5”的修改，请同时提交可独立检查的 verifier 与证据边界，而不只提交成功截图或模型输出。