跳转到主要内容
本教程使用内置 Pi 1.5.2,让 Agent 在云 Sandbox 中生成一个文本文件。你将获得 Session 和 Run 标识、最终回答、可下载产物,并验证关闭 Session 后产物仍可读取。

前提与验证范围

先完成安装,在 Console 验证并启用一个 Sandbox 连接和一个兼容的模型连接。使用执行矩阵中已有证据的精确组合;例如 E2B / Pi 的记录需要同时核对模型端点和协议。不要仅按供应商名称推断通过。 两套程序已于 2026-11-20 分别在 Vercel + 内置 Pi 1.5.2 + 已配置 Messages 端点的 deepseek-ai/DeepSeek-V4-Flash 组合完成独立实云运行。执行记录覆盖任务完成、产物大小/hash/内容、Session 关闭、删除操作完成,以及关闭后下载字节一致。该结果不认证其他端点、账户或组合,也不覆盖 Tools、审批、多轮和预览。执行会使用云资源和模型额度;不需要额外 Tool 或预先注册 Agent 模板。

运行完整程序

在仓库根目录设置已经验证的连接 ID。这两个值是标识,不是供应商密钥:
选择一种语言执行。两套程序是独立旅程,运行两套将分别创建资源。 Python:完整源文件。安装本地 SDK 后运行:
TypeScript:完整源文件。在已安装仓库依赖的环境运行:
程序直接创建 Session,固定 Pi 版本和所选连接。提交的任务要求 Harness 将 hello.txt 放入它收到的 Run 产物目录。程序轮询 Run,核对导出文件内容,再关闭 Session 并重复下载产物以检查保留行为。

完成后应该看到什么

程序输出 Session 和 Run ID、最终回答,以及 Completed; artifacts and journal:。Python 记录位于 .local/docs-first-python/,TypeScript 位于 .local/docs-first-typescript/。 目录中包含私有 journal.json 和以本地固定名称保存的产物。使用固定名称避免把远端路径直接用于本地文件写入。至少一个产物的去除首尾空白后的内容应为 Hello from Hexagon。 日志最终阶段 closed_and_retention_checked 表示该程序观察到 Run 完成、产物内容符合预期、关闭接口返回 closed,且关闭后仍能下载产物。这个结果仅证明本次具体组合,不证明所有 Provider 都支持同样的行为。 成功 Run 的 output 是包含 role: "assistant"、text 和产物元数据的对象。阅读 output.text,再与下载文件核对:回答应说明创建了 hello.txt,内容为 Hello from Hexagon 加换行,具体措辞可以不同。回答中的工作区路径不是下载 URL,应通过 Artifact ID 下载。最终回答、终态和实际导出字节需要分别检查。回答审阅记录将两次已有回答与留存字节、实际 read/命令事件逐项核对,不承诺模型措辞固定。

如果程序中途退出

十分钟是示例的观察期限,不是服务器的取消命令。超时、终端关闭或网络断开后,Run 可能仍在运行。打开 Console,按私有记录中的标识检查原任务。 程序拒绝覆盖已有 journal,防止再次执行意外创建第二个 Session。不要直接删除 journal 来重试: 需要取消时调用 Python client.cancel(run_id) 或 TypeScript await client.cancel(runId),随后查询终态。取消不会自动撤销已经发生的外部操作,也不能代替 Session 关闭。 需要清理时调用 Python client.close(session_id) 或 TypeScript await client.close(sessionId),核对返回状态并查看 Console 中的资源操作。未知结果需要对账,不能把抛出异常解释成资源不存在。 本示例采用单进程使用方式;不要让多个进程修改同一个 journal。确认旧 Session 清理完成后,归档整个结果目录,再进行独立的新实验。 下一步:理解刚才发生的事。 继续完成更完整的任务:完成一个真实项目任务。 将此生命周期接入应用时,继续阅读后端集成。契约依据:SDK 指南、Session 初始化与验收旅程。