文件概览

packages/agent/src/ ├── agent-loop.ts # 无状态循环引擎（~700 行，纯函数） ├── agent.ts # 有状态封装层（~540 行，Agent 类） ├── types.ts # 类型定义（~400 行） ├── proxy.ts # HTTP 代理（~320 行） ├── index.ts # 导出入口（~8 行） ├── agent-learn.ts # 学习相关 ├── agent-loop-learn.ts └── README.md

核心分界线：

Pi-Architecture: Agent

Fri, 29 May 2026 00:00:00 +0000

Pi Agent 包架构

packages/agent/src/ 实现了 Pi 框架中的 Agent 运行时，用于构建工具增强型 LLM 对话代理（Tool-Augmented LLM Agent）。

整个包由五个模块组成：

文件	职责	行数
`types.ts`	类型定义层	~400
`agent-loop.ts`	无状态循环引擎	~700
`agent.ts`	有状态封装层	~540
`proxy.ts`	代理流式函数	~320
`index.ts`	导出入口	8

架构总览

graph TD App[外部应用] subgraph "Agent 包" Index[index.ts
导出入口] subgraph "类型系统" Types[types.ts
AgentMessage / AgentEvent
AgentLoopConfig / AgentTool] end subgraph "管理层 agent.ts" Agent[Agent 类
状态管理 / 队列 / 并发 / 事件] Queue[PendingMessageQueue
steering / follow-up 队列] State[MutableAgentState
状态归约] end subgraph "引擎层 agent-loop.ts" Engine[LoopEngine
runAgentLoop / runLoop] LLMCall[streamAssistantResponse
LLM 调用] ToolExec[executeToolCalls
工具执行] end subgraph "HTTP 代理 proxy.ts" Proxy[streamProxy
代理流式函数] end end subgraph "LLM 核心库 @earendil-works/pi-ai" AI[streamSimple / Model
Message / Tool] end App --> Agent Agent --> Engine Agent --> Queue Agent --> State Engine --> LLMCall Engine --> ToolExec LLMCall --> AI Proxy -- 替代 streamFn --> Agent Agent -.-> Types Engine -.-> Types

分层设计

无状态引擎 vs 有状态封装

Agent 包的核心设计思想是将引擎逻辑与状态管理分离：

Agent on Yukari's Blog

Pi Agent 包源码逐行解读 — agent-loop.ts & agent.ts