# 会话与运行 API REST 基址为 `https://api.hostanagent.com/v1`。经应用 Key 和可信 Subject 授权后，先读取运行发现，再创建 Session 和 Run。下列是主要操作；完整请求/响应字段见本站筛选后的[OpenAPI](/docs/reference/openapi.json)。 | 操作 | 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、输入等写请求带原幂等键；响应不明时原样核对，不换键启动第二次。[恢复策略](/docs/integration/recovery/)。 `queued`、`running`、等待工具/审批以及 `completed`、`failed`、`cancelled`、`expired` 的区别见[运行记录](/docs/console/runs-diagnostics/)。`completed` 可能带 `completion_reason=needs_user_input`，表示本轮结束，需要同一 Session 的下一轮输入。停止 SSE 只是停止观察；`cancel` 请求本身也不证明外部业务取消。 发布配置可以零余额；新模型请求须有足够可用余额。`402 INSUFFICIENT_BALANCE` 时没有模型调用。[费用说明](/docs/console/billing/)。