Pi 的架构与 Agent Loop

Pi Coding Agent 的架构将模型接入、Agent 循环和编码应用分成不同职责。所谓 Agent Loop，是程序反复请求模型、执行模型提出的工具调用、再把结果交回模型的过程。它让一次用户请求可以包含多步观察与操作。

以下按 2026 年 9 月 17 日可查的官方源码仓库与组件文档说明，具体接口会随版本变化。

主要组件如何分工

其中，pi-ai 官方说明介绍了跨提供商的接口与工具调用支持。统一接口减少了调用方需要处理的差异，但不意味着不同模型的上下文容量、输出行为或任务能力完全相同。

一轮循环发生什么

可把常见执行过程概括为：

1. 程序整理用户消息、已有历史和工具定义。
2. 模型返回文字，或提出带参数的工具调用。
3. 运行时执行对应工具，收集成功结果或错误信息。
4. 工具结果进入消息上下文，模型据此生成下一轮响应。
5. 在正常完成、取消、错误或程序控制的停止条件下结束运行。

Agent Core 文档区分了一次运行和其中的多轮交互：一轮包含一次模型响应及其工具执行，一次用户请求可以经历多轮。消息、轮次与工具执行事件让上层界面展示中间进度。

用一次修复任务理解分工

假设用户说“修复排序函数对空输入的处理”。模型可能先选择读文件，再选择修改代码，随后执行测试。这里存在三个不同的判断：

• 模型决定下一步想做什么。
• 运行时决定如何执行已注册工具并整理返回值。
• 测试程序依据断言给出通过或失败结果。

测试失败并不是循环本身失效：错误输出可以成为下一轮输入。另一方面，循环最终停止也不自动证明需求已经满足，仍需查看文件差异和测试证据。

工具为什么不只是函数名

工具向模型说明用途和参数，同时在程序侧提供执行实现。两者必须一致：如果描述说“查询项目状态”，实现却修改项目，模型将难以可靠地选择动作。

编码工具通常围绕读取、写入、局部修改和命令执行组织。模型生成的工具调用要经过宿主程序才能影响环境；模型文本本身不会直接改写磁盘文件。

从源码学习什么

阅读时可以沿“输入消息 → 模型响应 → 工具执行 → 结果回填”追踪一次任务，再观察异常和中断怎样改变这个过程。另一个值得区分的问题是“应用保存了什么”与“模型这次收到了什么”：Agent Core 提供上下文转换接口，应用级消息不一定原样发送给模型。

Pi Coding Agent 的会话层还组织历史、压缩和资源加载。理解这些职责的划分，有助于避免把终端 UI、模型 API 和 Agent 循环当成同一个模块。关于会话层对外暴露的能力，可参阅官方 SDK 文档。