heaven999b / hello-agent-system

# 👋 Hello Agent System
### 企业级 Agent 系统设计训练营
**从"会调 LLM API"到"能设计生产级 Agent 系统"：32 节课 · 中英双语 · 每课都有带测试的练习。**
不依赖任何 Agent 框架，从零手写企业级 Agent 的每一层：工具、上下文、架构、编排、可靠性、安全、可观测、评估、并发、成本、发布；再到检索、记忆、MCP、数据、评估方法论、优化、编码 Agent 与主动式 Agent。**从第 02 课起就是 async**（一个进程同时服务成百上千个会话），**从第 12 课起就是真实的多进程**（崩溃接手、僵尸 worker、优雅停机，全部用真进程和真信号验证）；最后把同一套接口换成成熟组件（Postgres、Redis、Temporal、OpenTelemetry、LiteLLM、Cedar），落到生产。
本项目由 **Claude Opus 5.5** 协助架构设计
**中文** · English
快速开始 · 学习路线 · 综合实战 · 失败模式图鉴 · 面试题
---
## 🤔 为什么要做这个项目？
写一个"能跑"的 Agent 只要 20 行代码。但把它放进公司、让成千上万人用，你马上会遇到这些问题：
> 模型 429 了怎么办？Agent 陷入死循环一晚上烧了 2000 美元怎么办？用户在文档里藏一句"忽略之前的指令"就能让 Agent 重置管理员密码怎么办？A 公司的数据出现在 B 公司的回答里怎么办？改了一行 prompt，怎么知道有没有把别的场景改坏？进程在 Agent 执行到一半时重启了怎么办？
**这些问题决定了一个 Agent 能不能上线，而绝大多数教程只教那 20 行。**
| | 常见 Agent 教程 | 本项目 |
|---|---|---|
| 目标 | 让 Agent 跑起来 | 让 Agent **在生产中可靠、安全、可控地**跑起来 |
| 方式 | 调用框架 API（黑盒） | **从零手写每一层**（核心约 3800 行 + 多进程模块约 2000 行，每行都能看懂） |
| 覆盖 | 循环 + 工具 | LLM 必备知识、循环、工具、上下文、常见架构、编排、**工程考量全景**；重试熔断降级、检查点恢复、提示词注入防御、RBAC、人工审批、审计、追踪、评估；高并发与分布式执行、成本优化、权限感知 RAG、灰度发布与事故响应；检索质量、记忆系统、MCP 与沙箱、主流框架对照、Agent 数据、评估方法论、提示词优化与测试时计算、编码 Agent、主动式 Agent；**asyncio 并发、真实多进程执行（租约、fencing、kill -9 接手、网络分区）、Postgres/Redis/Temporal/OpenTelemetry/LiteLLM/Cedar 生产落地、多 worker 参考服务与压测** |
| 讲法 | 一种做法 | 企业问题卡片：**每个问题 2–4 种方案对比**，讲清怎么选 |
| 验证 | 看起来能用 | 每课都有**带自动化测试的练习**，离线、确定性、零成本；说"并发"就用在途峰值证明，说"多进程 / 崩溃接手"就起真实进程、发真实信号 |
| 模型 | 绑定某家厂商 | 任何 OpenAI 兼容接口（OpenAI / DeepSeek / Qwen / vLLM / 各类模型网关） |
| 语言 | 单语 | **中英双语**：每份讲义和文档都有等价的英文版（`*.en.md`） |
## ⚖️ 先说清楚：每一层做到了什么
整个项目只有**一套** async 实现，从第 02 课用到第 31 课；往上每一层只是把"状态存在哪里"换成更强的组件，接口不变：
| 层 | 是什么 | 做到了什么（都有测试证明） | 局限（实话） |
|---|---|---|---|
| `agentkit/` 核心 | async Agent 运行时：主循环、工具、上下文、编排、可靠性、安全、追踪、评估 | 一个进程里同时推进成百上千个会话；只读工具并行；真取消（断开即停）、超时、舱壁、流式；子进程硬超时 | 状态默认在内存或本地文件；注入检测和 PII 脱敏是正则 |
| `agentkit/distributed/` | 多进程执行：租约队列、fence 检查点、跨进程幂等 / 限流 / 并发槽位 / 熔断器、worker 进程、`WorkerPool` | 真实进程上的 kill -9 接手（副作用不重复）、SIGSTOP 僵尸醒来后写不进去、SIGTERM 优雅停机、多进程抢任务不重复（第 12–13 课） | 基于 SQLite，只能在一台机器上；同一时刻一个写者 |
| `agentkit/contrib/` | 成熟组件适配器：Postgres、Redis、Temporal、OpenTelemetry、LiteLLM、Cedar、护栏分类器 | 同一套队列 / 检查点接口换成 Postgres 就能多机共享；真实 TCP 网络分区下旧 worker 被 fence 拒绝（第 26–29 课） | 用嵌入式 Postgres、fakeredis、Temporal 开发服务器测试；Redis 主从切换、集群分片、多区域没有实测 |
| `production/` | 把上面串起来的参考服务：API、worker、压测、故障注入、docker-compose、Kubernetes | 压测与故障注入数字见第 31 课 | 参考实现，不是托管产品；本机没有 Docker，部署配置没有实际启动过 |
逐模块"做到了什么 → 还差什么 → 换成什么 → 怎么迁移"，见 📋 生产就绪指南。
## 🗺 你将亲手造出的系统
 [code] 
用 `agentkit` 组装一个企业级 Agent 只需要这样（每一个参数背后都是一节课）：
 [code] 
真实运行输出示例（`python -m agentkit.chat`，一轮里模型并行调用了两个工具）：
 [code] 
一个进程扛不住、或者进程会崩溃时，让多个 worker 进程从同一个持久化队列里领任务（第 12–13 课）：
 [code] 
 [code] 
 [code] 
多台机器时只换 `--queue postgresql://...`，其余不变（第 26 课）。再往上换成成熟组件，**接口不变**（这段代码在嵌入式 Postgres、fakeredis 和真实模型上跑通过）：
 [code] 
## 🚀 快速开始
 [code] 
编辑 `.env`，填入任意 OpenAI 兼容接口：
 [code] 
 [code] 
> 💡 **没有 API key？** 所有 demo 都支持 `--offline`（用剧本模型 `ScriptedLLM` 运行），所有练习和测试都是离线的。你可以零成本学完整个课程。
## 📚 学习路线
课程分四部分：**第一部分学会"怎么造"，第二部分学会"企业里出了问题怎么选方案"，第三部分学会"怎么让 Agent 持续变好"，第四部分学会"怎么用成熟组件真正上生产"**