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