跳转到主要内容
Session 固定工作配置并承载连续的 Runs。创建 Session 不会提交任务,也不证明云 Sandbox 能够执行任务。本文说明创建、检查、初始文件和生命周期操作的源码契约。路径均包含 /v1;示例假定使用可信后端 Token,HEXAGON_API_URL 为不带该前缀的控制平面 origin。

创建与预检

两者接受相同的严格 JSON 请求体,允许 owner 和应用 Token。预检也会调用已配置的凭据入口就绪处理,并检查租户内的连接状态、Secret 和兼容性。它不是纯离线 schema 校验、容量预留、模型推理或云执行证明。预检成功不代表检查后的配置不会再发生变化。

请求字段

使用已保存 Agent 时,不能覆盖 identity、instructions、context、name、resources、network、required_capabilities,也不能提供非空 optional_tools。仍需明确提供 Sandbox、模型 ID 和所需 Tool 绑定,不要假定此接口自动补齐 Agent 保存的绑定。环境变量覆盖 Agent 的默认值。已归档 Agent 不能创建新 Session,即使指定旧 revision。 所有声明的 Tool 都需要绑定,包括 optional-at-start Tool。“可选”表示可延后就绪,不代表可以省略绑定。Sandbox、模型和受保护 HTTP 连接必须启用且 ready;所有连接都要属于当前租户并具有正确 kind。已保存 Agent 会拒绝未声明的 Tool 名称或缺少的声明绑定。

初始化与环境

行为文本不能含 NUL。文件路径不能为绝对路径,不能包含反斜线、空段、. 或 ..。行为 JSON 和编译后的初始化另有 65,536 字节限制。Identity 是行为指导,不是认证身份。文件引用描述初始上传内容;存在性、哈希和有效文本在提交 Run 时检查,预检不证明文件已经上传。 环境变量名称匹配 ^[A-Za-z_][A-Za-z0-9_]{0,127}$。保留名称包括 HEXAGON_、OPENCODE_、PI_ 前缀,以及 PORT、NODE_OPTIONS、PYTHONPATH、PYTHONHOME、LD_PRELOAD、LD_LIBRARY_PATH。值为最多 16,384 字符且不含 NUL 的字符串;最多 64 项,序列化 JSON 不超过 65,536 UTF-8 字节。普通环境值对 Agent 进程可读,不提供受保护 Provider/模型凭据的边界。参见配置和凭据边界。

请求示例

保存为 session-request.json,将两个示例 UUID 替换为已验证的连接 ID。这些 UUID 是占位符,不是已创建资源:
先预检,再明确使用保存的相同请求体创建:
创建 Session 不具有 Run 提交的幂等保证。响应丢失后先调查原创建,不要立即重试。保存返回的 Session ID,然后上传初始文件并提交 Run。

响应形状

预检返回 ready:true、combination、readiness:{status:"ready",checked_at}、lifecycle 和 connections。失败使用错误响应,不返回 {ready:false}。Combination 是解析后的能力与协议契约,不是执行测量结果。 Lifecycle 包含 mode(serverless/provider_managed/retained)、preservation(filesystem/memory/provider_managed/none)、automatic_wake:true 和实际 idle_timeout_seconds,后者最大为 timeout 减十秒。Connections 将 model 和受保护 API 别名映射到 implementation、raw_secret_in_sandbox:false、delegated_token_in_sandbox。声明 native credential auth 时 implementation 为 external_proxy_with_native_auth,否则为 external_proxy。此映射不是 Tool 就绪状态列表。 创建返回 id、可空 agent_id/agent_revision、definition、env_names、state、可空 sandbox、created_at、updated_at,不返回环境变量值。Definition 包含有效行为/资源/网络配置、解析后的 capabilities/combination、可选初始化摘要与 OCI 镜像、固定的连接配置和版本、tool_bindings、protected_api_bindings、message_policy:"reject_if_busy"、lifecycle 和凭据边界。嵌套 Provider 字段是随版本演进的元数据,不是跨 Provider 通用 Sandbox schema。

检查 Session 与初始化

GET /v1/sessions/{id} 返回 200,包含以上 Session 字段并增加 pause_scope。State 为 open、pausing、paused、resuming、closing、closed;sandbox 是可空的 Provider 资源描述。Session 存在或 open 不证明 Harness 进程存活。Owner 和应用 Token 都可读取。资源不存在或属于其他租户时返回 404 session_not_found。
GET /v1/sessions/{id}/initialization 返回 200,包含 schema_version:1、session_id、created_at、source:{kind,agent_id,agent_revision}、definition、environment:{names,values_redacted:true}。Kind 为 direct 或 agent。它读取历史有效快照,不重新解析最新 Agent 定义或连接版本。

上传与列出初始文件

POST /v1/sessions/{id}/files 允许 owner 和应用 Token,返回 200 与 {files:[{path,sha256,size}]},只包含本次请求上传的文件。请求体为严格 {files:[{path,content_base64}]}。一次 1–100 项,相对路径唯一、最长 500 字符,并符合上面的路径限制。Base64 使用 schema 规定的带填充编码字母表,每项最多 2,097,152 字符;本次请求解码后的总大小最多 8 MiB。编码与解码大小的区别见限制。 允许上传时,同路径文件替换已保存初始输入,其他路径不变。必须是 open Session,且没有提交过 Run,也没有已分配 Sandbox;接口不能修改运行中的工作区。即使第一个 Run 已取消,也不能重新打开初始上传窗口。启用 initialization 时,SOUL.md 为保留路径。 将以下内容保存为 files-request.json,示例文件内容为 hello:
相同路径的 GET 返回 200,{files:[{path,sha256,size}]} 按路径排列。它列出保存的初始输入元数据,不返回文件内容或当前被 Agent 修改后的工作区。上传响应丢失时可核对这些哈希。
上传专有错误包括 400 duplicate_input_path、400 reserved_initialization_path、413 upload_too_large、409 workspace_already_started、409 session_closed;请求结构无效为 400 invalid_request。Session 不存在或属于其他租户为 404。结构校验可能先于资源查找失败。

暂停、恢复与关闭

配置 lifecycle 服务时才注册这些路由。暂停和恢复要求 owner Token;关闭也允许应用 Token。均为租户范围内的 POST 操作。
逻辑 scope=session 不证明计算停止。Scope=sandbox 依赖 Provider 能力,Provider 管理的待机另行报告。完成转换时可能包含 compute_paused 和 provider_managed_standby,已经在目标状态时重复调用可能只返回 state/scope,不能把缺少字段理解为完整的新检查。暂停要求没有非终态 Run;转换或 scope 冲突分别返回 session_transition_pending 或 session_pause_scope_conflict,不支持原生暂停为 sandbox_pause_unsupported,均为 409。Closing/closed 拒绝暂停和恢复。提交 Run 可以自动唤醒暂停的 Session,不必每次先显式 resume。
显式关闭遇到非终态 Run 返回 409 session_busy,应先取消并观察终态。Close 先保存意图,再对账其拥有的资源,之后才确认关闭。Sandbox creation/checkpoint/deletion unconfirmed 错误需要检查资源操作;超时或错误不证明资源已不存在。对原 Session 重复 close 会对账原资源,已关闭时返回 {state:"closed"}。导出产物和历史 Runs 仍可访问,预览授权失效。参见资源对账。

生命周期错误处理

生命周期响应描述一次具体转换,不保证 Harness 已健康运行。原生或 Provider 管理的恢复路径可能将 Runtime 留在 restoring,后续执行仍须建立就绪状态。不能把资源丢失或操作结果未知自动转换为创建替代 Session。

创建错误与相关操作

严格 schema 校验失败返回 400 invalid_request。常见领域错误包括 404 agent_not_found、404 agent_revision_not_found、409 agent_archived、404 connection_not_found、400 connection_kind_mismatch、409 connection_not_ready、409 tool_not_ready、400 missing_tool_binding、400 undeclared_tool_binding、400 ambiguous_variables、413 initialization_too_large。Harness、模型、网络或能力不兼容时返回对应 reason,状态码 400;凭据入口就绪也可能先于定义校验失败。不要将所有错误归因于云配额,参见错误参考。 本文不替代仍需展开的其他接口参考:租户 Session 列表/活动、敏感环境值读取、当前授权、Session 内连接撤销、访问与预览授权。权限见 HTTP 总览,行为说明见连接生命周期、私有预览和初始化。 来源:Session schema 与操作、初始化、环境、初始文件、生命周期、HTTP 路由。示例经过源码审阅,不宣称本轮执行了 HTTP 或云任务。 关联端点的完整契约:Session 列表与活动、环境、授权与代理访问授权、产物与浏览器预览授权。这些路由返回不同投影,并有各自权限,不能共用一套 Session 响应 schema 来解释全部结果。

判断响应丢失后能否重复请求

上传含五个字节 hello 的 notes.txt 时,元数据应为 size:5,SHA-256 为 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824。这是计算样例,不是服务器响应回执。上传结果沿用请求文件顺序,列表结果按路径排序;比较时按路径与摘要匹配,不依赖数组位置。两者都不代表 Agent 后续修改的 Sandbox 文件。 Schema 校验、领域校验和实际执行是不同阶段。例如,未知顶层字段被严格请求 schema 拒绝,格式正确但不可用的 Harness 在目录解析时失败,而有效且 ready 的 Session 仍可能在后续云分配中失败。variables 与非空 env 同时出现由领域处理拒绝,不是仅初始 Session schema 就能判定。不要把这些归为相同失败,也不能宣称 HTTP schema 测试证明云执行就绪。