会话与运行 API
REST 基址为 https://api.hostanagent.com/v1。经应用 Key 和可信 Subject 授权后，先读取运行发现，再创建 Session 和 Run。下列是主要操作；完整请求/响应字段见本站筛选后的OpenAPI。
| 操作 | REST 路径 | 结果与注意事项 |
|---|---|---|
| 模型与运行发现 | GET /models、GET /runtime/bootstrap、GET /agents/{agent_id}/runtime |
发现可访问 Agent 与版本；元数据不含系统指令 |
| 会话 | GET/POST /sessions、GET/DELETE /sessions/{session_id} |
当前支持 managed + durable，Subject 隔离 |
| 历史 | GET /sessions/{session_id}/messages |
按已授权会话读取，不触发新 Run |
| 运行列表/创建 | GET/POST /runs |
创建成功返回 Run ID；同时检查余额/模型能力/版本/状态 |
| 快照/事件 | GET /runs/{run_id}、GET /runs/{run_id}/events |
快照和 SSE 用于观察与恢复 |
| 继续与控制 | POST /runs/{run_id}/inputs、.../approvals、.../cancel |
追加输入、审批、明确停止分别处理 |
| 诊断 | GET /runs/{run_id}/diagnostics |
安全元数据时间线，不复制正文 |
创建 Run 使用 agent_id 或不可变 agent_version 二选一；服务端在接受时固定具体版本。已经有活动 Run 的会话不能再新建并行 Run，应向原 Run 追加输入或等待终态。新 Run、输入等写请求带原幂等键；响应不明时原样核对，不换键启动第二次。恢复策略。
queued、running、等待工具/审批以及 completed、failed、cancelled、expired 的区别见运行记录。completed 可能带 completion_reason=needs_user_input，表示本轮结束，需要同一 Session 的下一轮输入。停止 SSE 只是停止观察；cancel 请求本身也不证明外部业务取消。
发布配置可以零余额；新模型请求须有足够可用余额。402 INSUFFICIENT_BALANCE 时没有模型调用。费用说明。