Pi Agent 原理

Appearance

快速开始 ​

本教程不需要安装 pi 本体。仓库自带一个零依赖的工程化复现项目 pi-principles/（目录结构、依赖方向、模块边界都镜像真实的 pi），你只需要一个 Bun 运行时就能跑起真实的 Agent。分两步：先跑起来，再理解"最小可复现的 Agent"长什么样。

一步：准备运行环境 ​

只装一个 Bun（原生支持直接执行 TypeScript，无需编译）：

bash
npm install -g bun
bun --version    # 验证

二步：跑一个真实 Agent ​

进入 pi-principles/ 直接运行，无需任何安装：

bash
cd pi-principles

bun cli.ts chat "你好"                    # 单轮流式对话
bun cli.ts agent "请计算 123 + 456"        # 带 calculator 工具
bun cli.ts app "请计算 3 + 4"              # 全打通：server ⇄ client ⇄ tui
bun cli.ts repl                           # 交互式多轮对话（/exit 退出，/reset 重置）
  • 有 .env（OPENAI_BASE_URL / OPENAI_API_KEY / OPENAI_MODEL）→ 走真实 OpenAI Responses API，支持 DeepSeek、Moonshot、Kimi 等任何走该协议的厂商。
  • 无 .env → 自动回退离线假模型，零成本体验完整流程。

三步：最小的"程序化 Agent" ​

pi-principles/src/ 导出与 pi 同构的 SDK，你可以用几行代码创建并驱动一个完整会话：

ts
// minimal.ts（放在 pi-principles/ 下）
import { MiniAgent } from "./src/agent/agent.ts";
import { createDeciderStreamFn } from "./src/agent/decider.ts";

const agent = new MiniAgent({
  streamFn: createDeciderStreamFn(), // 离线假模型；配 .env 后可换真实模型
  systemPrompt: "你是一个只会做加法的教学 Agent",
  tools: [
    {
      name: "calculator",
      description: "两数相加",
      execute: ({ a, b }) => `= ${Number(a) + Number(b)}`,
    },
  ],
});

await agent.prompt("计算 2 + 3");
console.log(agent.state.messages.at(-1)?.content);
bash
bun minimal.ts

MiniAgent 对应 pi 的 Agent 实例（来自 @pi/agent-core），只依赖 StreamFn 契约，不关心背后是真模型还是假模型——这正是 pi 分层设计的意义。

想体验完整的 pi？ ​

bash
git clone https://github.com/earendil-works/pi.git
cd pi
npm install --ignore-scripts    # 按项目规范，不执行生命周期脚本
npm run build                   # 刷新模型目录并构建所有包
./pi-test.sh                    # 从源码运行 pi（可在任意目录执行）
pi "用一句话解释什么是 Agent"

也可以用 npm 全局安装发布版：npm install -g @earendil-works/pi-coding-agent。这不是本教程的前置条件，只是对照实验。

下一步 ​

你已经见过"上层"长什么样了。现在回到最底层，从 @pi/ai 的统一消息模型开始，逐层向上。