PI 框架（PI Framework）是 Anthropic 推出的用于构建 AI 编程代理的开源框架。本文将通过 15 个实战 demo，带你快速掌握 PI 框架的核心用法。

前言

在 AI 编程时代，如何构建一个能够「记住对话上下文」「支持分支探索」「具备持久化能力」的编程代理？Anthropic 推出的 PI 框架给出了答案。

最近我通过 15 个 demo 系统学习了 PI 框架的核心功能，特此整理成这篇入门教程，帮助想了解 PI 框架的开发者快速上手。

环境准备

# 安装 PI 框架
npm install @anthropic-ai/claude-agent-sdk

# 或使用 pnpm
pnpm add @anthropic-ai/claude-agent-sdk

确保你有一个 Anthropic API Key。

第一个例子：最小示例

让我们从最简单的例子开始：

import { claude } from "@anthropic-ai/claude-agent-sdk";

const agent = claude({
  apiKey: process.env.ANTHROPIC_API_KEY!,
});

const session = await agent.session();

const result = await session.message({
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(result.messages.at(-1)?.content);

这就是一个完整的 PI Agent，接收用户消息并返回响应。但这只是冰山一角。

核心概念

1. Agent（代理）

Agent 是与 LLM 交互的核心对象，负责发送消息、接收事件、管理状态。

const agent = claude({ apiKey: "your-key" });

2. Session（会话）

Session 是对话的容器，保存消息历史。Session 是状态ful的，多次交互会共享上下文。

const session = await agent.session();
await session.message({ messages: [{ role: "user", content: "Hi" }] });
await session.message({ messages: [{ role: "user", content: "What did I say?" }] });

3. Tool（工具）

Agent 可以配备工具来执行代码、读取文件等操作：

const agent = claude({
  apiKey: "your-key",
  tools: [
    {
      name: "Bash",
      description: "Run shell commands",
      parameters: { type: "object", properties: { command: { type: "string" } } },
      handler: async ({ command }) => ({ output: "Command executed" }),
    },
  ],
});

15 个 Demo 详解

以下是 15 个 demo 的核心要点总结，帮助你快速了解 PI 框架的全貌：

基础篇

Demo	文件	核心内容
01	minimal.mts	最简单的 Agent + Session 示例
02	agent-core.mts	官方 Tool 的使用
03	coding-agent.mts	完整的 Coding Agent 实现

Session 持久化

Demo	文件	核心内容
04	persistent-session.mts	FileSession：将会话保存到文件
05	session-management.mts	SessionManager：创建、打开、列出会话

Session 进阶功能

Demo	文件	核心内容
06	session-fork.mts	Fork：将会话分叉到另一个项目
07	session-branch.mts	Branch：在会话内创建分支
08	session-parent.mts	Parent Session：追踪会话血缘
09	session-inherit.mts	手动继承父会话上下文

高级功能

Demo	文件	核心内容
10	custom-tool-factory.mts	自定义工具工厂
11	extensions.mts	Extensions 系统
12	compaction.mts	Context 压缩
13	steering.mts	Steering：干预 Agent 行为
14	thinking-levels.mts	Thinking 级别控制
15	auth-model-registry.mts	AuthStorage 和 ModelRegistry

几个关键点

Session Fork

PI 框架支持将会话「分叉」到另一个项目。这对于：

• 在多个项目中复用同一个调试会话
• 基于某个工作状态开新项目

非常有用。

const forked = await session.fork({ cwd: "/path/to/new-project" });

Session Branch

在同一个项目中，可以创建多个分支，探索不同的解决方案：

const branch = await session.branch({ description: "Try another approach" });

Steering

Steering 允许你在 Agent 运行过程中「干预」其行为：

• steer(): 引导 Agent 走向特定方向
• followUp(): 在完成后追加新任务

Context Compaction

当对话变长时，PI 框架支持压缩上下文，保留关键信息的同时减少 token 消耗。

总结

PI 框架为构建 AI 编程代理提供了完整的解决方案：

• ✅ 简洁的 API 设计
• ✅ 强大的 Session 管理（持久化、分叉、分支）
• ✅ 灵活的工具系统
• ✅ 支持上下文压缩和行为干预

如果你想深入了解每个 demo 的具体实现，可以查看我的 GitHub 仓库：https://github.com/xiayongchao/pi-demo

参考链接

• PI 框架文档：https://docs.anthropic.com/en/docs/claude-code/overview
• Demo 源码：https://github.com/xiayongchao/pi-demo
• Anthropic API：https://www.anthropic.com/api

---

本文由 PI 框架学习过程中整理，欢迎交流讨论。