用 SDK 创建第一个 Agent

从最小 createAgentSession 到只读工具集，建立一个可释放、可观察的嵌入式 Pi session。

前提

本章 API 对应 @earendil-works/pi-coding-agent@0.82.1。需要 Node.js >=22.19.0，并提前配置模型凭据。

最小 session

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

const { session } = await createAgentSession();

try {
  session.subscribe((event) => {
    if (
      event.type === "message_update" &&
      event.assistantMessageEvent.type === "text_delta"
    ) {
      process.stdout.write(event.assistantMessageEvent.delta);
    }
  });

  await session.prompt("Explain this repository's test strategy.");
} finally {
  session.dispose();
}

逐行理解

1. createAgentSession() 发现当前目录与 ~/.pi/agent 中的 settings、context、resources 和模型配置。
2. subscribe() 观察的是 AgentSession events；示例只消费 text delta。
3. prompt() 直到 run 完成才 resolve，但 streaming 事件会在过程中持续到达。
4. dispose() 释放 extension/runtime 服务；应放在 finally。

做成只读 session

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

const { session } = await createAgentSession({
  tools: ["read", "grep", "find", "ls"],
  sessionManager: SessionManager.inMemory(),
});

这里的“只读”表示没有注册内建 write/edit/bash，且不持久保存 session。若加载了拥有文件权限的 extension，这个描述就不再完整。

练习

• 记录 agent_start 到 agent_end 的总时长。
• 把每个 tool_execution_start/end 转成结构化 trace。
• 使用 SessionManager.inMemory() 与持久 session 各运行一次，比较恢复行为。
• 在 30 秒后调用 abort，并确认 UI/调用方能区分 aborted 与 error。