LLM
模型本身。它接收消息和工具描述，然后输出文本、thinking 或 toolCall。
本章一句话
agent 的关键不是“模型更聪明”，而是模型、工具、上下文和循环被组织到了一起。
核心定义
agent 是一个循环：把上下文交给模型，模型可能返回文本，也可能返回 toolCall；本地执行工具后把 toolResult 回填上下文，再让模型继续推理，直到没有下一步动作。
先懂概念
后面的源码会反复出现这些词。先把边界分清，比一开始追函数更重要。
Context
本轮要发给 provider 的输入包，核心是 systemPrompt、messages、tools。
toolCall
模型提出的工具调用请求。它不是执行结果，也不代表工具已经跑完。
toolResult
本地工具执行后的观察结果。必须回填上下文，模型下一轮才知道发生了什么。
agent loop
反复执行模型生成、工具调用、工具结果回填和继续生成的核心循环。
session
长期历史存储。保存 user、assistant、toolResult、分支和压缩边界。
普通聊天 vs agent
普通聊天只有一次模型回答；agent 多了本地动作、观察结果和下一轮推理。
模式
链路
关键区别
普通聊天
user -> model -> assistant text模型直接给答案，没有本地工具执行和结果回填。
agent
user -> model -> toolCall -> toolResult -> model -> final text模型可以请求工具，本地执行后把观察结果交回模型继续推理。
agent loop 怎么跑
这张图是后面 01 到 07 的总主线：所有章节都在解释这条链路里的某个环节。
01用户输入一句自然语言请求。
02AgentSession会话层预处理。
03Agent loop组织模型和工具循环。
04模型返回 text 或 toolCall。
05本地工具执行 read、edit、bash 等动作。
06toolResult工具返回观察结果。
07回填上下文，再继续下一轮直到没有工具、steering 或 follow-up。
最小伪代码
while (true) {
const assistant = await model(context);
context.messages.push(assistant);
if (!assistant.toolCalls.length) break;
const results = await executeTools(assistant.toolCalls);
context.messages.push(...results);
}
读源码时记住
Pi 真实实现比这段伪代码复杂：它还要处理 streaming、hooks、steering、follow-up、abort、terminate、并行/顺序工具和 session 持久化。
Pi 三层结构
读源码不要从所有文件一起看。先按模型层、agent runtime、coding-agent 产品层分开。
01packages/aiContext、provider、stream event、tool calling payload。
02packages/agentAgent、agent loop、messages、tools、toolResult 回填。
03packages/coding-agentCLI、AgentSession、默认工具、session、skills、extensions。
04packages/tui终端 UI 渲染。第一遍可以先不深入。
05HTML 教程第一遍跟学主线，建立概念和流程。
06Markdown notes第二遍深入源码，补函数和类型细节。
07小实验用运行结果验证你对流程的解释。
常见误解
这些误解后面读 01、02、03、04 时最容易反复出现。
toolCall 等于工具执行了？
不对。toolCall 是模型请求。本地 agent loop 才负责校验参数、鉴权、执行工具。
toolResult 只是日志？
不对。toolResult 是模型下一轮推理需要的上下文。UI 可以展示它，但核心作用是喂回模型。
Context 就是完整 session？
不对。session 是历史存储；Context 是本轮要交给模型的输入视图。
AgentSession 和 Agent 是一回事？
不对。AgentSession 是产品会话层，Agent 是运行控制器，agent loop 是执行引擎。
自测题
不用背术语，能用自己的话讲清这些问题就够了。
先回答
- 为什么 agent 不是普通聊天？
- toolCall 和 toolResult 的区别是什么？
- 为什么工具结果必须回填上下文？
- Context 和 session 的区别是什么？
参考答案方向
- agent 有模型、工具、观察结果和循环状态。
- toolCall 是请求，toolResult 是本地执行结果。
- 模型下一轮必须看到工具结果才能继续推理。
- Context 是模型输入视图，session 是长期历史。
下一章怎么接
00 章只建立概念。01 章开始用真实 Pi 输出验证这条链路。
本章完成度
- 能说出 agent 为什么不只是“问模型一次”。
- 能区分 toolCall 和 toolResult。
- 能解释为什么工具结果要回到上下文。
- 能按三层结构定位 Pi 源码。
进入 01
下一章先跑一次 Pi，观察一次 prompt 如何进入 AgentSession、Agent 和 runAgentLoop()。