先观察一次完整的 Agent 运行

#你将得到什么

进入本章时，你还没有 Agent，也不需要先理解所有 TypeScript。我们先观察最终成品的一次离线运行：用户要求读取项目说明，模型请求工具，环境返回结果，模型再给出回答。你将得到一张能贯穿全书的地图，并学会用事件轨迹判断系统是否真的闭环。

本章只增加一种复杂性：把“Agent 会思考”改写成可观察的数据流。我们暂时不实现模型和工具。完成后你会观察 packages/pi-course/src/demo/prologue.ts 中的教学 checkpoint；页面随附的 workshop/src/demo/prologue.ts 是全书最终参考实现，不是第一次练习要从空白复刻的答案。你将能解释一条固定轨迹中的每个所有者，并指出一条不能破坏的不变量：

每一个已经作为 assistant content 进入 transcript 的 tool call，最终都必须有一个相同 toolCallId 的 tool result。

若想恢复本章起点，不需要回滚代码；重新运行固定脚本即可。它不访问网络，也不修改工作区。

#先建立全景

假设用户说：“读取 README.md，用一句话告诉我这个项目做什么。”离线演示产生下面的稳定轨迹：

01 user_message       "读取 README.md，并概括项目"
02 model_start
03 assistant_message  stopReason=toolUse
   toolCall           id=call_1 name=read arguments={"path":"README.md"}
04 tool_start         id=call_1
05 tool_result        id=call_1 isError=false content="# tiny-pi ..."
06 model_start
07 assistant_message  stopReason=stop
   text               "这是一个用于学习 Agent 内核的 TypeScript 项目。"

model_start 与 tool_start 是为了观察运行过程而记录的运行轨迹事件，不是稍后会持久化的 AgentMessage。Canonical AgentMessage 只保存 user、完成的 assistant 和 tool result 这些对下一轮仍有意义的事实。现在不需要理解 AgentContext、EventStream、provider 或 Usage 的实现；它们只是地图上的站名，会在后续章节各自出现一次。

这里没有神秘的“自主性”。Agent 只是反复回答三个问题：当前事实是什么、模型下一步请求什么、这个请求应当由谁执行。模型拥有生成内容的责任，却不拥有文件系统；工具拥有环境副作用，却不能决定下一轮提示；循环拥有顺序和终止责任，却不应理解 read 的业务细节。序章播放的是固定 fixture：tool_result 的内容已经写在轨迹里，不执行真实的文件读取，也不会改动你的工作区。

阅读轨迹时要区分“系统已经观察到的事实”和“我们根据最终答案做出的猜测”。第 03 行只能证明模型请求读取；第 04 行只能证明执行开始；直到第 05 行出现，读取结果才成为可供下一轮使用的环境事实。若只看第 07 行，我们甚至无法排除模型凭训练记忆猜中答案。后续测试因此不会只断言最后一句字符串，还会检查中间消息、配对键和 stop reason。这种检查方式会贯穿全书：先找首次偏差，再讨论最终表现。

#用消息而不是界面描述事实

终端会把事件渲染成几行文字，但界面不是事实源。后续章节会建立统一消息语言；现在先看它的最小形状：

type AgentMessage =
  | { role: "user"; content: TextContent[]; timestamp: number }
  | {
      role: "assistant";
      content: (TextContent | ToolCall)[];
      provider: string;
      model: string;
      usage: Usage;
      stopReason: "stop" | "length" | "toolUse" | "error" | "aborted";
      errorMessage?: string;
      timestamp: number;
    }
  | {
      role: "toolResult";
      toolCallId: string;
      toolName: string;
      content: TextContent[];
      details?: unknown;
      isError: boolean;
      timestamp: number;
    };

同一份 AgentMessage[] 可以被终端打印、写入 JSONL、变成下一次模型请求，或在网页中折叠显示。若反过来把彩色终端字符串当历史，颜色、换行和日志前缀就会混入语义，恢复会话时也无法可靠找到 tool call。

#从终点倒推我们要造的部件

完整运行可以压缩成一条重复路径：

用户目标
  → AgentContext
  → Model.stream()
  → EventStream<ModelEvent, AssistantMessage>
  → tool call
  → 工具执行与 tool result
  → 更新 AgentContext
  → 下一次 Model.stream()
  → stop

第一部会造 AgentContext、消息 IR、EventStream、ScriptedModel 和真实 provider 边界；第二部才闭合工具与循环；第三部让运行可取消、可保存、可恢复；第四部再处理扩展、产品入口和系统评测。这个顺序不是仓库导览，而是每次只让一个未知量进入系统。

注意这条主链会重复出现，而不是一章讲完就被丢弃。第一次它只是固定 trace；加入 EventStream 后能观察时间；加入消息 IR 后能保存语义；加入工具后才真正接触环境；加入 session 后可以恢复与分支。每一次重走同一条路，旧部件都要在新约束下再次证明自己。你最终记住的应当是稳定因果关系，而不是某个版本的文件树。

#故意把它弄坏

把工具错误伪装成成功文本，是最危险的“看起来还能跑”。例如读取不存在的文件时，下面这条消息保留了配对关系，也保留了失败事实：

{
  "role": "toolResult",
  "toolCallId": "call_1",
  "toolName": "read",
  "content": [{ "type": "text", "text": "ENOENT: README.md" }],
  "isError": true
}

#本章验收

#可选迁移练习

#小结

Agent 的最小本质不是聊天界面，而是由类型化事实连接起来的反馈回路。消息保存语义，模型提出下一步，工具接触环境，循环维护顺序。序章只让你看见终点；从下一章开始，我们会逐件造出它，并让每个部件都能被测试、破坏和恢复。