PI agent
学习指南
从零看懂一个生产级 AI Agent 的运行时底座——不是玩具框架， 而是真正能上线的 Agent 工程参考实现。十章导读， 带你拆解 Agent Loop、工具管道、上下文工程与会话树的每一处设计权衡。
WHY PI
为什么值得学 Pi
大多数 Agent 教程止步于调 API。Pi 把“能上线”的完整答案写在源码里： 六项核心能力，每一项都对应一个真实工程痛点。
Agent Loop
模型循环调用、明确的停止条件信号灯、层层设防的错误处理——引擎的每一圈都兜得住。
工具系统
定义 / 注册 / 拦截 / 执行 / 回收的五步管道，让模型的每一次“动手”都在管控之内。
消息系统
内部用自由联合类型充分表达，跨边界时统一翻译成标准 Message——内富外严。
事件驱动
发布订阅解耦 UI 与运行时，“emit 即 await”的同步屏障保证时序可预测。
会话管理
Session Tree 让对话可存储、可恢复、可分叉，回退与分支都是数据结构的自然能力。
扩展机制
工厂函数 + 事件总线，新能力以插件方式挂进来，核心代码零改动。
WHO SHOULD LEARN
LEARNING PATH
四段递进的学习路径
阶段 ① · 第 1 – 2 章
建立全局观
先看懂 Pi 的整体样貌与三层架构骨骼，知道每个包为什么存在、依赖流向何方。
阶段 ② · 第 3 – 5 章
拆解运行时主循环
深入 Agent Loop、多模型统一调用与工具管道——Agent 真正“干活”的核心三段。
阶段 ③ · 第 6 – 7 章
拆解支撑系统
消息系统与事件驱动：记忆如何组织传递，各模块如何有序通信。
阶段 ④ · 第 8 – 10 章
长生对话的工程问题
上下文工程、压缩算法与会话树——让 Agent 连续工作几小时也不丢记忆。
10 CHAPTERS
十章指南
每章一篇精华导读，配原创图解与代码示意。点击卡片进入完整章节。
INTERVIEW 30 Q&A
AI Agent 面试题：30 问 30 答合集
十章的面试问答全部汇总在一页，自测、速查、面试前抱佛脚都好用。
Pi-Agent 总览：一个框架的三重身份
为什么说"做减法"本身就是一项功能——编码工具、学习教材与开发 SDK
三层架构：Pi-Agent 项目的骨骼
包怎么分工、依赖方向为什么不能反向、类型如何层层递进
Agent Loop：让模型转动起来的引擎
循环为什么存在、靠什么信号决定停转、内核与叠加怎么分层
模型调用：一行代码驾驭多个模型
翻译器架构如何把 30+ 家供应商的方言收敛成一条统一事件流
工具系统：Agent 的手脚是怎么被管住的
三层工具类型、五步执行管道，以及"错误即消息"的防线设计
消息系统：Agent 的记忆如何组织与传递
内富外严的两层消息设计——自定义消息自由表达，LLM 边界统一翻译
事件驱动：Agent 的神经系统
10 种事件、4 层嵌套，以及"emit 必须 await"的同步屏障设计
上下文工程：让有限窗口装下无限对话
输入侧做减法与加法，历史侧做压缩与摘要——四层互补的防护体系
上下文压缩：当对话太长怎么办
阈值触发、切割点算法、结构化摘要——把 50 轮对话压成一段笔记
会话管理：对话的存储、恢复与分叉
一棵 append-only 的树，让回退与分支只是移动指针而非删除数据
HANDS-ON LAB · 新专栏
动手做一个 mini Agent：6 关从零写出自己的 Agent
零依赖、零框架、纯 Node.js。从一次裸 fetch 开始，逐关加上工具调用、流式事件、上下文压缩， 每关结尾对照 Pi 源码验收——理论给地图，动手给肌肉记忆。配套代码已开源（pi-mini-agent），6 关全部实测可跑。
ABOUT PI
关于 Pi 项目
Pi 是一个开源的生产级 AI Agent 运行时底座（MIT License）。四个核心包各司其职， 组合出一个“模型自由、界面自由、扩展自由”的 Agent 工程参考实现。
pi-ai
统一多模型 LLM API。一套中立格式驾驭十几家厂商，翻译器架构把协议差异关在边界层。
pi-agent-core
Agent 运行时核心。循环引擎、工具管道、事件总线、会话树都在这里，与 UI 和模型彻底解耦。
pi-coding-agent
交互式编程 CLI。基于核心运行时构建的完整产品形态，开箱即用的终端编程助手。
pi-tui
独立的终端 UI 层。负责渲染与交互，可替换、可裁剪，展示“表现层”该有的克制。