Pi Coding Agent 除终端交互外，还提供 SDK 与 RPC，使其他程序能够提交任务、接收进度和管理会话。SDK 适合在 Node.js 应用内直接使用 Pi；RPC 适合把 Pi 作为独立子进程，由另一种语言或界面控制。
以下按 2026 年 9 月 17 日官方文档说明。示例用于解释接口，不代表已经在某个业务系统中运行验证。
SDK：进程内使用
官方 SDK 随 @earendil-works/pi-coding-agent 包提供。其主要入口 createAgentSession() 创建会话，调用方可以选择模型和工具、订阅事件，再提交提示。
简化的使用步骤如下：
- 配置可用的模型访问方式。
- 创建会话并指定所需工具。
- 订阅事件，将文字增量或工具进度发送给界面。
- 调用
session.prompt()提交任务。 - 处理结束、失败、取消与会话保存。
会话可以使用内存存储或持久化存储。资源加载器还负责组织扩展、Skills 和项目上下文。创建会话并不自动提供业务系统的用户鉴权和资源授权，这些仍属于宿主应用的职责。
RPC：通过子进程通信
RPC 模式 使用标准输入和标准输出传递 JSONL，而不是默认启动一个 HTTP 服务。宿主程序先启动：
pi --mode rpc --no-session
在已配置模型访问权限的前提下，可以向该进程的标准输入写入一行命令，例如：
{"id":"explain-entry","type":"prompt","message":"解释当前项目的程序入口"}
其中 id 用于关联命令响应，--no-session 表示此次不持久化会话。程序需要持续读取标准输出，解析响应和后续事件。
协议使用换行符分隔 JSON 记录。实现客户端时应按协议处理数据块拼接与换行，不能假设一次读取恰好得到一条完整消息。
命令受理不等于任务完成
RPC 对提示命令返回成功，表示请求已被接受、排队或立即处理；模型执行仍可能在后续事件中继续，且之后仍可能失败。
因此，界面至少需要区分“已受理”“运行中”和“已结束及其结果”。如果只根据命令响应显示任务成功，用户可能在工具还没执行时就看到错误的完成状态。应结合当前版本的运行事件和错误信息判断执行状态。
SDK、RPC 与 JSON 输出怎样选择
| 方式 | 交互形态 | 适合的场景 |
|---|---|---|
| SDK | 同一 Node.js 进程内调用对象和接口 | 深度集成、自定义工具与状态管理 |
| RPC | 外部程序双向控制 Pi 子进程 | 跨语言接入、桌面或编辑器界面 |
| JSON 事件输出 | 一次运行输出结构化事件 | 脚本处理、日志采集和批处理 |
JSON 事件模式适合程序读取一次任务的输出；RPC 则提供运行期间继续发送控制命令的通信方式。两者都可能输出 JSON 行，但用途和交互协议不同。
集成示例与应用边界
例如，一个代码检查界面可以向后端提交任务，由后端选择项目目录、启动 Pi，再把文字和工具进度推送到浏览器。用户看到的是网页，Agent 实际执行仍发生在后端环境中。
在这种设计里，项目目录是否属于当前用户、哪些工具允许执行、进程超时后如何清理、外部写入如何获得授权，都需要宿主系统明确处理。RPC 的进程分离只是集成方式，本身不构成执行沙箱；相关权限边界见Pi 安全说明。