Demo：SDK 最小调用

前六层的 Demo 都是零依赖原理复现。这一节我们用 @pi/coding-agent 的真实 SDK，演示"官方推荐的最小用法"。它需要仓库已构建（npm run build）才能运行 —— 是本书唯一一个"真实依赖"的 Demo，因为它依赖的是最顶层的真实实现。

代码

// sdk-demo.ts —— 在 pi 仓库根目录构建后运行（见下方"运行"）
// 需要: @earendil-works/pi-coding-agent 已可用（npm run build 后）

import { createAgentSession } from "@earendil-works/pi-coding-agent";

async function main() {
	// 1. 装配一个最小会话：只给 read 工具，用假模型避免消耗真实 API
	const { session } = await createAgentSession({
		cwd: process.cwd(),
		tools: ["read"],          // 只启用 read
		// modelRuntime 默认会找已配置的模型；也可显式传 model
	});

	// 2. 订阅会话事件（观察 Agent 在做什么）
	session.agent.subscribe((event) => {
		switch (event.type) {
			case "agent_start":
				console.log("== 会话开始 ==");
				break;
			case "message_end":
				console.log(`[${event.message.role}]`, event.message.content);
				break;
			case "tool_execution_start":
				console.log(`  → 调用工具: ${event.toolName}`);
				break;
			case "agent_end":
				console.log("== 会话结束 ==");
				break;
		}
	});

	// 3. 提一个问题
	await session.prompt("用一句话说明你在做什么");
	await session.agent.waitForIdle();

	// 4. 读取最终状态
	console.log("\ntranscript 条数:", session.agent.state.messages.length);
}

main();

运行

把上面的代码存成 sdk-demo.ts，在 pi 仓库根目录构建后运行：

# 在 pi 仓库根目录
npm run build                          # 先构建所有包，让 workspace 依赖可用
bun sdk-demo.ts

首次运行若未配置模型，createAgentSession 会引导你登录一个 Provider。也可以用环境变量或 ~/.pi/agent/auth.json 预置。

这背后发生了什么

createAgentSession()（6.1）一行就完成了：

解析 cwd → 创建 ModelRuntime → 创建 SessionManager/SettingsManager
→ 解析模型 → new Agent(...) + AgentSession(...)

session.prompt() 则进入 @pi/agent-core 的循环（2.1）：

• 把上下文交给 Agent 的 streamFn（由 ModelRuntime.streamSimple 提供）。
• 循环消费事件，通过 session.agent.subscribe 我们能观察到每一步。
• 模型若调用 read 工具，工具结果回填，循环继续。

对应到源码

调用	真实源码
createAgentSession	packages/coding-agent/src/core/sdk.ts:169
new Agent(...)	packages/coding-agent/src/core/sdk.ts:294
session.agent.subscribe	packages/agent/src/agent.ts:250
prompt → 循环	packages/agent/src/agent-loop.ts:95

小结

• 顶层 SDK 让"跑一个 Agent"变成一行 createAgentSession。
• 通过 session.agent.subscribe 能观察到完整生命周期。
• prompt + waitForIdle 是程序化驱动 Agent 的标准姿势。

TIP

若你不想配置真实模型，可以结合 @pi/ai 的 fauxProvider（1.3）注入一个假模型，让会话完全离线可跑。

最后一章，把全书串起来：从零手写一个 Agent。