Pi Agent SDK 入门：配置模型，跑通第一个流式 Agent

我是安徽最忧郁程序员无隅前言想把 Agent 接进自己的应用第一步不是研究所有扩展接口而是确认三件事程序能找到模型、能发出问题、能收到回复。本文用一个最小的 TypeScript 示例跑通这条链路并解释每个关键调用的职责。读完后你可以独立判断失败发生在环境、模型配置还是会话运行阶段。一、开始前明确要跑通什么1.1 SDK 帮我们处理哪部分工作如果直接调用模型接口应用还要自己组织对话消息、处理流式响应并在需要时接入工具。Pi Agent SDK 提供会话、模型运行环境和事件接口让应用可以从一次简单提问开始再逐步加入业务工具。这里的 SDK 指earendil-works/pi-coding-agent包提供的编程接口不是让读者操作 Pi 的交互式终端。它的官方 SDK 文档也把嵌入应用和构建自定义界面列为使用场景。本篇只做一个最小闭环选中可用模型 → 创建会话 → 发送问题 → 在终端打印回复。代码会显式关闭工具因此这里的 Agent 还不会读取文件或查询业务数据后续接入工具时再沿同一个会话入口扩展。1.2 准备条件与成功标志你需要 Node.js22.19.0 或更高版本、npm、一个 DeepSeek API Key以及能访问模型接口的网络。本文以earendil-works/pi-coding-agent0.84.3为例Node 要求见该版本的包配置。先在终端检查node--version成功时程序会先打印实际选中的模型标识再输出模型生成的文字。模型回复的具体措辞不固定看到一段回复才说明这次模型请求完成了。安装成功或模型列表非空都还不能证明接口调用已经成功。二、准备项目与模型2.1 创建项目并安装依赖在一个空目录中执行下面的命令。typemodule让项目按 ESM 模块方式运行tsx用来直接执行.ts示例文件。mkdirpi-agent-democdpi-agent-demonpminit-ynpmpkgsettypemodulenpminstall--save-exact earendil-works/pi-coding-agent0.84.3npminstall--save-dev --save-exact tsx4.22.1这里固定版本是为了让安装结果与本文核对过的 SDK API 一致。版本更新时先对照对应版本的文档再调整示例。2.2 给内置 Provider 提供密钥这次使用 Pi 内置的 DeepSeek Provider。它在该版本中识别DEEPSEEK_API_KEY环境变量见Provider 源码。在Windows PowerShell中执行以下两行然后在提示符处输入自己的密钥$secureKeyRead-HostDeepSeek API Key-AsSecureString$env:DEEPSEEK_API_KEY [System.Net.NetworkCredential]::new(,$secureKey).Password环境变量只对当前终端会话及其启动的进程有效。后面的运行命令要在同一个终端执行不要把密钥写进示例代码、提交到仓库或放进文章截图。macOS / Linux 用户可按所用 Shell 的方式设置同名环境变量。看下图的两条输入Pi 已带有 DeepSeek 模型信息当前终端再提供凭据模型运行环境才能把相应模型列入可用列表。**列入可用列表不等于模型接口已调用成功。**这一步还没有发送问题真正的模型请求发生在后面的session.prompt()。原资料使用models.json配置 Provider。对这里选用的内置DeepSeek Provider先写这个文件会增加不必要的字段和排错点。需要接入自定义模型或兼容接口时再参考 Pi 的模型配置文档。三、运行第一个 Agent3.1 用一段代码完成提问和输出在项目根目录新建hello.ts写入下面的完整示例。代码先找出当前凭据可用的 DeepSeek 模型如果一个也没有就在创建会话前报出明确错误。import{createAgentSession,ModelRuntime,SessionManager,}fromearendil-works/pi-coding-agent;constmodelRuntimeawaitModelRuntime.create();constmodelsawaitmodelRuntime.getAvailable(deepseek);constmodelmodels[0];if(!model){thrownewError(未找到可用的 DeepSeek 模型请检查 DEEPSEEK_API_KEY);}const{session}awaitcreateAgentSession({model,modelRuntime,sessionManager:SessionManager.inMemory(),tools:[],});try{session.subscribe((event){if(event.typemessage_updateevent.assistantMessageEvent.typetext_delta){process.stdout.write(event.assistantMessageEvent.delta);}});console.log(使用模型${model.provider}/${model.id});process.stdout.write(回复);awaitsession.prompt(请用一句中文介绍你自己。);process.stdout.write(\n);}finally{session.dispose();}SessionManager.inMemory()让这个练习不创建持久化会话文件tools: []让示例只验证模型对话。try/finally保证提问失败时仍会释放会话。运行npx tsx hello.ts例如终端可能显示以下内容。这是示意输出不是本文实测结果模型 ID 和回复内容以你的运行结果为准。使用模型deepseek/deepseek-v4-flash 回复你好我是一个可以回答问题的助手。3.2 怎样判断失败发生在哪里先按图找到最早出现的现象再查下面的具体检查项。模型名已经打印出来只说明程序找到了可用配置还需要等到回复出现才能确认这次请求完成。看到的现象先检查什么node --version低于 22.19.0更新 Node.js 后重新打开终端提示找不到 SDK 包或tsx确认当前目录是pi-agent-demo并检查依赖是否安装完成提示“未找到可用的 DeepSeek 模型”确认设置密钥与运行程序用的是同一个终端检查环境变量名打印了模型名却没有正常回复模型“可用”只代表凭据已配置继续检查密钥有效性、网络连接和服务返回的错误流式输出是按事件逐段到达但短回复在终端里也可能看起来一次显示完。判断成功的重点是拿到模型回复而不是肉眼是否看到了“打字机速度”。四、看懂这段程序的调用链4.1 谁负责发问谁负责接收先看图中上下两排上排准备模型和会话下排才开始这次对话。箭头表示程序在这个示例中的调用与事件顺序。ModelRuntime.create()建立模型运行环境getAvailable(deepseek)选出当前凭据下可用的模型。createAgentSession()用它创建会话session.subscribe()先注册监听器等待文字事件。调用session.prompt()后模型生成的文字以message_update中的text_delta事件到达监听器再把每段文字写到终端。SDK 示例也使用这组事件字段。**prompt()负责启动并等待一次提问subscribe()负责观察过程中的事件。**两者连着同一个session因此监听器才能收到这次提问的输出。图中没有把“获取可用模型”画成联网验证它只筛选当前配置可用的模型真正的请求要到prompt()才发生。4.2 读懂代码只需认识三个写法如果你熟悉 Python却不常写 TypeScript可以先把这段代码看成三个动作await表示等异步操作完成const { session } ...表示从返回对象中取出session字段(event) { ... }是传给subscribe()的回调函数。这些写法不影响前面的调用链遇到它们时先看变量和事件代表什么即可。现在这个 Agent 已经能在程序中接收一次提问并输出回复但它没有业务知识或工具。要做资料中的数据分析助手下一步才是定义数据查询工具、确定工具能访问哪些数据再观察一次“模型请求工具 → 工具返回结果 → 模型继续回答”的链路。参考资料本文示例按 Piv0.84.3SDK 文档、模型配置文档及该版本源码整理。示例采用内置 DeepSeek Provider其他 Provider 的凭据名称与模型列表应以对应版本文档为准。