openapi: 3.2.0 info: title: Kimi 托管智能体 version: 2026-09-01-beta description: |- ## 概览 Kimi 托管智能体提供公共 REST API，用于配置智能体、运行会话，以及读取事件和产物。 API 基础地址为 `https://api.moonshot.cn/v1`。本文操作路径已包含 `/v1`，拼接这些路径时使用服务器地址 `https://api.moonshot.cn`。 ### 资源模型 **智能体**（Agent）定义执行所需的模型、指令、工具等配置。**会话**（Session）将冻结的智能体版本与对话及执行历史关联起来。会话可以覆盖部分配置，无需修改智能体。 每个会话都有接收用户输入的协调者**线程**（Thread），可以将工作委托给独立执行的子线程。会话事件流包含子线程活动，通过 `session_thread_id` 区分事件所属线程。 其他资源提供执行条件或保存执行结果： - **环境**（Environment）提供云沙箱或自托管执行。自托管 worker 认领**工作行**（WorkItem），在租约有效期间执行沙箱工具调用。 - **凭据库**（Vault）保存项目级凭据，秘密值只写不读。 - **技能**（Skill）提供可复用指令；**插件**（Plugin）打包技能与 MCP 服务器。 - **记忆库**（Memory Store）保存会话可访问的项目级文件；**Dreams** 维护这些记忆。 - **触发器**（Trigger）按计划或手动启动、复用会话，每次执行记录为一次 **TriggerRun**。 - **产物**（Artifact）是会话交付的可下载文件。 模型提供方操作中的 `provider binding` 指调用方为该提供方配置的接入。 ## 认证 通过 `Authorization` 请求头，以 Bearer 方式发送凭据。根据调用的操作选择凭据： | 凭据 | 授权范围 | | --- | --- | | API key（`sk-...`） | 调用方权限允许的项目 API。 | | 环境 work key | 绑定环境的工作队列。 | | 会话 work token | 绑定会话允许的 worker 操作。 | worker 凭据不能与 API key 互换，环境和会话凭据也不能互换。 例如，使用 API key 列出智能体： ```sh curl https://api.moonshot.cn/v1/agents \ -H "Authorization: Bearer $KIMI_API_KEY" \ -H "kimi-api-version: 2026-09-01-beta" ``` ## API 版本 ### 选择版本 发送 `kimi-api-version: 2026-09-01-beta` 使用本契约。除 `/v1/files*` 外，缺少版本头返回 400 `invalid_request_error`；所有端点都会拒绝未知版本。 文件端点允许省略版本头，以使用兼容格式：上传和删除返回 200，而非 201/204；文件记录使用 `status`、`status_details`，而非 `extract_status`；上传的文件不能挂载到会话。省略版本头不表示选择最新版。 ### 兼容性 稳定版的破坏性变更进入新的日期版本，包括删除或重命名端点、字段或枚举值，改变类型、含义或默认行为，新增必填请求字段，收窄合法输入，以及移除或重新定义错误类型。 客户端需要容忍新增端点、可选请求字段、响应字段、响应头和响应枚举值，包括错误类型。消息措辞不属于稳定接口。 ### Beta 与退役政策 当前版本是 beta，行为可能在同一版本内调整，调用方可见变化记录在 ChangeLog 和发布说明中。稳定版在继任版本发布后继续可用，退役提前公告，但没有固定通知期。退役政策约定响应携带 `Deprecation` 和 `Sunset`，到期后拒绝该版本。目前没有版本进入退役。 ## 请求约定 ### 资源标识符 资源 ID 是不透明字符串，应完整保存和传递。不要校验前缀、解析结构，或通过 ID 推断资源属性。 ### 请求体与更新 JSON 请求体使用 `application/json`，文件和包上传使用 `multipart/form-data`。未声明的内容类型返回 400 `invalid_request_error`。 只发送操作声明的字段，未知 JSON 字段返回 400 `invalid_parameter_error`。`PATCH` 中省略字段表示不修改，非 nullable 字段拒绝显式 `null`，清空时使用该字段说明中约定的空值。 ### 分页 列表操作接受 `page_size`（1–1000，默认 50）和 `page_token`，返回 `{items, next_page_token}`。将返回的令牌原样传入以读取下一页；`next_page_token` 缺省表示结束。 ## 幂等与创建重试 声明了 `Idempotency-Key` 的操作接受最长 255 字节的键。每个创建意图使用独立键，包括针对不同目标资源的创建。不要在同一项目内跨操作或资源复用键。 已保存的响应在 24 小时内按原状态码和响应体重放。重试时保持键和请求体字节一致，JSON 空白变化或重新生成 multipart boundary 都可能造成冲突。同键请求不同，或原请求仍在执行时，返回 409 `conflict_error`。 校验、认证与权限类失败和 5xx 不保存响应；业务拒绝可以被保存。没有重放记录不能证明写入未发生。超时、500 或键过期后，应先查询资源确认结果，再决定是否重新创建。幂等键减少重复执行，但不保证所有故障下都只写入一次。 ## 限流与大小限制 临时限流返回 429 `rate_limit_reached_error`，`Retry-After` 为等待秒数。配额或预算耗尽使用 `exceeded_current_quota_error`，不携带该响应头。 请求超限返回 400 `invalid_request_error`，而非 413。上传还受文件与包大小限制，其他约束见各操作说明。 | 请求或上传 | 上限 | | --- | --- | | JSON 请求体，记忆写入除外 | 4 MiB | | 记忆写入请求体 | 28 MiB | | `POST /v1/files` | 每个文件 100 MiB | | `POST /v1/skills` | 每个技能包 64 MiB | | 插件包上传 | 每个插件包 64 MiB | ## 错误处理 ### HTTP 错误 API 错误使用 `{"error": {type, message, request_id, param?}}`。结合 HTTP 状态码和 `error.type` 选择恢复方式，用 `message` 展示原因，不要解析其措辞。 | 错误类型 | 状态码 | 恢复方式 | | --- | --- | --- | | `invalid_parameter_error` | 400 | 修正 `param` 指出的字段。 | | `invalid_request_error` | 400 | 修正请求格式、方法、版本或大小。 | | `failed_precondition_error` | 400、409、412 | 核对操作的状态要求。完成 WorkItem stop 时收到 409，应继续服务当前租约；租约操作返回 412，表示放弃过期租约并重新轮询。 | | `authentication_error` | 401 | 更新或更换凭据。 | | `permission_denied_error` | 403 | 核对权限和凭据范围。 | | `resource_not_found_error` | 404 | 核对 ID 和可见范围。 | | `conflict_error` | 409 | 解决名称、版本或幂等冲突后再重试。 | | `rate_limit_reached_error` | 429 | 按 `Retry-After` 指定的秒数等待。 | | `exceeded_current_quota_error` | 429 | 解决配额或预算耗尽后再重试。 | | `server_error` | 500 | 记录请求 ID，写操作先确认结果，读操作可退避重试。 | 表中是当前声明的类型。客户端也应处理未知类型和不符合该格式的响应，包括基础设施故障。 字段校验错误携带 `param`，路径可能包含位置前缀和数组下标，如 `body.mcp_servers[2].name`，也可能只有字段名。不要依赖单一路径形状。 资源中的错误字段，如 `TriggerRun.error`，使用各自的领域 schema 和仅供展示的类型，不是 HTTP 错误响应。 ### 请求 ID 响应携带 `Msh-Request-Id`，通常与错误体的 `request_id` 一致；重放可能保留原响应体的 ID，而响应头标识本次重试。反馈重试问题时请同时提供两个 ID。 ### 会话执行错误 `session.error` 事件描述会话创建后的执行问题，其 `error_type` 独立于 HTTP `error.type`。重新连接事件流不会重试执行。 | `error_type` | 恢复方式 | | --- | --- | | `internal_error` | 反馈错误并提供可用的请求 ID。 | | `model_error` | 按消息处理或稍后重试执行。 | | `model_unavailable` | 选择可用模型或新建会话。 | | `rate_limited` | 等待后重试执行。 | | `engine_overloaded` | 稍后重试执行。 | | `quota_exceeded` | 恢复模型配额或账户余额后继续。 | | `context_length_exceeded` | 缩短输入或新建会话。 | | `invalid_request` | 按消息修正模型请求。 | | `timeout` | 核对会话状态后再重试执行。 | | `max_steps` | 发送新输入，以新的轮次继续。 | | `mcp_connection_failed` | 检查受影响 MCP 服务器的连通性。 | | `mcp_authentication_failed` | 更新或重新连接受影响的 MCP 凭据。 | 客户端应容忍新增值，并在恢复前核对会话状态。MCP 失败可能只让该服务器的工具不可用，其余执行仍然继续。存在 `mcp_server_name` 时，可据此定位受影响的服务器。 ## 事件流（SSE） ### 事件格式 会话和线程事件流（`GET .../events/stream`）通过 `event:` 表示事件类型、`id:` 表示恢复游标、`data:` 提供完整事件 JSON，每 30 秒发送一次 `: hb` 心跳。 事件流按序投递完整事件；`agent.delta` 增量预览仅在 `include_deltas=true` 时发送。 建流前失败返回 HTTP 错误格式。建流后报告的传输失败通过 `event: error` 携带同一格式并关闭连接。客户端也应处理没有错误帧的断线。 ### 重连 以最后收到的帧 `id` 作为 `cursor` 或 `Last-Event-ID` 重连。资源事件 ID 不是恢复游标。不可用的游标返回 `invalid_parameter_error`，且 `param=cursor`。 ### 游标过期后的恢复 游标位置过期时，丢弃未完成的预览，并按以下顺序恢复： 1. 打开 `cursor=now` 流，等待控制帧，暂存随后到达的实时事件。 2. 通过 `GET .../events` 回补已持久化事件。 3. 合并历史与暂存事件，去除重叠，再继续消费已打开的流。 先建流再回补，可避免历史与实时事件之间留下空档。未写入持久历史的预览无法重建。 ## ChangeLog 以下按日期记录调用方可见变化，同日优先列出影响已有接入的变化，再列新增能力与仅更新契约的内容。每条说明影响及必要的调用方动作，完整输入与输出见对应操作定义。 ### 2026-10-14 #### 触发器 - **`reuse_session` 更新**：更新保持 `reuse_session` 的触发器时，修改 `agent_id`、`agent_version`、`environment_id` 或 `resources` 现在返回 400 `failed_precondition_error`。此前这些修改会被接受，但不会作用到托管会话，该会话沿用创建时的配置。需要修改时，先将 `session_mode` 切换为 `new_session`，或新建触发器。 - **平台发起的运行**：平台为托管触发器发起的运行（例如 Dreams 策略的活跃度检查）现在记录 `context.type: "system"`，不再记录为归属触发器创建者的 `manual` 上下文。按 `context.type` 分支的客户端须接受 `system`。 #### 会话事件流 - **增量预览改为可选**：会话与线程事件流默认不再包含 `agent.delta` 事件。需要继续接收增量预览时，设置新增的 `include_deltas=true` 查询参数；只消费完整事件的调用方不再接收增量流量。 ### 2026-10-10 #### 自托管 worker 停止 - **worker 停止**：中断会话在取消完成后可以释放工作行，即使仍保留排队输入。租约释放后，显式 Continue 重新将工作入队。使用 `user.interrupt` 停止会话执行，使用工作行 stop 请求 worker 停止。 - **停止完成**：工作行 stop 不传 `final_status` 时进入 `stopping`；worker 取消工具、完成结果回写后提交 `final_status: completed`，仍忙碌的会话会被取消。空闲 worker 可以直接提交 `completed`，释放租约但不取消会话；活跃执行或新输入返回 409 `failed_precondition_error`。会话 work token 可以停止自己的工作行，REST 不接受 `force` 或 `reason`。 #### 工具确认与自定义工具 - **工具回复**：`always_ask` 工具产生 `agent.tool_use`，等待 `user.tool_confirmation`。使用 `type: custom` 声明的工具产生 `agent.custom_tool_use`，由客户端执行并提交 `user.custom_tool_result`。两类回复均通过 `data.event_id` 指定请求，不传 `session_thread_id`，同一调用以首条有效回复为准。 - **等待中的线程**：`requires_action` 和 `stop_reason.event_ids` 标识待返回的确认与自定义工具结果。每个线程收到全部待返回回复后恢复执行，会话级列表汇总所有等待线程。子线程状态、请求和回复出现在会话事件流中，由顶层 `session_thread_id` 标识所属线程。 ### 2026-10-09 - MCP 工具在工具集与单个工具均未设置 `load_mode` 时改为按需加载：模型先获得名称，需要时再加载 schema。需要保留原加载行为时，设置 `load_mode: eager`，让 schema 随每次请求发送；不支持按需加载的模型仍使用 eager 加载。 - `default_toolset_20260901` 中的 `search_image_by_text` 与 `search_image_by_image` 采用同一默认规则，其他内置工具仍为 `eager`。 ### 2026-09-24 - `project` 插件引用接受 `version: "latest"`，每次唤醒时解析为采用版本。省略版本仍在写入时固定为最新发布版本。`official` 引用必须省略版本，任何显式值都返回 400 `invalid_parameter_error`。 ### 2026-09-23 - **提示词校验**：创建和更新会话时，无效的 `agent_overrides.system` 模板返回 400 `invalid_parameter_error`。 - **执行事件**：新增 `agent.model_started` 和 `agent.tool_started` 事件，标记模型请求与工具执行的开始。流式调用在各自首个片段产生 `agent.thinking_started` 和 `agent.message_started`，非流式调用不产生这两个事件。可用 `agent.model_started` 到首个 `agent.delta` 计算 TTFT。 - **配置通知**：并发更新按提交顺序产生 `session.updated`，该事件不标识运行中的执行何时采用新配置。 ### 2026-09-21 #### 项目插件 - **项目插件**：`POST /v1/plugins` 和 `POST /v1/plugins/{id}/versions` 发布不超过 64 MiB 的 `.zip` 包，返回 201 与插件、版本和校验结果，两者均接受 `Idempotency-Key`。`POST /v1/plugins/validate` 只校验而不发布；不可发布的包返回 200 和 `ok: false` 的校验结果。 - **插件版本与归档**：`GET /v1/plugins/{id}/versions` 按语义版本从新到旧列出，`GET /v1/plugins/{id}/versions/{version}/content` 下载 `application/zip`。`POST /v1/plugins/{id}/archive` 返回 204，插件退出读取 API，项目内名称释放，已有精确版本引用继续有效。 - **插件选择**：`GET /v1/plugins` 接受 `scope` 为 `official` 或 `project`，省略返回两者，`org` 和 `user` 返回 400 `invalid_parameter_error`。`Plugin` 新增 `scope`、`status` 和 `latest_version`，`version` 仍表示配置写入时固定的版本。 - **会话插件**：创建和更新接受 `agent_overrides.plugins`，以与 `skills` 相同的三态语义替换冻结智能体的插件集合。`official` 条目省略 `version`，`project` 条目可以指定已发布版本。 #### OAuth 路由 - `MCPOAuthCredential` 和 `CreateVaultOAuthSession` 接受 `egress_environment_id`，发现、动态客户端注册、令牌交换与后台刷新均经过该环境的代理。空字符串清除绑定；新建时省略表示不绑定，更新时省略保留已有绑定。 ### 2026-09-20 - 插件和技能响应新增用于展示的可选 `categories`，未分类时省略，声明的分类包括 `finance`。分类不改变智能体配置。`GET /v1/plugins` 和 `GET /v1/skills` 接受 `category` 过滤列表。 ### 2026-09-19 - 智能体与会话的 `model.reasoning_effort` 接受 `max`，它仍是所选模型可能忽略的提示。 ### 2026-09-17 #### 会话输入与配置 - **输入容量**：会话已有 50 条待处理输入时，新输入返回 400 `failed_precondition_error`。消费或撤回释放容量，Interrupt 和 Continue 仍可使用。 - **会话覆盖**：`agent_overrides` 在 `mcp_servers`、`skills` 之外新增 `tools`、`model` 和 `system`。`roster` 只能在创建时覆盖，`PATCH` 携带它返回 400 `invalid_parameter_error`。 - **技能版本**：省略版本在写入时冻结为当前版本，`"latest"` 在每次唤醒时解析，精确版本经过校验后固定使用。同一 `skill_id` 混用 `"latest"` 和精确版本返回 400 `invalid_parameter_error`。 - **更新事件**：`session.updated` 仅在实际变化时产生，只携带变更字段：生效智能体快照与覆盖文档，或 `title`。清空全部覆盖产生空 `agent_overrides` 对象，客户端可安全忽略不识别的事件。 #### 触发器投递与暂停 - **复用会话**：定时和手动 `reuse_session` 运行跳过上次因执行错误停止的空闲会话（`session_failed`）和已满队列（`session_queue_full`）。同一会话连续 3 次因这两类原因跳过才暂停触发器，其他结果重置计数，已有消息和会话自身重试不受影响。 - **触发器暂停**：计划运行自动暂停活跃触发器时发送 `trigger.paused` webhook。通过 `data.id` 查询触发器的 `paused_reason`，普通跳过和手动操作不发送该 webhook。 #### 契约修正与说明 - **触发器错误**：`TriggerRun.error` 和 `PausedReason.error` 使用 `TriggerError`，其仅供展示的 `type` 为开放字符串，包括 `fire_failed`、`session_failed` 和 `overlap_in_flight`。本次修正 schema 复用 `ErrorType` 的问题，线上负载不变。 - **补充既有行为**：中断保留待处理输入；触发器更新重新校验未修改的 `initial_events`；未配置子智能体名单的会话不提供编排工具；重复内置工具集只使用首份声明，不合并配置。请求与响应不变。 ### 2026-09-15 - **未知 JSON 字段**：未声明成员现在返回 400 `invalid_parameter_error`，路径如 `body.unknown_key`，此前会被忽略。调用方应移除请求中的额外成员。 - **时间过滤**：智能体和会话列表接受 `created_at_gt`、`created_at_gte`、`created_at_lt`、`created_at_lte` 及对应 `updated_at_*` 参数。`gt`、`lt` 不含边界，`gte`、`lte` 包含边界。 - **契约声明**：OpenAPI 从 3.1.0 升级为 3.2.0；`POST /v1/files` 和 `POST /v1/skills` 的 multipart 文件部分采用无类型 schema 与通配编码的标准声明；事件流通过 `itemSchema` 声明各事件的 `event` 和 `data`；创建操作共用一份 `Idempotency-Key` 参数。线上格式与请求处理行为不变。 ### 2026-09-14 - 非 nullable 的可选请求字段显式传 `null` 现在返回 400 `invalid_parameter_error`，路径如 `body.name` 或 `body.description`，此前会被视为省略。省略字段表示不修改，清空时使用该字段说明中约定的空值。 ### 2026-09-13 - 请求校验现在执行 query、path、header 和 JSON 输入声明的类型、必填、范围、模式、枚举与组合约束。违例返回 400 `invalid_parameter_error`，校验路径带位置前缀与数组下标，如 `body.mcp_servers[2].name`、`query.page_size`。此前部分违例被接受，或在后续校验中使用较短路径与不同消息。调用方应按声明约束检查请求，并使用 `error.type` 与 `param` 判断错误，不匹配消息措辞。 - 未声明的 `Content-Type` 现在返回 400 `invalid_request_error`，即使请求体可以解析。JSON 操作使用 `application/json`，上传使用 `multipart/form-data`。 ### 2026-09-10 2026-09-09 预告的持久中断行为现已生效。 - **中断**：空闲会话现在接受中断，返回 202 和 `control_epoch`，而非 400。会话与活跃线程异步停止，响应与 `user.interrupt` 确认均不代表完成，需通过获取会话接口核对。可选令牌为 `data.expected_control_epoch`，过期值返回 409 `conflict_error`；会话仍处于中断状态时，重复中断不推进控制版本。 - **继续**：`POST /v1/sessions/{id}/continue` 返回 `control_epoch`，未中断会话保持不变，正在停止或已终止的会话返回 409 `conflict_error`。请求被接受不代表启动完成，需核对返回控制版本上的 `continue_pending`。 - **排队输入**：停止后发送的新输入在收尾完成后恢复执行，保留输入本身不会恢复会话，恢复后保持队列顺序。 - **归档**：运行中的子线程可以归档并取消，会话停止期间也允许操作。父会话未终止时，重复归档子线程返回 204。归档会话在停止期间返回 409 `conflict_error`，运行期间仍返回 400。 ### 2026-09-09 本日公告持久中断契约，执行行为于 2026-09-10 生效。停止完成与恢复规则见该日记录。 - **控制状态**：线程新增 `interrupted`、`control_epoch`；会话新增 `stopping`、`interrupted`、`control_epoch`、`continue_pending`；事件可含 `epoch` 与 `user.interrupt` 确认。 - **生命周期操作**：契约新增无需请求体的 `POST /v1/sessions/{id}/continue`、空闲会话中断，以及停止后新输入恢复执行。可选的预期控制版本在过期时返回 409 `conflict_error`，省略则针对当前代次。子线程归档取消活跃执行；仍有生命周期任务或活跃线程时，删除会话返回 409 `conflict_error`。 - **触发器输入**：`initial_events` 和待处理事件接受可排队用户消息，不接受此 beta 中的中断命令。`reuse_session` 触发器会恢复已停止的会话。 ### 2026-09-07 - **字段错误**：JSON 类型与校验失败使用 `invalid_parameter_error` 和字段路径，union 错误定位到 union 本身；请求级错误使用不带 `param` 的 `invalid_request_error`。本次修正此前分类错误或路径不完整的字段错误，缺少 `user.message.data` 和低于下限的 `activity.min_changed_sessions` 现在会被拒绝。 - **不透明 ID**：资源 ID 不再声明 `pattern` 约束。调用方应移除基于旧模式的校验，其范围未覆盖所有已签发 ID。 - **MCP 错误**：`SessionErrorType` 新增 `mcp_connection_failed` 和 `mcp_authentication_failed`，用于初始连接或执行中途失败。凭据自动刷新并重试一次仍被拒绝时报告鉴权失败，其他刷新失败不作为会话错误。`SessionErrorPayload.mcp_server_name` 标识受影响的服务器，其他类型与旧事件不含该字段，应据此定位而不解析消息。 - **官方环境**：`GET /v1/environments` 新增 `official_only`，默认 false。 ### 2026-09-06 - `listTriggers` 接受 `agent_id`，按所属智能体过滤。 ### 2026-09-05 - `listMemoryStores` 和 `listMemories` 从按创建时间升序改为最新在前。依赖旧顺序的客户端需要调整处理逻辑。 - `GET /v1/agents` 新增 `official_only`，默认 false。 ### 2026-09-04 - **仅更新契约声明**：各操作声明可选的 `kimi-api-version` 请求头，线上仍要求 `/v1/files*` 之外携带，文件端点省略时采用兼容格式。事件流声明已有的 `Cache-Control: no-cache`、`X-Accel-Buffering: no` 响应头；共享 429 响应声明已有的 `Retry-After`，仅用于 `rate_limit_reached_error`。请求处理行为不变。 ### 2026-09-03 - **batch 文件**：向会话挂载 `batch` 文件返回 400 `failed_precondition_error`，而非 404 `resource_not_found_error`，仍不支持挂载。 - **MCP 请求头**：智能体和会话的 `McpServer` 声明接受只写的 `headers`，用于非敏感连接请求头。更新时，省略或空请求头保留身份未变的服务器（name、type、URL）的原值；非空整体替换，空字符串值删除键，仅大小写不同的重名请求头会被拒绝。 - **环境代理**：`EnvironmentProxy.route_all` 将全部出站主机经代理转发，并允许空 `hosts` 列表。平台内部端点绕过代理；`limited` 下主机白名单不生效，可达性由代理决定。 tags: - name: 智能体 description: 管理智能体配置及其版本。 - name: 会话 description: 管理会话、线程、资源、消息和事件。 - name: 文件 description: 上传、浏览、下载和删除用户文件。 - name: 产物 description: 查看已交付的产物，下载指定版本。 - name: 技能 description: 管理 Skill 包及不可变版本。 - name: 工作队列 description: 经环境工作队列认领并驱动自托管会话工作。 - name: 环境 description: 管理执行环境及其配置。 - name: 凭据库 description: 管理凭据库、凭据和 OAuth 会话。 - name: 插件 description: 列出并查看可用插件。 - name: 记忆库 description: 管理记忆库、文件、版本和 Dreams 策略。 - name: 触发器 description: 创建、管理和运行 Trigger。 paths: /v1/agents: get: operationId: listAgents summary: 列出智能体 description: |- 返回调用方的智能体，默认最新在前，除非 `order` 为 `created_at`。已归档的智能体不会出现在列表中。 将 `official_only` 设为 true 时，仅返回平台提供的官方智能体；默认值为 false。 `created_at_*` 与 `updated_at_*` 参数按创建时间或最近更新时间限定列表；`gt` / `lt` 后缀不含该时刻，`gte` / `lte` 含该时刻。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: order in: query required: false description: 列表排序。默认为 `created_at_desc`。 schema: $ref: '#/components/schemas/AgentOrder' explode: false - name: exclude_multiagent in: query required: false description: 为 true 时只返回未配置 `multiagent` 的智能体。子智能体选择器使用它，因为子智能体名单不能引用本身就是协调者的智能体。 schema: type: boolean explode: false - name: official_only in: query required: false description: 为 true 时只返回平台提供的官方智能体。默认为 false。 schema: type: boolean explode: false - name: created_at_gt in: query required: false description: 返回在该时间戳之后创建的智能体（不含该时刻）。 schema: type: string format: date-time explode: false - name: created_at_gte in: query required: false description: 返回在该时间戳及之后创建的智能体（含该时刻）。 schema: type: string format: date-time explode: false - name: created_at_lt in: query required: false description: 返回在该时间戳之前创建的智能体（不含该时刻）。 schema: type: string format: date-time explode: false - name: created_at_lte in: query required: false description: 返回在该时间戳及之前创建的智能体（含该时刻）。 schema: type: string format: date-time explode: false - name: updated_at_gt in: query required: false description: 返回在该时间戳之后更新的智能体（不含该时刻）。 schema: type: string format: date-time explode: false - name: updated_at_gte in: query required: false description: 返回在该时间戳及之后更新的智能体（含该时刻）。 schema: type: string format: date-time explode: false - name: updated_at_lt in: query required: false description: 返回在该时间戳之前更新的智能体（不含该时刻）。 schema: type: string format: date-time explode: false - name: updated_at_lte in: query required: false description: 返回在该时间戳及之前更新的智能体（含该时刻）。 schema: type: string format: date-time explode: false - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页智能体，按请求的排序返回。 content: application/json: schema: $ref: '#/components/schemas/AgentList' example: items: [] next_page_token: next-page-token '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 智能体 post: operationId: createAgent summary: 创建智能体 description: |- 创建智能体及其首个不可变版本（`"1"`）。 - 省略 `version` 的技能引用会在写入时固定为当时的最新版本；指定精确版本会固定使用该版本；显式传入 `"latest"` 时保留该值，并在读取或唤醒时重新解析。插件引用按所属市场的版本规则处理（见 `PluginRef.version`）。 - `multiagent` 中的子智能体名单在写入时解析为固定的智能体版本。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - $ref: '#/components/parameters/IdempotencyKeyHeader' responses: '201': description: 已创建的智能体，处于首个不可变版本。 content: application/json: schema: $ref: '#/components/schemas/Agent' example: id: agent_01h455vb4pex5vsknk084sn02q name: Example Agent model: id: kimi-example version: '1' created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' scope: project '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 智能体 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAgentRequest' example: name: Example Agent model: kimi-example /v1/agents/{id}: get: operationId: getAgent summary: 获取智能体 description: 返回单个智能体及其最新版本。已归档的智能体仍可读取。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 智能体 ID。 schema: type: string responses: '200': description: 最新版本的智能体。 content: application/json: schema: $ref: '#/components/schemas/Agent' example: id: agent_01h455vb4pex5vsknk084sn02q name: Example Agent model: id: kimi-example version: '1' created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' scope: project '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 智能体 patch: operationId: updateAgent summary: 更新智能体 description: |- 修改请求体中提供的字段，并创建一个新的不可变智能体版本。 - 数组和 `metadata` 会替换已存储的值。传入空值可清空对应集合。`null` 值会被拒绝（400 `invalid_parameter_error`）。 - `mcp_servers` 的 headers 例外：按服务器身份合并。`headers` 缺省或为空时，继承未发生变化的服务器（name、type、url 均一致）的已存储值，非空时整体替换，值为空字符串表示删除该键。 - 传入当前的 `version` 进行乐观并发检查。版本过期时更新失败，返回 409 `conflict_error`。 - 空补丁返回 400 `invalid_request_error`。已归档的智能体拒绝更新，返回 400 `failed_precondition_error`。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 智能体 ID。 schema: type: string responses: '200': description: 更新后的智能体，处于新的不可变版本。 content: application/json: schema: $ref: '#/components/schemas/Agent' example: id: agent_01h455vb4pex5vsknk084sn02q name: Updated Agent model: id: kimi-example version: '2' created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-02T00:00:00Z' scope: project '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 智能体 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAgentRequest' example: version: '1' name: Updated Agent /v1/agents/{id}/archive: post: operationId: archiveAgent summary: 归档智能体 description: 归档智能体。已归档的智能体仍可读取，但不能更新，也不能用于开启新会话。已有会话不受影响。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 智能体 ID。 schema: type: string responses: '204': description: 智能体已归档。 '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 智能体 /v1/agents/{id}/versions: get: operationId: listAgentVersions summary: 列出智能体版本 description: 返回智能体的不可变版本，最新在前。每一项都是该版本捕获的完整配置。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 智能体 ID。 schema: type: string - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页智能体版本，最新在前。 content: application/json: schema: $ref: '#/components/schemas/AgentVersionList' example: items: - version: '1' id: agent_01h455vb4pex5vsknk084sn02q name: Example Agent model: id: kimi-example created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' scope: project next_page_token: next-page-token '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 智能体 /v1/artifacts: get: operationId: listArtifacts summary: 列出产物 description: 列出调用方可见的产物，最近交付的在前。每个条目为该产物的最新版本。用 `session_id` 筛选单个会话的产物。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: session_id in: query required: false description: 仅返回该会话交付的产物。 schema: type: string explode: false - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页产物，最近交付的在前。 content: application/json: schema: $ref: '#/components/schemas/ArtifactList' example: items: - id: arti_01h455vb4pex5vsknk084sn02q session_id: sesn_01h455vb4pex5vsknk084sn02q path: /workspace/report.txt name: report.txt mime_type: text/plain size_bytes: 14 version: '1' delivered_at: '2026-08-26T12:00:00Z' next_page_token: page-example-next '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 产物 /v1/artifacts/{id}: get: operationId: getArtifact summary: 获取产物 description: 返回单个产物的元数据。未指定 `version` 时返回最新版本，指定时返回该确切版本。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 产物 ID。 schema: type: string - name: version in: query required: false description: 要返回的版本。省略时返回最新版本。 schema: type: string explode: false responses: '200': description: 指定版本的产物。 content: application/json: schema: $ref: '#/components/schemas/Artifact' example: id: arti_01h455vb4pex5vsknk084sn02q session_id: sesn_01h455vb4pex5vsknk084sn02q path: /workspace/report.txt name: report.txt mime_type: text/plain size_bytes: 14 version: '1' delivered_at: '2026-08-26T12:00:00Z' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 产物 delete: operationId: deleteArtifact summary: 删除产物 description: 永久删除一个产物及其全部版本。已上报该产物的事件不会撤回。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 产物 ID。 schema: type: string responses: '204': description: 产物及其全部版本已删除。 '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 产物 /v1/artifacts/{id}/content: get: operationId: getArtifactContent summary: 下载产物内容 description: 下载产物内容。未指定 `version` 时下载最新版本。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 产物 ID。 schema: type: string - name: version in: query required: false description: 要下载的版本。省略时下载最新版本。 schema: type: string explode: false responses: '200': description: 该产物版本的内容字节。 content: '*/*': schema: contentMediaType: '*/*' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 产物 /v1/artifacts/{id}/versions: get: operationId: listArtifactVersions summary: 列出产物版本 description: 列出一个产物的全部版本，最新在前。每个条目为该版本的完整产物。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 产物 ID。 schema: type: string - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页产物版本，最新在前。 content: application/json: schema: $ref: '#/components/schemas/ArtifactVersionList' example: items: - id: arti_01h455vb4pex5vsknk084sn02q session_id: sesn_01h455vb4pex5vsknk084sn02q path: /workspace/report.txt name: report.txt mime_type: text/plain size_bytes: 14 version: '1' delivered_at: '2026-08-26T12:00:00Z' next_page_token: page-example-next '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 产物 /v1/environments: post: operationId: createEnvironment summary: 创建环境 description: |- 创建一个环境，将其配置冻结为不可变版本 `"1"`，并开始构建。 最新版本的 `build_status` 报告 `ready` 后，会话即可使用该环境。名称不要求唯一。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - $ref: '#/components/parameters/IdempotencyKeyHeader' responses: '201': description: 已创建的环境。其首个版本正在构建（构建管道开启时 `build_status` 为 `building`）。 content: application/json: schema: $ref: '#/components/schemas/Environment' example: id: env_01h455vb4pex5vsknk084sn02q name: Data analysis description: 用于数据分析任务的执行环境 config: type: cloud networking: type: limited allowed_hosts: - example.invalid packages: pip: - pandas==2.3.2 setup_script: mkdir -p /workspace/output metadata: {} build_status: building created_at: '2026-08-26T12:00:00Z' updated_at: '2026-08-26T12:00:00Z' scope: project '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 环境 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateEnvironmentRequest' example: name: Data analysis description: 用于数据分析任务的执行环境 config: type: cloud networking: type: limited allowed_hosts: - example.invalid packages: pip: - pandas==2.3.2 setup_script: mkdir -p /workspace/output metadata: {} get: operationId: listEnvironments summary: 列出环境 description: |- 返回调用方的环境，最新在前。除非 `include_archived` 为 true，否则不包含已归档的环境。 将 `official_only` 设为 true 时，仅返回平台提供的官方环境；默认值为 false。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: include_archived in: query required: false description: 包含已归档的环境。省略时不包含。 schema: type: boolean explode: false - name: official_only in: query required: false description: 为 true 时只返回平台提供的官方环境。默认为 false。 schema: type: boolean explode: false - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页环境，最新在前。 content: application/json: schema: $ref: '#/components/schemas/EnvironmentList' example: items: - id: env_01h455vb4pex5vsknk084sn02q name: Data analysis description: 用于数据分析任务的执行环境 config: type: cloud networking: type: unrestricted build_status: ready created_at: '2026-08-26T12:00:00Z' updated_at: '2026-08-26T12:05:00Z' scope: project next_page_token: page-example-next '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 环境 /v1/environments/{environment_id}/work: get: operationId: listWork summary: 列出工作行 description: 按最新在前列出环境的工作行。终态行作为审计轨迹保留，除非用 `status` 筛选，否则一并返回。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: environment_id in: path required: true description: 要列出工作行的环境。 schema: type: string - name: status in: query required: false description: 按生命周期状态筛选。省略时返回全部状态。 schema: $ref: '#/components/schemas/WorkItemStatus' explode: false - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页工作行，最新在前。 content: application/json: schema: $ref: '#/components/schemas/WorkItemList' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 工作队列 /v1/environments/{environment_id}/work/poll: get: operationId: pollWorkItems summary: 轮询认领工作行 description: 为调用方认领环境中最早的待处理工作行。返回的工作行处于租约状态：通过 ack 确认、心跳续租和 stop 释放，期间始终携带 poll 返回的 `generation`。`block_ms` 大于零时，调用将长轮询直到有工作到达或预算耗尽（届时返回空响应）。成功的 poll 即一次认领：不要对它做幂等重试。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: environment_id in: path required: true description: 要轮询队列的环境。 schema: type: string - name: worker_id in: query required: true description: 租约登记其下的 worker 标识。 schema: type: string explode: false - name: block_ms in: query required: false description: 长轮询预算（毫秒），最大 999：`0`（默认）立即返回（无待处理工作时为 204）；正值时调用等待工作直到预算耗尽。轮询不是幂等的：每次成功调用都会认领环境中最早的待认领工作行。 schema: type: integer format: int32 minimum: 0 maximum: 999 default: 0 explode: false - name: lease_ttl_ms in: query required: false description: 请求的租约时长（毫秒）。非正值取平台默认值；超过默认值的请求会被钳制到默认值。 schema: type: integer format: int32 explode: false - name: reclaim_older_than_ms in: query required: false description: 本次 poll 的内联回收提前量（毫秒，默认 5000）：投递前，先把投递时间超过该值的工作行退回队列。ack 窗口本身固定 5000ms，由后台 sweeper 回收——该参数只调整本次 poll 内联回收的提前量。投递后须立即 Ack，慢 executor 启动须在 Ack 之后；恢复时长用 lease_ttl_ms 控制。 schema: type: integer format: int32 minimum: 0 explode: false responses: '200': description: 已投递的工作行；若预算耗尽仍无待处理工作，则返回 204。 content: application/json: schema: $ref: '#/components/schemas/WorkItem' example: id: work_01h455vb4pex5vsknk084sn02q session_id: sesn_01h455vb4pex5vsknk084sn02q environment_id: env_01h455vb4pex5vsknk084sn02q status: queued generation: 1 worker_id: worker-1 lease_ttl_ms: 300000 created_at: '2026-09-20T12:00:00Z' claimed_at: '2026-09-20T12:00:00Z' secret: eyJzZXNzaW9uc190b2tlbiI6InN3dC1hYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ejAxMjM0NTY3ODlBQkNERUZHIn0 '204': description: 已投递的工作行；若预算耗尽仍无待处理工作，则返回 204。 '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 工作队列 /v1/environments/{environment_id}/work/stats: get: operationId: getWorkItemStats summary: 工作队列统计 description: 返回该环境的队列统计（按活跃行实时计算）：`depth` 为待认领行数，`claimed` 为租约中行数，`workers` 为持有租约的不同 worker 数，`oldest_queued_at` 为最老待认领行的入队时间（无待认领行时缺省）。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: environment_id in: path required: true description: 要统计队列的环境。 schema: type: string responses: '200': description: 该环境的工作队列统计。 content: application/json: schema: $ref: '#/components/schemas/WorkQueueStats' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 工作队列 /v1/environments/{environment_id}/work/{id}: get: operationId: getWorkItem summary: 获取工作行 description: 按 ID 返回一个工作行。任意生命周期状态的行均可返回，包括保留作审计的终态行。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: environment_id in: path required: true description: 工作行所属的环境。 schema: type: string - name: id in: path required: true description: 工作行 ID。 schema: type: string responses: '200': description: 该工作行。 content: application/json: schema: $ref: '#/components/schemas/WorkItem' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 工作队列 /v1/environments/{environment_id}/work/{id}/ack: post: operationId: ackWorkItem summary: 确认收到投递的工作行 description: 确认收到已投递的工作行（`queued` → `starting`），记录 `acknowledged_at`——不在固定 ack 窗口（5000ms，由后台 sweeper 回收）内确认，工作行将被退回队列。投递后须立即 Ack，慢 executor 启动须在 Ack 之后。过期 token 将被拒绝并返回 412 `failed_precondition_error`。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: environment_id in: path required: true description: 工作行所属的环境。 schema: type: string - name: id in: path required: true description: 工作行 ID。 schema: type: string responses: '200': description: 已确认的工作行，状态转为 `starting`。 content: application/json: schema: $ref: '#/components/schemas/WorkItem' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '412': description: 调用方的 fencing token 已过期：工作行的租约状态已变化——重新同步后携带当前 generation 重试（仅 `work-items` 端点与受 fencing 保护的工具结果回写）。 content: application/json: schema: $ref: '#/components/schemas/PreconditionFailedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 工作队列 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AckWorkItemRequest' example: worker_id: worker-1 generation: 1 /v1/environments/{environment_id}/work/{id}/heartbeat: post: operationId: heartbeatWorkItem summary: 心跳续租工作行 description: 续租调用方持有的已认领工作行。（`id`、`worker_id`、`generation`）三元组必须与该行的当前状态一致：token 过期意味着工作行已被回收并可能被其他 worker 重新认领，调用将失败并返回 412 `failed_precondition_error`，其中携带当前 generation——请重新轮询以重同步。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: environment_id in: path required: true description: 工作行所属的环境。 schema: type: string - name: id in: path required: true description: 工作行 ID。 schema: type: string responses: '200': description: 续租后该工作行的租约状态。 content: application/json: schema: $ref: '#/components/schemas/WorkHeartbeat' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '412': description: 调用方的 fencing token 已过期：工作行的租约状态已变化——重新同步后携带当前 generation 重试（仅 `work-items` 端点与受 fencing 保护的工具结果回写）。 content: application/json: schema: $ref: '#/components/schemas/PreconditionFailedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 工作队列 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/HeartbeatWorkItemRequest' example: worker_id: worker-1 generation: 1 /v1/environments/{environment_id}/work/{id}/stop: post: operationId: stopWorkItem summary: 停止或完成工作行 description: |- 不传 `final_status` 时请求优雅停止：工作行进入 `stopping`，worker 在下次心跳中收到该状态，取消在飞工具，在续租期间完成结果回写，再提交 `final_status: completed`。确认时若会话仍忙碌则取消会话，并将工作行释放为 `completed`。 空闲 worker 直接提交 `completed`，保留会话。待处理输入、活跃 loop、尚未完成的取消或恢复会返回 409 `failed_precondition_error`，worker 应用同一租约继续服务。已终止或取消已完成的会话可保留排队输入。释放后的新输入或 continue 为会话创建新的工作行。 会话级 work token 只能停止绑定的工作行，worker 与代次必须匹配。过期租约返回 412 `failed_precondition_error`，worker 必须放弃该租约。停止请求在租约回收后仍然保留。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: environment_id in: path required: true description: 工作行所属的环境。 schema: type: string - name: id in: path required: true description: 工作行 ID。 schema: type: string responses: '204': description: 已请求停止，或已确认 worker 完成。 '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '412': description: 调用方的 fencing token 已过期：工作行的租约状态已变化——重新同步后携带当前 generation 重试（仅 `work-items` 端点与受 fencing 保护的工具结果回写）。 content: application/json: schema: $ref: '#/components/schemas/PreconditionFailedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 工作队列 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StopWorkItemRequest' example: worker_id: worker-1 generation: 1 /v1/environments/{id}: get: operationId: getEnvironment summary: 获取环境 description: 返回单个环境，包括其最新版本的构建状态。已归档的环境仍可读取。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 环境 ID。 schema: type: string responses: '200': description: 环境详情，包括其最新版本的构建状态。 content: application/json: schema: $ref: '#/components/schemas/Environment' example: id: env_01h455vb4pex5vsknk084sn02q name: Data analysis description: 用于数据分析任务的执行环境 config: type: cloud networking: type: unrestricted build_status: ready created_at: '2026-08-26T12:00:00Z' updated_at: '2026-08-26T12:05:00Z' scope: project '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 环境 patch: operationId: updateEnvironment summary: 更新环境 description: |- 仅修改请求体中出现的字段。`null` 值会被拒绝（400 `invalid_parameter_error`），传入空对象或空数组可清空对应集合。 每次更新——包括仅修改元数据——都会冻结一个新的不可变版本并开始构建。只有之后创建的会话会使用新版本。配置类型不能更改。已归档的环境拒绝更新（400 `failed_precondition_error`）。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 环境 ID。 schema: type: string responses: '200': description: 更新后的环境，携带新的不可变版本。 content: application/json: schema: $ref: '#/components/schemas/Environment' example: id: env_01h455vb4pex5vsknk084sn02q name: Data analysis production description: 用于数据分析任务的执行环境 config: type: cloud networking: type: unrestricted metadata: {} build_status: ready created_at: '2026-08-26T12:00:00Z' updated_at: '2026-08-26T12:10:00Z' scope: project '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 环境 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateEnvironmentRequest' example: name: Data analysis production metadata: {} delete: operationId: deleteEnvironment summary: 删除环境 description: |- 永久删除一个已归档的环境及其全部版本。 环境必须先归档，且没有任何未终止的会话仍在引用它，否则返回 400 `failed_precondition_error`。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 环境 ID。 schema: type: string responses: '204': description: 环境及其全部版本已删除。 '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 环境 /v1/environments/{id}/archive: post: operationId: archiveEnvironment summary: 归档环境 description: 归档一个环境。已归档的环境拒绝更新，也不能承载新会话。现有会话不受影响。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 环境 ID。 schema: type: string responses: '204': description: 环境已归档。 '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 环境 /v1/files: get: operationId: listFiles summary: 列出文件 description: 列出已上传的文件。不带 `kimi-api-version` 请求头的请求列出整个组织的文件列表；`2026-09-01-beta` 请求列出项目下的文件。不带 `page_size` 时返回完整列表。通过 `POST /v1/sessions/{id}/resources` 将文件挂载到会话。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: page_size in: query required: false schema: type: integer format: int32 minimum: 1 maximum: 1000 explode: false - name: page_token in: query required: false schema: type: string explode: false responses: '200': description: 调用方可见的全部已上传文件。 content: application/json: schema: $ref: '#/components/schemas/FileMetadataList' example: items: - id: file_01h455vb4pex5vsknk084sn02q filename: report.txt mime_type: text/plain size_bytes: 14 created_at: '2026-08-26T12:00:00Z' purpose: file-extract extract_status: ready '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 文件 post: operationId: uploadFile summary: 上传文件 description: |- 以 multipart 表单数据上传一个文件，并返回其文件记录。 - **表单**：`file` 部分必填，须携带文件名（或在表单中显式提供 `filename`）。该部分自身的 Content-Type 可以省略，存储的 MIME 类型将按文件内容与文件名检测。 - **限制**：单个文件上限 100 MiB 且不能为空。上传后的文件不可修改。 - **命名**：与现有文件重名上传时，服务器会在存储的文件名上添加后缀，例如 `report (1).txt`。 parameters: - $ref: '#/components/parameters/APIVersionHeader' responses: '201': description: 上传文件的记录。 content: application/json: schema: $ref: '#/components/schemas/FileMetadata' example: id: file_01h455vb4pex5vsknk084sn02q filename: report.txt mime_type: text/plain size_bytes: 15 created_at: '2026-08-26T12:00:00Z' purpose: file-extract extract_status: ready '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 文件 requestBody: required: true content: multipart/form-data: schema: type: object properties: file: description: 文件字节内容。 filename: $ref: '#/components/schemas/UploadFilename' purpose: allOf: - $ref: '#/components/schemas/FilePurpose' description: 处理用途。 required: - file encoding: file: contentType: '*/*' filename: contentType: text/plain purpose: contentType: text/plain example: {} /v1/files/{id}: get: operationId: getFile summary: 获取文件 description: 返回单个文件的元数据。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 文件 ID。 schema: type: string responses: '200': description: 文件的元数据。 content: application/json: schema: $ref: '#/components/schemas/FileMetadata' example: id: file_01h455vb4pex5vsknk084sn02q filename: report.txt mime_type: text/plain size_bytes: 14 created_at: '2026-08-26T12:00:00Z' purpose: file-extract extract_status: ready '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 文件 delete: operationId: deleteFile summary: 删除文件 description: 删除一个文件，并释放其名称供后续上传使用。`batch` 文件只能由上传它的用户删除，否则返回 403。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 文件 ID。 schema: type: string responses: '204': description: 文件已删除。 '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '403': description: 调用方无权执行该操作，例如操作他人所有的资源。 content: application/json: schema: $ref: '#/components/schemas/ForbiddenErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 文件 /v1/files/{id}/content: get: operationId: getFileContent summary: 获取文件内容 description: |- 返回文件按其处理用途可用的内容。 - `file-extract`：一个 JSON 对象，解析出的 Markdown 在 `content` 字段中。 - `batch`：上传的文件，仅上传者本人可读。文件在上传时经解析规范化，返回的字节可能与原文件不同。 - **错误**：`image`/`video` 文件、解析失败的文件以及没有解析文本的文件将返回 400 `failed_precondition_error`。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 文件 ID。 schema: type: string responses: '200': description: 按文件处理用途可用的内容（`file-extract` 为携带解析 Markdown 的 JSON 对象，`batch` 为规范化后的上传文件）。 content: '*/*': schema: contentMediaType: '*/*' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '403': description: 调用方无权执行该操作，例如操作他人所有的资源。 content: application/json: schema: $ref: '#/components/schemas/ForbiddenErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 文件 /v1/memory-stores: post: operationId: createMemoryStore summary: 创建记忆库 description: |- 创建项目作用域的记忆库。 - `name` 在项目内唯一，活跃和已归档的记忆库均不可重名。冲突返回 409 `conflict_error`，归档记忆库也不会释放其名称。 - 记忆库创建时为空。用 `POST /v1/memory-stores/{id}/memories` 添加文件。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - $ref: '#/components/parameters/IdempotencyKeyHeader' responses: '201': description: 已创建的记忆库。 content: application/json: schema: $ref: '#/components/schemas/MemoryStore' example: id: mstr_01h455vb4pex5vsknk084sn02q name: team-memory description: 项目共享笔记 created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 记忆库 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateMemoryStoreRequest' example: name: team-memory description: 项目共享笔记 get: operationId: listMemoryStores summary: 列出记忆库 description: 返回调用方的记忆库，最新在前。除非 `include_archived` 为 true，否则不包含已归档的记忆库。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: include_archived in: query required: false description: 包含已归档的记忆库。省略时不包含。 schema: type: boolean explode: false - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页记忆库，最新在前。 content: application/json: schema: $ref: '#/components/schemas/MemoryStoreList' example: items: - id: mstr_01h455vb4pex5vsknk084sn02q name: team-memory created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' next_page_token: next-page-token '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 记忆库 /v1/memory-stores/{id}: get: operationId: getMemoryStore summary: 获取记忆库 description: 返回单个记忆库的元数据。已归档的记忆库仍可读取。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 记忆库 ID。 schema: type: string responses: '200': description: 记忆库的元数据。 content: application/json: schema: $ref: '#/components/schemas/MemoryStore' example: id: mstr_01h455vb4pex5vsknk084sn02q name: team-memory created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 记忆库 patch: operationId: updateMemoryStore summary: 更新记忆库 description: |- 重命名记忆库或修改其描述。请求体中未出现的字段保持当前值。 - 新名称不得与项目内其他记忆库重名，无论活跃还是已归档（409 `conflict_error`）。 - 空的部分更新返回 400 `invalid_request_error`。已归档的记忆库拒绝更新，返回 400 `failed_precondition_error`。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 记忆库 ID。 schema: type: string responses: '200': description: 应用了修改的记忆库。 content: application/json: schema: $ref: '#/components/schemas/MemoryStore' example: id: mstr_01h455vb4pex5vsknk084sn02q name: team-memory description: 更新后的笔记 created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-02T00:00:00Z' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 记忆库 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateMemoryStoreRequest' example: description: 更新后的笔记 delete: operationId: deleteMemoryStore summary: 删除记忆库 description: |- 永久删除已归档的记忆库及其全部文件和版本历史。 - 记忆库必须先归档，且不能绑定任何会话。违反时返回 400 `failed_precondition_error`。 - 记忆库的 Dreams 策略一并删除。该策略持有的触发器被归档：不再触发，运行记录保留。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 记忆库 ID。 schema: type: string responses: '204': description: 记忆库及其文件、版本历史与 Dreams 策略已删除。 '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 记忆库 /v1/memory-stores/{id}/archive: post: operationId: archiveMemoryStore summary: 归档记忆库 description: |- 归档一个记忆库。归档不可撤销。 已归档的记忆库拒绝元数据更新和记忆写入。读取——包括版本历史和内容——仍然可用，历史版本的正文也仍可删除。重复归档返回 204。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 记忆库 ID。 schema: type: string responses: '204': description: 记忆库已归档。 '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 记忆库 /v1/memory-stores/{id}/memories: post: operationId: createMemory summary: 创建记忆 description: |- 在记忆库中创建一个文件，并记录为第一个版本。 - `content` 为 base64 编码，解码后不超过 20 MiB。省略时创建空文件。 - 相同 `path` 上已有未删除的文件时返回 409 `conflict_error`。重新创建此前删除过的路径会成功，并生成新的文件 ID。 - 已归档的记忆库拒绝写入，返回 400 `failed_precondition_error`。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 记忆库 ID。 schema: type: string responses: '201': description: 已创建的文件，携带其内容与哈希。 content: application/json: schema: $ref: '#/components/schemas/Memory' example: id: mem_01h455vb4pex5vsknk084sn02q memory_store_id: mstr_01h455vb4pex5vsknk084sn02q path: README.md content: SGVsbG8= content_sha256: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa content_size_bytes: 5 created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 记忆库 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateMemoryRequest' example: path: README.md content: SGVsbG8= get: operationId: listMemories summary: 列出记忆 description: 返回记忆库当前的文件，最新在前，不含文件内容。已删除的文件不在其中。已归档的记忆库仍可读取。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 记忆库 ID。 schema: type: string - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页当前文件，最新在前，不含内容。 content: application/json: schema: $ref: '#/components/schemas/MemoryList' example: items: - id: mem_01h455vb4pex5vsknk084sn02q memory_store_id: mstr_01h455vb4pex5vsknk084sn02q path: README.md content_sha256: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa content_size_bytes: 5 created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' next_page_token: next-page-token '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 记忆库 /v1/memory-stores/{id}/memories/{memory_id}: get: operationId: getMemory summary: 获取记忆 description: 返回单个文件的元数据和当前的 base64 编码内容。已删除的文件返回 404。已归档的记忆库仍可读取。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 记忆库 ID。 schema: type: string - name: memory_id in: path required: true description: 记忆文件 ID。 schema: type: string responses: '200': description: 文件的元数据与当前的 base64 编码内容。 content: application/json: schema: $ref: '#/components/schemas/Memory' example: id: mem_01h455vb4pex5vsknk084sn02q memory_store_id: mstr_01h455vb4pex5vsknk084sn02q path: README.md content: SGVsbG8= content_sha256: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa content_size_bytes: 5 created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 记忆库 patch: operationId: updateMemory summary: 更新记忆 description: |- 修改文件的路径、内容或两者，并把更改记录为新版本。 - 请求带上文件当前的 `content_sha256` 以防范并发写入。不匹配返回 409 `conflict_error`。 - 路径和内容都没有变化的更新返回当前文件，不记录新版本。 - 重命名到另一个未删除文件的路径返回 409 `conflict_error`。已归档的记忆库拒绝写入，返回 400 `failed_precondition_error`。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 记忆库 ID。 schema: type: string - name: memory_id in: path required: true description: 记忆文件 ID。 schema: type: string responses: '200': description: 更新后的文件，携带其内容与新哈希。 content: application/json: schema: $ref: '#/components/schemas/Memory' example: id: mem_01h455vb4pex5vsknk084sn02q memory_store_id: mstr_01h455vb4pex5vsknk084sn02q path: README.md content: V29ybGQ= content_sha256: bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb content_size_bytes: 5 created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-02T00:00:00Z' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 记忆库 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateMemoryRequest' example: content: V29ybGQ= content_sha256: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa delete: operationId: deleteMemory summary: 删除记忆 description: 删除文件并记录一个 `deleted` 版本。文件的版本历史仍可读取。对已删除的文件再次删除返回 404。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 记忆库 ID。 schema: type: string - name: memory_id in: path required: true description: 记忆文件 ID。 schema: type: string responses: '204': description: 文件已删除，并记录了一个 `deleted` 版本。 '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 记忆库 /v1/memory-stores/{id}/memories/{memory_id}/versions: get: operationId: listMemoryVersions summary: 列出记忆版本 description: 返回文件的版本历史，仅含元数据。默认最旧在前，`order` 为 `desc` 时最新在前。已删除文件的版本仍可列出。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 记忆库 ID。 schema: type: string - name: memory_id in: path required: true description: 记忆文件 ID。 schema: type: string - name: order in: query required: false description: 排序。默认为 `asc`。 schema: $ref: '#/components/schemas/MemoryVersionOrder' explode: false - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页版本元数据，按请求的排序。 content: application/json: schema: $ref: '#/components/schemas/MemoryVersionList' example: items: - id: mver_01h455vb4pex5vsknk084sn02q memory_store_id: mstr_01h455vb4pex5vsknk084sn02q memory_id: mem_01h455vb4pex5vsknk084sn02q path: README.md operation: modified source: api created_at: '2026-01-02T00:00:00Z' next_page_token: next-page-token '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 记忆库 /v1/memory-stores/{id}/memories/{memory_id}/versions/{version_id}: get: operationId: getMemoryVersionContent summary: 获取记忆版本 description: 返回单个版本的元数据及其历史内容的 base64 编码。`deleted` 版本以及已删除正文的版本不返回内容。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 记忆库 ID。 schema: type: string - name: memory_id in: path required: true description: 记忆文件 ID。 schema: type: string - name: version_id in: path required: true description: 记忆版本 ID。 schema: type: string responses: '200': description: 版本的元数据，以及可读时的历史 base64 编码内容。 content: application/json: schema: $ref: '#/components/schemas/MemoryVersion' example: id: mver_01h455vb4pex5vsknk084sn02q memory_store_id: mstr_01h455vb4pex5vsknk084sn02q memory_id: mem_01h455vb4pex5vsknk084sn02q path: README.md operation: modified content: SGVsbG8= content_sha256: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa content_size_bytes: 5 source: api created_at: '2026-01-02T00:00:00Z' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 记忆库 /v1/memory-stores/{id}/memories/{memory_id}/versions/{version_id}/redact: post: operationId: redactMemoryVersion summary: 删除记忆版本正文 description: |- 永久删除一个历史版本的正文，仅保留其元数据。已删除的正文无法恢复。 - 只影响所选版本。当前文件和其他版本不受影响。 - 文件当前对应的版本不能删除正文（400 `failed_precondition_error`）。对已经删除过正文的版本重复执行是空操作。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 记忆库 ID。 schema: type: string - name: memory_id in: path required: true description: 记忆文件 ID。 schema: type: string - name: version_id in: path required: true description: 记忆版本 ID。 schema: type: string responses: '200': description: 已设置 `redacted_at` 的版本。 content: application/json: schema: $ref: '#/components/schemas/MemoryVersion' example: id: mver_01h455vb4pex5vsknk084sn02q memory_store_id: mstr_01h455vb4pex5vsknk084sn02q memory_id: mem_01h455vb4pex5vsknk084sn02q path: README.md operation: modified source: api created_at: '2026-01-02T00:00:00Z' redacted_at: '2026-01-03T00:00:00Z' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 记忆库 /v1/memory-stores/{memory_store_id}/dream-policy: get: operationId: getDreamPolicy summary: 获取 Dreams 策略 description: |- 返回单个记忆库的 Dreams 策略。 从未配置过策略时，响应中两个条件均为禁用，且不携带 `agent_id`、`trigger_id`、`environment_id` 或 `updated_at`。已归档的记忆库仍可读取。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: memory_store_id in: path required: true description: 记忆库 ID。 schema: type: string responses: '200': description: 记忆库的 Dreams 策略。未配置时两个条件均为禁用。 content: application/json: schema: $ref: '#/components/schemas/DreamPolicy' example: memory_store_id: mstr_01h455vb4pex5vsknk084sn02q agent_id: agent_01h455vb4pex5vsknk084sn02q activity: enabled: true min_changed_sessions: 3 schedule: enabled: false trigger_id: trig_01h455vb4pex5vsknk084sn02q environment_id: env_01h455vb4pex5vsknk084sn02q updated_at: '2026-01-01T00:00:00Z' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 记忆库 patch: operationId: updateDreamPolicy summary: 更新 Dreams 策略 description: |- 整体替换单个记忆库的 Dreams 策略。 - 请求体是对两个条件的整体替换而非合并。即使禁用，`activity` 和 `schedule` 也必填。 - 任一条件启用时 `environment_id` 必填，且环境必须处于活跃状态。启用条件还要求调用方携带模型 API key，否则返回 401。 - 每次更新记录一个不可变的策略版本，并创建或更新策略持有的触发器。定时条件禁用期间触发器保持暂停。 - 已归档的记忆库只接受禁用两个条件的更新。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: memory_store_id in: path required: true description: 记忆库 ID。 schema: type: string responses: '200': description: 替换后的策略，携带解析后的 `agent_id`、`trigger_id` 与 `updated_at`。 content: application/json: schema: $ref: '#/components/schemas/DreamPolicy' example: memory_store_id: mstr_01h455vb4pex5vsknk084sn02q agent_id: agent_01h455vb4pex5vsknk084sn02q activity: enabled: true min_changed_sessions: 3 schedule: enabled: false trigger_id: trig_01h455vb4pex5vsknk084sn02q environment_id: env_01h455vb4pex5vsknk084sn02q updated_at: '2026-01-02T00:00:00Z' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 记忆库 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateDreamPolicyRequest' example: agent_id: agent_01h455vb4pex5vsknk084sn02q activity: enabled: true min_changed_sessions: 3 schedule: enabled: false environment_id: env_01h455vb4pex5vsknk084sn02q /v1/plugins: get: operationId: listPlugins summary: 列出插件 description: |- 返回可用于智能体配置的已上架插件，按 ID 升序排列。`query` 对名称、描述和关键词做大小写不敏感匹配。 - **可见性范围**：默认同时返回平台上架的 `official` 插件与调用方项目自有的插件。`scope` 将结果收窄到其中一种；`org` 与 `user` 不是插件的可见性范围，传入时返回 400 `invalid_parameter_error`。 - 已归档的插件不会出现在列表中。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: query in: query required: false description: 对名称、描述和关键词做大小写不敏感匹配。 schema: type: string explode: false - name: category in: query required: false description: 按展示分类过滤。 schema: $ref: '#/components/schemas/PluginCategory' explode: false - name: scope in: query required: false description: 要列出的可见性范围。省略时同时返回 `official` 与 `project` 插件。 schema: $ref: '#/components/schemas/ResourceScope' explode: false - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页已上架插件，按 ID 升序。 content: application/json: schema: $ref: '#/components/schemas/PluginList' example: items: [] next_page_token: page_next_example '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 插件 post: operationId: createPlugin summary: 创建插件 description: |- 通过 `.zip` 插件包上传发布一个项目自有的插件及其第一个版本。 - 插件包不超过 64 MiB（展开后 128 MiB、500 个条目），且必须包含 `kimi.plugin.json` manifest，`skills/` 与 `locales/` 目录与之同级。 - 存在阻塞性结论的插件包以 400 拒绝，不会发布。可先调用 `POST /v1/plugins/validate` 读取全部结论；拒绝响应只携带其中第一条。 - 声明的名称不得属于项目中另一个活跃插件（409 `conflict_error`）。归档插件会释放其名称。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - $ref: '#/components/parameters/IdempotencyKeyHeader' responses: '201': description: 已发布的插件、其首个不可变版本与插件包校验结果。 content: application/json: schema: $ref: '#/components/schemas/CreatePluginResponse' example: plugin: id: plg_01h455vb4pex5vsknk084sn02q name: data-tools display_name: Data tools description: 用于处理结构化数据的工具。 version: 1.0.0 created_at: '2026-09-13T10:00:00Z' updated_at: '2026-09-13T10:00:00Z' scope: project status: active latest_version: 1.0.0 version: plugin_id: plg_01h455vb4pex5vsknk084sn02q version: 1.0.0 name: data-tools description: 用于处理结构化数据的工具。 created_at: '2026-09-13T10:00:00Z' report: ok: true issues: [] '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 插件 requestBody: required: true content: multipart/form-data: schema: type: object properties: file: description: 插件包归档。 required: - file encoding: file: contentType: '*/*' example: {} /v1/plugins/validate: post: operationId: validatePlugin summary: 校验插件包 description: |- 校验一个插件包并返回全部结论，不产生任何副作用。 不可发布的插件包以 200 响应返回 `ok: false` 的校验结果，而不是错误：下列 4xx 响应对应上传本身有误，不对应校验未通过。在调用 `POST /v1/plugins` 或 `POST /v1/plugins/{id}/versions` 之前使用本接口，可一次读取全部结论。 parameters: - $ref: '#/components/parameters/APIVersionHeader' responses: '200': description: 所提交插件包的校验结果，无论是否可发布。 content: application/json: schema: $ref: '#/components/schemas/ValidatePluginResponse' example: report: ok: false issues: - code: manifest.name.pattern field: name severity: error message: The Plugin name must be kebab-case. '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 插件 requestBody: required: true content: multipart/form-data: schema: type: object properties: file: description: 待校验的插件包归档。 required: - file encoding: file: contentType: '*/*' example: {} /v1/plugins/{id}: get: operationId: getPlugin summary: 获取插件 description: 返回单个已上架插件，包括其捆绑的 MCP 服务器与技能。未上架的插件返回 404。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 插件 ID。 schema: type: string responses: '200': description: 插件详情，包括其捆绑的 MCP 服务器与技能。 content: application/json: schema: $ref: '#/components/schemas/Plugin' example: id: data-tools name: data-tools display_name: Data tools description: 用于处理结构化数据的工具。 version: '1' mcp_servers: - mcp_key: data name: Data service description: 结构化数据工具。 needs_oauth: false url: https://example.invalid/mcp skills: - name: data-analysis description: 分析表格数据。 created_at: '2026-08-01T10:00:00Z' updated_at: '2026-08-01T10:00:00Z' scope: official status: active latest_version: '1' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 插件 /v1/plugins/{id}/archive: post: operationId: archivePlugin summary: 归档插件 description: |- 归档一个项目自有的插件。 已归档的插件不能被新的智能体版本引用，并从读取 API 中消失（获取、列表、版本列表与版本内容均返回 404）。归档状态会在后续唤醒和挂载解析时生效，已经固定精确版本的存量智能体也会被过滤，因此归档前请评估仍需运行的智能体。其名称在同一项目内释放，供后续插件使用。`official` 插件，或归属其他项目的插件，返回 404。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 插件 ID。 schema: type: string responses: '204': description: 插件已归档。 '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 插件 /v1/plugins/{id}/versions: post: operationId: createPluginVersion summary: 创建插件版本 description: |- 通过 `.zip` 插件包上传为项目自有插件发布一个新的不可变版本。 - manifest 声明的语义版本不得已在该插件下发布过（409 `conflict_error`）；已发布的版本不会被覆盖。 - 版本可以是预发布版本（如 `2.0.0-rc.1`），用于测试。只有精确固定该版本的引用才会使用预发布版本；仅当插件没有正式版本时，它才会成为 `latest_version`。 - 插件包大小限制与阻塞性结论的拒绝规则同 `POST /v1/plugins`。 - `official` 插件，或归属其他项目的插件，返回 404。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 插件 ID。 schema: type: string - $ref: '#/components/parameters/IdempotencyKeyHeader' responses: '201': description: 发布之后的插件、新的不可变版本与插件包校验结果。 content: application/json: schema: $ref: '#/components/schemas/CreatePluginResponse' example: plugin: id: plg_01h455vb4pex5vsknk084sn02q name: data-tools display_name: Data tools description: 用于处理结构化数据的工具。 version: 1.1.0 created_at: '2026-09-13T10:00:00Z' updated_at: '2026-09-13T11:00:00Z' scope: project status: active latest_version: 1.1.0 version: plugin_id: plg_01h455vb4pex5vsknk084sn02q version: 1.1.0 name: data-tools description: 用于处理结构化数据的工具。 created_at: '2026-09-13T11:00:00Z' report: ok: true issues: [] '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 插件 requestBody: required: true content: multipart/form-data: schema: type: object properties: file: description: 插件包归档。 required: - file encoding: file: contentType: '*/*' example: {} get: operationId: listPluginVersions summary: 列出插件版本 description: 返回该插件已发布的版本，语义版本最新的在前。已归档插件的版本不再可读。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 插件 ID。 schema: type: string - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页已发布版本，语义版本最新的在前。 content: application/json: schema: $ref: '#/components/schemas/PluginVersionList' example: items: - plugin_id: plg_01h455vb4pex5vsknk084sn02q version: 1.0.0 name: data-tools description: 用于处理结构化数据的工具。 created_at: '2026-09-13T10:00:00Z' next_page_token: page_next_example '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 插件 /v1/plugins/{id}/versions/{version}/content: get: operationId: getPluginVersionContent summary: 获取插件版本内容 description: 下载项目自有插件指定确切发布版本的插件包归档。响应始终为 `application/zip`，字节与提交时的归档一致。`official` 插件不提供插件包下载，返回 400 `failed_precondition_error`。已归档的插件返回 404。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 插件 ID。 schema: type: string - name: version in: path required: true description: 确切的已发布语义版本，例如 `"1.0.0"`。 schema: type: string responses: '200': description: 存储的插件包归档字节（`application/zip`）。 content: application/zip: schema: contentMediaType: application/zip '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 插件 /v1/sessions: get: operationId: listSessions summary: 列出会话 description: |- 返回调用方的会话，最近更新的排在最前，除非 `order` 另有指定。列表项省略 `resources` 绑定。请使用 `GET /v1/sessions/{id}` 获取。 `agent_id` 将列表限定为一个智能体，`agent_version` 限定为其某个固定版本，`statuses` 限定为给定的生命周期状态。`created_at_*` 与 `updated_at_*` 参数按创建时间或最近更新时间限定列表；`gt` / `lt` 后缀不含该时刻，`gte` / `lte` 含该时刻。除非 `include_archived` 为 true，否则不包含已归档的会话。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: order in: query required: false description: 列表排序。默认为 `updated_at_desc`。 schema: $ref: '#/components/schemas/SessionOrder' explode: false - name: agent_id in: query required: false description: 将列表限定为运行该智能体的会话。 schema: type: string explode: false - name: agent_version in: query required: false description: 将列表限定为固定到该智能体版本的会话（按资源递增的数字版本号，例如 `"2"`）。通常与 `agent_id` 组合使用。 schema: type: string explode: false - name: statuses in: query required: false description: 将列表限定为这些生命周期状态。省略表示不过滤状态。 schema: type: array items: $ref: '#/components/schemas/SessionState' explode: false - name: include_archived in: query required: false description: 包含已归档的会话。省略时不包含。 schema: type: boolean explode: false - name: created_at_gt in: query required: false description: 返回在该时间戳之后创建的会话（不含该时刻）。 schema: type: string format: date-time explode: false - name: created_at_gte in: query required: false description: 返回在该时间戳及之后创建的会话（含该时刻）。 schema: type: string format: date-time explode: false - name: created_at_lt in: query required: false description: 返回在该时间戳之前创建的会话（不含该时刻）。 schema: type: string format: date-time explode: false - name: created_at_lte in: query required: false description: 返回在该时间戳及之前创建的会话（含该时刻）。 schema: type: string format: date-time explode: false - name: updated_at_gt in: query required: false description: 返回在该时间戳之后更新的会话（不含该时刻）。 schema: type: string format: date-time explode: false - name: updated_at_gte in: query required: false description: 返回在该时间戳及之后更新的会话（含该时刻）。 schema: type: string format: date-time explode: false - name: updated_at_lt in: query required: false description: 返回在该时间戳之前更新的会话（不含该时刻）。 schema: type: string format: date-time explode: false - name: updated_at_lte in: query required: false description: 返回在该时间戳及之前更新的会话（含该时刻）。 schema: type: string format: date-time explode: false - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页会话，按请求的排序返回。列表项省略 `resources`。 content: application/json: schema: $ref: '#/components/schemas/SessionList' example: items: [] next_page_token: next-page-token '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 post: operationId: createSession summary: 创建会话 description: |- 创建运行选定智能体版本的会话，初始状态为 `idle`。 - 未提供 `agent_version` 时，将冻结最新可用的智能体版本，并固定环境最新构建就绪的版本。此后对二者的更新都不会改变此会话。 - 凭据库（Vault）与记忆库的绑定仅在创建时生效（最多 16 个凭据库和 8 个记忆库）。文件可以稍后添加。 - 使用 `POST /v1/sessions/{id}/events` 发送第一条消息以开始任务。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - $ref: '#/components/parameters/IdempotencyKeyHeader' responses: '201': description: 已创建的会话（`idle`），携带其资源绑定与智能体快照。 content: application/json: schema: $ref: '#/components/schemas/Session' example: id: sesn_01h455vb4pex5vsknk084sn02q agent_id: agent_01h455vb4pex5vsknk084sn02q environment_id: env_01h455vb4pex5vsknk084sn02q status: idle title: 示例会话 created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSessionRequest' example: agent_id: agent_01h455vb4pex5vsknk084sn02q title: 示例会话 environment_id: env_01h455vb4pex5vsknk084sn02q /v1/sessions/{id}: get: operationId: getSession summary: 获取会话 description: 返回单个会话，包含其资源绑定和协调者的智能体快照（含系统提示词）。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string responses: '200': description: 会话详情，携带其资源绑定与智能体快照。 content: application/json: schema: $ref: '#/components/schemas/Session' example: id: sesn_01h455vb4pex5vsknk084sn02q agent_id: agent_01h455vb4pex5vsknk084sn02q environment_id: env_01h455vb4pex5vsknk084sn02q status: idle title: 示例会话 created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 patch: operationId: updateSession summary: 更新会话 description: |- 修改会话的标题或智能体覆盖配置。仅 `title` 与 `agent_overrides` 可修改，请求体中未出现的字段保持原值。 `agent_overrides` 在下一个轮次生效。已终止（已归档）的会话拒绝更新，返回 400 `failed_precondition_error`。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string responses: '200': description: 应用了修改的会话。 content: application/json: schema: $ref: '#/components/schemas/Session' example: id: sesn_01h455vb4pex5vsknk084sn02q agent_id: agent_01h455vb4pex5vsknk084sn02q environment_id: env_01h455vb4pex5vsknk084sn02q status: idle title: 更新后的会话 created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-02T00:00:00Z' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateSessionRequest' example: title: 更新后的会话 delete: operationId: deleteSession summary: 删除会话 description: |- 永久删除一个已归档的会话及其资源绑定。 会话必须先归档，否则返回 400 `failed_precondition_error`。绑定到 `reuse_session` 模式触发器的会话，在该触发器存在期间无法删除。 存在未完成的生命周期任务或活跃线程时，返回 409 `conflict_error`。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string responses: '204': description: 会话及其资源绑定已删除。 '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 /v1/sessions/{id}/archive: post: operationId: archiveSession summary: 归档会话 description: 归档会话：将其终止并取消其线程。运行中的会话无法归档（400 `failed_precondition_error`），正在停止的会话返回 409 `conflict_error`。先发送 `user.interrupt` 事件，等待会话空闲后再归档。已归档的会话拒绝更新和新事件，但仍可读取。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string responses: '204': description: 会话已归档，其线程已取消。 '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 /v1/sessions/{id}/continue: post: operationId: continueSession summary: 继续会话 description: 恢复当前空闲且已中断的会话，不需要请求体。正在停止或已终止的会话返回 409 `conflict_error`。未中断的会话保持不变。延迟或重试的请求可能恢复后来的一次停止。等待返回的控制版本上 `continue_pending` 变为 false；更新的控制版本会取代本次请求。保留已有排队输入，本操作不添加消息。恢复 self-hosted 会话时，若 worker 租约已释放，则重新入队工作行。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string responses: '200': description: 请求后的会话控制版本。 content: application/json: schema: $ref: '#/components/schemas/SessionControlResponse' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 /v1/sessions/{id}/events: get: operationId: listSessionEvents summary: 列出会话事件 description: |- 分页返回会话的事件历史，最旧的在前——即协调者线程的事件。仅供流式传输的 `agent.delta` 事件从不出现在历史中。 使用最后一页的 `stream_cursor`，可从历史结束的位置恢复实时流。`order` 取 `*_desc` 时最新在前，此时 `page_token` 继续向更早的事件翻页。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string - name: order in: query required: false description: 列表排序方式；缺省为 `asc`（最旧在前）。取 `desc` 时最新在前，`page_token` 继续向更早的事件翻页。 schema: $ref: '#/components/schemas/EventOrder' explode: false - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页事件历史，最旧在前，携带用于恢复实时流的 `stream_cursor`。 content: application/json: schema: $ref: '#/components/schemas/SessionEventList' example: items: - id: sevt_01h455vb4pex5vsknk084sn02q processed_at: '2026-01-01T00:00:00Z' type: user.message data: content: - type: text text: Hello next_page_token: next-page-token stream_cursor: '4096' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 post: operationId: createSessionEvents summary: 向会话发送事件 description: |- 接收用户事件作为会话输入，返回 202。接受不代表已消费：待处理输入出现在「列出待处理事件」接口中，此时尚未作为 `user.message` 出现在事件历史中。 - 排队的 `user.message` 输入按到达顺序投递，每个轮次一条（`type: next_turn`，默认值），或在下一个步骤边界注入运行中的轮次（`type: steer`）。 - 已有 50 条待处理输入时，新输入返回 400 `failed_precondition_error`。等待消费或撤回排队输入后可继续发送；停止与继续操作不受限制。 - `user.interrupt` 事件停止会话及其活跃线程，空闲会话也接受停止。它不入队，且必须是请求中唯一的事件。详见其模型。 - `user.tool_confirmation` 允许或拒绝一次声明为 `always_ask` 的待处理工具调用。只需标识来源工具调用事件 ID，服务端解析 owner Thread。confirmation 不入队：请求必须只包含 `user.tool_confirmation` 事件（一条或多条，可跨线程），响应 body 为空。同一调用以第一条决定为准，之后的不同决定返回 409 `conflict_error`。 - `user.custom_tool_result` 返回由调用方执行的 Custom Tool 结果。请求必须只包含 Custom Tool result，服务端按 `event_id` 路由，事件不入队。当前 tool node 的 confirmation 和 Custom Tool result 全部解决后，Thread 恢复执行。 - 停止后接受的新消息会在收尾完成后恢复对应的控制版本，无需额外恢复参数。此前排队的输入不会自行恢复执行；它们保持待处理，直到新消息或显式继续恢复会话，再按原有 `next_turn` / `steer` 规则投递。 - 消息内容中的文件块会自动作为文件资源绑定到会话。 - 空消息以默认提示词（`Continue.`）唤醒智能体。已终止的会话拒绝输入，返回 400 `failed_precondition_error`。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string responses: '202': description: 事件已接受。返回排队输入的 `event_id`（`user.interrupt` 请求不携带）。 content: application/json: schema: $ref: '#/components/schemas/SendEventsResponse' example: event_id: sevt_01h455vb4pex5vsknk084sn02q '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '412': description: 调用方的 fencing token 已过期：工作行的租约状态已变化——重新同步后携带当前 generation 重试（仅 `work-items` 端点与受 fencing 保护的工具结果回写）。 content: application/json: schema: $ref: '#/components/schemas/PreconditionFailedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SendEventsRequest' example: type: next_turn events: - type: user.message data: content: - type: text text: Hello /v1/sessions/{id}/events/pending: get: operationId: listPendingEvents summary: 列出待处理事件 description: 按到达顺序返回会话排队中的输入事件。列表不分页。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string responses: '200': description: 按到达顺序排列的排队输入事件。 content: application/json: schema: $ref: '#/components/schemas/PendingEventList' example: items: - event_id: sevt_01h455vb4pex5vsknk084sn02q type: next_turn events: - type: user.message data: content: - type: text text: Hello queued_at: '2026-01-01T00:00:00Z' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 /v1/sessions/{id}/events/pending/{event_id}: delete: operationId: retractSessionEvent summary: 撤回待处理事件 description: 在投递前移除一个排队中的输入事件。`event_id` 已投递、已撤回或从未排队时，返回 400。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string - name: event_id in: path required: true description: 待撤回的排队输入的 ID。 schema: type: string responses: '204': description: 排队输入已撤回。 '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 /v1/sessions/{id}/events/stream: get: operationId: streamSessionEvents summary: 流式获取会话事件（SSE） description: |- 通过 Server-Sent Events 打开会话的实时事件流。 连接在事件到达期间保持打开，在客户端断开时结束。 每个帧包含： - `event:` 事件的 `type`，例如 `agent.message` - `id:` 恢复游标，可作为 `cursor` 或 `Last-Event-ID` 发送 - `data:` 单行的完整 SessionEvent JSON 完整事件按序投递。仅供流式传输的 `agent.delta` 增量预览仅在 `include_deltas=true` 时发送。 `?cursor=now` 仅接收将来的事件，流以一个携带恢复游标的 `event: control` 帧开始。会话尚无任何事件时，该游标为 `0`。服务器无法再提供的 `cursor` 会在流打开前失败，返回 400 `invalid_parameter_error`。以 `:` 开头的行必须忽略。流传输失败时发送一个最终的 `event: error` 帧，随后连接关闭。 下面的示例展示打开时的控制帧和一个事件帧（每个帧以一个空行结束）： ``` event: control id: 4096 data: {"cursor":"4096","reason":"tail"} id: 4128 event: agent.message data: {"id":"sevt_01","type":"agent.message","processed_at":"2026-01-01T00:00:00Z","data":{"content":[{"type":"text","text":"hi"}]}} : hb ``` 失败时的终止帧使用 `event: error`，错误体放在 `data:` 行上，随后流结束。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string - name: cursor in: query required: false description: 从上一个 `id:` 帧之后恢复。`now` 表示只接收将来的事件。 schema: type: string explode: false - name: include_deltas in: query required: false description: 包含仅供流式传输的 `agent.delta` 增量事件。缺省或 `false` 时只投递完整事件。 schema: type: boolean explode: false - name: Last-Event-ID in: header required: false description: 从上一个 SSE `id:` 帧之后恢复。两者同时设置时以 `cursor` 为准。 schema: type: string responses: '200': description: 实时 Server-Sent Events 事件流，帧格式见本接口说明。 headers: Cache-Control: required: true description: 恒为 `no-cache`：事件流不得缓存。 schema: type: string X-Accel-Buffering: required: true description: 恒为 `no`：提示中间层关闭响应缓冲，让帧立即刷出。 schema: type: string content: text/event-stream: itemSchema: type: object properties: event: type: string data: type: string required: - event oneOf: - title: user.message properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/UserMessageEvent' event: const: user.message - title: user.interrupt properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/UserInterruptEvent' event: const: user.interrupt - title: user.tool_confirmation properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/UserToolConfirmationEvent' event: const: user.tool_confirmation - title: user.custom_tool_result properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/UserCustomToolResultEvent' event: const: user.custom_tool_result - title: agent.message properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentMessageEvent' event: const: agent.message - title: agent.thinking properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentThinkingEvent' event: const: agent.thinking - title: agent.tool_use properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentToolUseEvent' event: const: agent.tool_use - title: agent.tool_result properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentToolResultEvent' event: const: agent.tool_result - title: agent.model_started properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentModelStartedEvent' event: const: agent.model_started - title: agent.thinking_started properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentThinkingStartedEvent' event: const: agent.thinking_started - title: agent.message_started properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentMessageStartedEvent' event: const: agent.message_started - title: agent.tool_started properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentToolStartedEvent' event: const: agent.tool_started - title: agent.custom_tool_use properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentCustomToolUseEvent' event: const: agent.custom_tool_use - title: agent.thread_message_received properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentThreadMessageReceivedEvent' event: const: agent.thread_message_received - title: agent.thread_message_sent properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentThreadMessageSentEvent' event: const: agent.thread_message_sent - title: agent.thread_context_compacted properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentThreadContextCompactedEvent' event: const: agent.thread_context_compacted - title: agent.delta properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentDeltaEvent' event: const: agent.delta - title: session.status properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/SessionStatusEvent' event: const: session.status - title: session.error properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/SessionErrorEvent' event: const: session.error - title: session.thread_created properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/SessionThreadCreatedEvent' event: const: session.thread_created - title: session.thread_status properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/SessionThreadStatusEvent' event: const: session.thread_status - title: session.title_updated properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/SessionTitleUpdatedEvent' event: const: session.title_updated - title: session.updated properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/SessionUpdatedEvent' event: const: session.updated '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 /v1/sessions/{id}/filesystem: get: operationId: listSessionFilesystem summary: 列出会话文件系统中的文件 description: |- 列出会话文件系统中一个目录的直接子项：目录在前，随后文件按名称排序。列表不递归。 `prefix` 指定相对于会话文件根目录的目录（路径首尾的斜杠会被忽略）。省略时列出根目录。上传的用户文件位于 `upload/` 下。 会话文件不保证完整持久化。智能体执行结束后仍在运行的后台进程写入的文件可能缺失或不完整，本列表也可能落后于最近的写入。需要持久、带版本的输出时，请交付为产物（Artifact）。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string - name: prefix in: query required: false description: 要列出的目录，相对于会话文件根目录。省略时列出根目录。 schema: type: string explode: false responses: '200': description: 目录的直接子项，目录在前。 content: application/json: schema: $ref: '#/components/schemas/SessionFSList' example: items: - name: report.txt size_bytes: 14 is_dir: false last_modified: '2026-08-26T12:00:00Z' path: reports/report.txt '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 /v1/sessions/{id}/filesystem/raw: get: operationId: downloadSessionFilesystemFile summary: 下载会话文件系统中的文件 description: |- 下载会话文件系统中的一个文件。`path` 为必填，取列表结果中的路径。 - **Content-Type**：使用文件存储的类型，缺失时按文件扩展名回退。可能是任意媒体类型。 - 会话文件与交付的产物（Artifact）是不同的资源。会话文件不保证完整持久化；产物是持久、带版本的交付路径。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string - name: path in: query required: true description: 会话文件系统列表返回的路径。 schema: type: string explode: false responses: '200': description: 文件的内容字节。 content: '*/*': schema: contentMediaType: '*/*' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 /v1/sessions/{id}/resources: get: operationId: listSessionResources summary: 列出会话资源 description: 返回绑定到会话的资源，每项都带有服务端分配的绑定 `id`。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页已绑定的资源。 content: application/json: schema: $ref: '#/components/schemas/SessionResourceList' example: items: - type: file id: sres_01h455vb4pex5vsknk084sn02q file_id: file_01h455vb4pex5vsknk084sn02q next_page_token: next-page-token '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 post: operationId: addSessionResource summary: 添加会话资源 description: |- 将一个已上传的文件绑定到会话，并返回该绑定。 创建后只能添加文件。凭据库（Vault）与记忆库的绑定在会话创建时即已固定。重复绑定同一文件，或文件名在工作区中冲突，将返回 409 `conflict_error`。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string responses: '201': description: 已创建的资源绑定，携带分配的 `id`。 content: application/json: schema: $ref: '#/components/schemas/SessionResource' example: type: file id: sres_01h455vb4pex5vsknk084sn02q file_id: file_01h455vb4pex5vsknk084sn02q '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AddSessionResourceRequest' example: type: file file_id: file_01h455vb4pex5vsknk084sn02q /v1/sessions/{id}/resources/{resource_id}: get: operationId: getSessionResource summary: 获取会话资源 description: 返回会话的一个资源绑定。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string - name: resource_id in: path required: true description: 会话资源绑定 ID。 schema: type: string responses: '200': description: 资源绑定详情。 content: application/json: schema: $ref: '#/components/schemas/SessionResource' example: type: file id: sres_01h455vb4pex5vsknk084sn02q file_id: file_01h455vb4pex5vsknk084sn02q '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 delete: operationId: deleteSessionResource summary: 移除会话资源 description: 从会话中移除一个资源绑定。对于文件，工作区中的链接会一并移除。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string - name: resource_id in: path required: true description: 会话资源绑定 ID。 schema: type: string responses: '204': description: 资源绑定已移除。 '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 /v1/sessions/{id}/threads: get: operationId: listSessionThreads summary: 列出会话的线程 description: 返回会话的线程：协调者在前，随后按创建顺序列出子线程，每个线程都带有固定的智能体快照。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页线程，协调者在前。 content: application/json: schema: $ref: '#/components/schemas/SessionThreadList' example: items: - id: sthr_01h455vb4pex5vsknk084sn02q session_id: sesn_01h455vb4pex5vsknk084sn02q status: idle created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' next_page_token: next-page-token '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 /v1/sessions/{id}/threads/{thread_id}: get: operationId: getSessionThread summary: 获取会话的线程 description: 返回会话的一个线程，包含其固定的智能体快照。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string - name: thread_id in: path required: true description: 线程 ID。 schema: type: string responses: '200': description: 线程详情，携带其固定的智能体快照。 content: application/json: schema: $ref: '#/components/schemas/SessionThread' example: id: sthr_01h455vb4pex5vsknk084sn02q session_id: sesn_01h455vb4pex5vsknk084sn02q status: idle created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 /v1/sessions/{id}/threads/{thread_id}/archive: post: operationId: archiveSessionThread summary: 归档会话的线程 description: 终止子线程并取消其当前执行，会话正在停止时也允许操作。对协调者返回 400 `failed_precondition_error`，应改为归档会话。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string - name: thread_id in: path required: true description: 线程 ID。 schema: type: string responses: '204': description: 线程已归档。 '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 /v1/sessions/{id}/threads/{thread_id}/events: get: operationId: listThreadEvents summary: 列出线程事件 description: 分页返回单个线程的事件历史，最旧的在前。会话级接口返回协调者线程的历史。`order` 取 `*_desc` 时最新在前，此时 `page_token` 继续向更早的事件翻页。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string - name: thread_id in: path required: true description: 线程 ID。 schema: type: string - name: order in: query required: false description: 列表排序方式；缺省为 `asc`（最旧在前）。取 `desc` 时最新在前，`page_token` 继续向更早的事件翻页。 schema: $ref: '#/components/schemas/EventOrder' explode: false - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页线程的事件历史，最旧在前。 content: application/json: schema: $ref: '#/components/schemas/SessionEventList' example: items: - id: sevt_01h455vb4pex5vsknk084sn02q processed_at: '2026-01-01T00:00:00Z' session_thread_id: sthr_01h455vb4pex5vsknk084sn02q type: agent.message data: content: - type: text text: Hello next_page_token: next-page-token stream_cursor: '4096' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 /v1/sessions/{id}/threads/{thread_id}/events/stream: get: operationId: streamThreadEvents summary: 流式获取线程事件（SSE） description: 通过 Server-Sent Events 订阅一个线程的实时公开事件流。帧格式、增量投递与游标语义均与会话事件流相同。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 会话 ID。 schema: type: string - name: thread_id in: path required: true description: 线程 ID。 schema: type: string - name: cursor in: query required: false description: 从上一个 `id:` 帧之后恢复。`now` 表示只接收将来的事件。 schema: type: string explode: false - name: include_deltas in: query required: false description: 包含仅供流式传输的 `agent.delta` 增量事件。缺省或 `false` 时只投递完整事件。 schema: type: boolean explode: false - name: Last-Event-ID in: header required: false description: 从上一个 SSE `id:` 帧之后恢复。两者同时设置时以 `cursor` 为准。 schema: type: string responses: '200': description: 线程的实时 Server-Sent Events 事件流。 headers: Cache-Control: required: true description: 恒为 `no-cache`：事件流不得缓存。 schema: type: string X-Accel-Buffering: required: true description: 恒为 `no`：提示中间层关闭响应缓冲，让帧立即刷出。 schema: type: string content: text/event-stream: itemSchema: type: object properties: event: type: string data: type: string required: - event oneOf: - title: user.message properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/UserMessageEvent' event: const: user.message - title: user.interrupt properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/UserInterruptEvent' event: const: user.interrupt - title: user.tool_confirmation properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/UserToolConfirmationEvent' event: const: user.tool_confirmation - title: user.custom_tool_result properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/UserCustomToolResultEvent' event: const: user.custom_tool_result - title: agent.message properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentMessageEvent' event: const: agent.message - title: agent.thinking properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentThinkingEvent' event: const: agent.thinking - title: agent.tool_use properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentToolUseEvent' event: const: agent.tool_use - title: agent.tool_result properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentToolResultEvent' event: const: agent.tool_result - title: agent.model_started properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentModelStartedEvent' event: const: agent.model_started - title: agent.thinking_started properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentThinkingStartedEvent' event: const: agent.thinking_started - title: agent.message_started properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentMessageStartedEvent' event: const: agent.message_started - title: agent.tool_started properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentToolStartedEvent' event: const: agent.tool_started - title: agent.custom_tool_use properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentCustomToolUseEvent' event: const: agent.custom_tool_use - title: agent.thread_message_received properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentThreadMessageReceivedEvent' event: const: agent.thread_message_received - title: agent.thread_message_sent properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentThreadMessageSentEvent' event: const: agent.thread_message_sent - title: agent.thread_context_compacted properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentThreadContextCompactedEvent' event: const: agent.thread_context_compacted - title: agent.delta properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/AgentDeltaEvent' event: const: agent.delta - title: session.status properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/SessionStatusEvent' event: const: session.status - title: session.error properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/SessionErrorEvent' event: const: session.error - title: session.thread_created properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/SessionThreadCreatedEvent' event: const: session.thread_created - title: session.thread_status properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/SessionThreadStatusEvent' event: const: session.thread_status - title: session.title_updated properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/SessionTitleUpdatedEvent' event: const: session.title_updated - title: session.updated properties: data: contentMediaType: application/json contentSchema: $ref: '#/components/schemas/SessionUpdatedEvent' event: const: session.updated '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 会话 /v1/skills: get: operationId: listSkills summary: 列出技能 description: 返回调用方项目的技能与已启用的官方技能，按创建时间升序排列。已归档的技能不会列出。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: category in: query required: false description: 按展示分类过滤。 schema: $ref: '#/components/schemas/SkillCategory' explode: false - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页技能，按创建时间升序。 content: application/json: schema: $ref: '#/components/schemas/SkillList' example: items: [] next_page_token: page_next_example '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 技能 post: operationId: createSkill summary: 创建技能 description: |- 通过 `.zip` 或 `.skill` 包上传创建项目拥有的技能及其第一个不可变版本。 - 包大小不超过 64 MiB（展开后 128 MiB、256 个文件），且必须恰好包含一个 SKILL.md，其 frontmatter 声明 `name` 与 `description`。 - 该名称不得属于项目中另一个活跃技能（409 `conflict_error`）。归档技能会释放其名称。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - $ref: '#/components/parameters/IdempotencyKeyHeader' responses: '201': description: 已创建的技能及其首个不可变版本。 content: application/json: schema: $ref: '#/components/schemas/CreateSkillResponse' example: skill: id: 0198f2c4-7b3a-7f2e-9c1d-4e5f6a7b8c9d name: data-analysis description: 分析表格数据并生成摘要。 latest_version: '1' status: active created_at: '2026-08-01T10:00:00Z' updated_at: '2026-08-01T10:00:00Z' scope: project version: skill_id: 0198f2c4-7b3a-7f2e-9c1d-4e5f6a7b8c9d version: '1' name: data-analysis description: 分析表格数据并生成摘要。 created_at: '2026-08-01T10:00:00Z' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 技能 requestBody: required: true content: multipart/form-data: schema: type: object properties: file: description: 技能包归档。 required: - file encoding: file: contentType: '*/*' example: {} /v1/skills/{id}: get: operationId: getSkill summary: 获取技能 description: 返回单个技能。已归档的技能返回 404。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 技能 ID。 schema: type: string responses: '200': description: 技能的目录条目。 content: application/json: schema: $ref: '#/components/schemas/Skill' example: id: 0198f2c4-7b3a-7f2e-9c1d-4e5f6a7b8c9d name: data-analysis description: 分析表格数据并生成摘要。 latest_version: '1' status: active created_at: '2026-08-01T10:00:00Z' updated_at: '2026-08-01T10:00:00Z' scope: project '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 技能 delete: operationId: deleteSkill summary: 删除技能 description: |- 删除一个项目拥有的技能——等同于 `POST /v1/skills/{id}/archive`。 已归档的技能不能被新的智能体版本引用，并从读取 API 中消失（获取、列表与版本内容均返回 404）。持有精确版本引用的智能体可继续正常工作。官方技能不能通过此 API 归档。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 技能 ID。 schema: type: string responses: '204': description: 技能已归档。 '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '403': description: 调用方无权执行该操作，例如操作他人所有的资源。 content: application/json: schema: $ref: '#/components/schemas/ForbiddenErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 技能 /v1/skills/{id}/archive: post: operationId: archiveSkill summary: 归档技能 description: |- 归档一个项目拥有的技能。`DELETE /v1/skills/{id}` 是该操作的别名。 已归档的技能不能被新的智能体版本引用，并从读取 API 中消失（获取、列表与版本内容均返回 404）。持有精确版本引用的智能体可继续正常工作。官方技能不能通过此 API 归档。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 技能 ID。 schema: type: string responses: '204': description: 技能已归档。 '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '403': description: 调用方无权执行该操作，例如操作他人所有的资源。 content: application/json: schema: $ref: '#/components/schemas/ForbiddenErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 技能 /v1/skills/{id}/versions: get: operationId: listSkillVersions summary: 列出技能版本 description: 返回技能的不可变版本，最新在前。已归档技能的版本仍可列出。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 技能 ID。 schema: type: string - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页技能版本，最新在前。 content: application/json: schema: $ref: '#/components/schemas/SkillVersionList' example: items: - skill_id: 0198f2c4-7b3a-7f2e-9c1d-4e5f6a7b8c9d version: '1' name: data-analysis description: 分析表格数据并生成摘要。 created_at: '2026-08-01T10:00:00Z' next_page_token: page_next_example '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 技能 /v1/skills/{id}/versions/{version}/content: get: operationId: getSkillVersionContent summary: 获取技能版本内容 description: 下载指定确切版本的原始 SKILL.md 指令（`version` 必须是数字版本号，不能是 `latest`）。响应始终为 `text/markdown`。已归档的技能返回 404。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 技能 ID。 schema: type: string - name: version in: path required: true description: 确切的数字技能版本号，例如 `"1"`。 schema: type: string responses: '200': description: 原始 SKILL.md 字节（`text/markdown`）。 content: text/markdown: schema: contentMediaType: text/markdown '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 技能 /v1/triggers: get: operationId: listTriggers summary: 列出触发器 description: 返回调用方的触发器，最新在前。不设置 `status` 时不包含已归档的触发器。`policy_type` 按策略类型筛选，`agent_id` 按所属 Agent 筛选。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: status in: query required: false description: 按生命周期状态筛选。省略时不包含已归档的触发器。 schema: $ref: '#/components/schemas/TriggerStatus' explode: false - name: policy_type in: query required: false description: 按策略类型筛选。 schema: $ref: '#/components/schemas/TriggerPolicyType' explode: false - name: agent_id in: query required: false description: 按所属 Agent 筛选。 schema: type: string explode: false - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页触发器，最新在前。 content: application/json: schema: $ref: '#/components/schemas/TriggerList' example: items: - id: trig_01h455vb4pex5vsknk084sn02q name: Daily summary status: active agent_id: agent_01h455vb4pex5vsknk084sn02q session_mode: new_session policy: type: cron expression: 0 9 * * * timezone: UTC scope: project created_by: user_example created_at: '2026-08-01T09:00:00Z' updated_at: '2026-08-01T09:00:00Z' next_page_token: page-next-example '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 触发器 post: operationId: createTrigger summary: 创建触发器 description: |- 创建一个处于活跃状态的触发器，为智能体启动会话。 - cron 策略接受分钟粒度的五字段表达式和一个 IANA `timezone`。实际触发会加入少量抖动。 - 智能体、环境、凭据库与记忆库引用在创建时校验。一个项目最多持有 200 个未归档的触发器。 - 每次触发向本次运行的会话投递 `initial_events` 和一条平台上下文消息。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - $ref: '#/components/parameters/IdempotencyKeyHeader' responses: '201': description: 已创建的触发器（活跃状态）。 content: application/json: schema: $ref: '#/components/schemas/Trigger' example: id: trig_01h455vb4pex5vsknk084sn02q name: Daily summary status: active agent_id: agent_01h455vb4pex5vsknk084sn02q session_mode: new_session policy: type: cron expression: 0 9 * * * timezone: UTC scope: project created_by: user_example created_at: '2026-08-01T09:00:00Z' updated_at: '2026-08-01T09:00:00Z' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 触发器 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateTriggerRequest' example: name: Daily summary agent_id: agent_01h455vb4pex5vsknk084sn02q environment_id: env_01h455vb4pex5vsknk084sn02q session_mode: new_session policy: type: cron expression: 0 9 * * * timezone: UTC /v1/triggers/{id}: get: operationId: getTrigger summary: 获取触发器 description: 返回单个触发器。cron 策略处于活跃状态时包含即将到来的运行时间。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 触发器 ID。 schema: type: string responses: '200': description: 触发器详情。cron 策略活跃时携带即将到来的运行时间。 content: application/json: schema: $ref: '#/components/schemas/Trigger' example: id: trig_01h455vb4pex5vsknk084sn02q name: Daily summary status: active agent_id: agent_01h455vb4pex5vsknk084sn02q session_mode: new_session policy: type: cron expression: 0 9 * * * timezone: UTC scope: project created_by: user_example created_at: '2026-08-01T09:00:00Z' updated_at: '2026-08-01T09:00:00Z' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 触发器 patch: operationId: updateTrigger summary: 更新触发器 description: |- 仅修改请求体中出现的字段。传入空对象或空数组可清空集合，`null` 值会被拒绝（400 `invalid_parameter_error`）。状态变更通过暂停、恢复与归档操作进行。 更新后的 `initial_events` 必须全部为 `user.message`。若旧触发器包含其他事件类型，即使只修改无关字段，也须同时将 `initial_events` 替换为合法列表或 `[]`，否则返回 400 `invalid_parameter_error`。 将 `session_mode` 从 `reuse_session` 切换为其他值会释放平台管理的会话绑定。触发器保持 `reuse_session` 时，其托管会话沿用创建时的智能体、环境与资源，因此修改 `agent_id`、`agent_version`、`environment_id` 或 `resources` 返回 400 `failed_precondition_error`；与当前值相同的取值会被接受。需要修改时，先将 `session_mode` 切换为 `new_session`，或新建触发器。平台管理的触发器（`origin_type` 已设置）与已归档的触发器拒绝更新，返回 400 `failed_precondition_error`。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 触发器 ID。 schema: type: string responses: '200': description: 应用了修改的触发器。 content: application/json: schema: $ref: '#/components/schemas/Trigger' example: id: trig_01h455vb4pex5vsknk084sn02q name: Updated daily summary status: active agent_id: agent_01h455vb4pex5vsknk084sn02q session_mode: new_session policy: type: cron expression: 0 9 * * * timezone: UTC scope: project created_by: user_example created_at: '2026-08-01T09:00:00Z' updated_at: '2026-08-01T09:30:00Z' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 触发器 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateTriggerRequest' example: name: Updated daily summary /v1/triggers/{id}/archive: post: operationId: archiveTrigger summary: 归档触发器 description: |- 永久归档触发器：归档后不再触发，`reuse_session` 绑定被释放，运行记录保留。 归档已归档的触发器为空操作。平台管理的触发器（`origin_type` 已设置，例如 Dreams 策略的触发器）不能执行此操作，返回 400 `failed_precondition_error`。其生命周期跟随所属资源。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 触发器 ID。 schema: type: string responses: '204': description: 触发器已归档。 '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 触发器 /v1/triggers/{id}/pause: post: operationId: pauseTrigger summary: 暂停触发器 description: 停止计划运行。暂停期间触发器不参与调度，原本会触发的时刻不产生运行记录。进行中的运行不受影响，仍可手动运行。暂停已暂停的触发器为空操作。平台管理的触发器（`origin_type` 已设置）与已归档的触发器会被拒绝，返回 400 `failed_precondition_error`。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 触发器 ID。 schema: type: string responses: '204': description: 触发器已暂停（已暂停时为空操作）。 '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 触发器 /v1/triggers/{id}/run: post: operationId: runTrigger summary: 运行触发器 description: |- 立即触发一次触发器——包括已暂停的触发器——并同步执行，返回终态的触发器运行记录（`completed`、`failed` 或 `skipped`）。 `completed` 表示会话已创建且开场事件已被接受。不涵盖智能体的任务结果。已归档的触发器，或已有另一次运行正在进行时，返回 400 `failed_precondition_error`。`reuse_session` 运行发现平台管理的会话仍在执行上一次运行时，返回 `skipped` 与 `overlap_in_flight`。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 触发器 ID。 schema: type: string - $ref: '#/components/parameters/IdempotencyKeyHeader' responses: '201': description: 终态的触发器运行记录（`completed`、`failed` 或 `skipped`）。 content: application/json: schema: $ref: '#/components/schemas/TriggerRun' example: id: trun_01h455vb4pex5vsknk084sn02q trigger_id: trig_01h455vb4pex5vsknk084sn02q status: completed created_at: '2026-08-01T09:00:00Z' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 触发器 requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/RunTriggerRequest' example: payload: Run the daily summary. /v1/triggers/{id}/runs: get: operationId: listTriggerRuns summary: 列出触发器运行 description: 返回一个触发器的运行记录，最新在前。用 `has_error` 可只筛出失败的运行。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 触发器 ID。 schema: type: string - name: has_error in: query required: false description: 筛选有失败的触发器运行（`true`）或无失败的（`false`）。 schema: type: boolean explode: false - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页触发器运行，最新在前。 content: application/json: schema: $ref: '#/components/schemas/TriggerRunList' example: items: - id: trun_01h455vb4pex5vsknk084sn02q trigger_id: trig_01h455vb4pex5vsknk084sn02q status: completed session_id: sesn_01h455vb4pex5vsknk084sn02q created_at: '2026-08-01T09:00:00Z' finished_at: '2026-08-01T09:01:00Z' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 触发器 /v1/triggers/{id}/runs/{run_id}: get: operationId: getTriggerRun summary: 获取触发器运行 description: 返回单次触发器运行。属于其他触发器的运行返回 404。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 触发器 ID。 schema: type: string - name: run_id in: path required: true description: 触发器运行 ID。 schema: type: string responses: '200': description: 触发器运行的记录。 content: application/json: schema: $ref: '#/components/schemas/TriggerRun' example: id: trun_01h455vb4pex5vsknk084sn02q trigger_id: trig_01h455vb4pex5vsknk084sn02q status: completed session_id: sesn_01h455vb4pex5vsknk084sn02q created_at: '2026-08-01T09:00:00Z' finished_at: '2026-08-01T09:01:00Z' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 触发器 /v1/triggers/{id}/unpause: post: operationId: unpauseTrigger summary: 恢复触发器 description: 恢复已暂停触发器的计划运行。调度从当前时刻重新开始——暂停期间错过的运行不会补跑。恢复活跃的触发器为空操作。平台管理的触发器（`origin_type` 已设置）与已归档的触发器会被拒绝，返回 400 `failed_precondition_error`。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 触发器 ID。 schema: type: string responses: '204': description: 触发器已恢复。 '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 触发器 /v1/vaults: post: operationId: createVault summary: 创建凭据库（Vault） description: |- 创建一个凭据库（Vault），用于将凭据分组以绑定到会话。 `display_name` 不要求唯一。凭据库（Vault）创建时为空，可用 `POST /v1/vaults/{id}/credentials` 添加凭据。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - $ref: '#/components/parameters/IdempotencyKeyHeader' responses: '201': description: 已创建的凭据库（Vault）。 content: application/json: schema: $ref: '#/components/schemas/Vault' example: id: vlt_01h455vb4pex5vsknk084sn02q display_name: Production credentials created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 凭据库 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateVaultRequest' example: display_name: Production credentials get: operationId: listVaults summary: 列出凭据库（Vault） description: 返回调用方的凭据库（Vault），最新者在前。除非 `include_archived` 为 true，否则不包含已归档的凭据库。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: include_archived in: query required: false description: 包含已归档的凭据库（Vault）。省略时不包含。 schema: type: boolean explode: false - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页凭据库（Vault），最新者在前。 content: application/json: schema: $ref: '#/components/schemas/VaultList' example: items: - id: vlt_01h455vb4pex5vsknk084sn02q display_name: Production credentials created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' next_page_token: next-page-token '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 凭据库 /v1/vaults/credentials/check: post: operationId: checkVaultCredentials summary: 检查凭据覆盖情况 description: |- 按请求顺序，报告每个请求的 MCP 服务器 URL 分别在哪些凭据库（Vault）中持有活跃凭据。 - 只有 `mcp_oauth` 和 `static_bearer` 凭据计入覆盖。`environment_variable` 凭据从不作为覆盖出现。 - 每个 URL 在匹配前会做规范化。规范化失败的 URL 不报任何匹配。 - 省略 `vault_ids` 时，搜索调用方可见的所有凭据库（Vault）。 parameters: - $ref: '#/components/parameters/APIVersionHeader' responses: '200': description: 按请求顺序排列的覆盖结果。 content: application/json: schema: $ref: '#/components/schemas/CheckVaultCredentialsResponse' example: coverage: - mcp_server_url: https://example.invalid/mcp matching_vault_ids: - vlt_01h455vb4pex5vsknk084sn02q '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 凭据库 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CheckVaultCredentialsRequest' example: mcp_server_urls: - https://example.invalid/mcp vault_ids: - vlt_01h455vb4pex5vsknk084sn02q /v1/vaults/{id}: get: operationId: getVault summary: 获取凭据库（Vault） description: 返回一个凭据库（Vault）的元数据。已归档的凭据库（Vault）仍可读取。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 凭据库（Vault）ID。 schema: type: string responses: '200': description: 凭据库（Vault）的元数据。 content: application/json: schema: $ref: '#/components/schemas/Vault' example: id: vlt_01h455vb4pex5vsknk084sn02q display_name: Production credentials created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 凭据库 patch: operationId: updateVault summary: 更新凭据库（Vault） description: |- 重命名凭据库（Vault）或替换其元数据。请求体中未出现的字段保持当前值。 - `metadata` 整体替换整个映射。传入空对象则清空。 - 空的部分更新请求返回 400 `invalid_request_error`。已归档的凭据库（Vault）拒绝更新，返回 400 `failed_precondition_error`。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 凭据库（Vault）ID。 schema: type: string responses: '200': description: 应用了修改的凭据库（Vault）。 content: application/json: schema: $ref: '#/components/schemas/Vault' example: id: vlt_01h455vb4pex5vsknk084sn02q display_name: Updated credentials created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-02T00:00:00Z' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 凭据库 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateVaultRequest' example: display_name: Updated credentials delete: operationId: deleteVault summary: 删除凭据库（Vault） description: |- 永久删除一个已归档的凭据库（Vault）及其全部凭据。 凭据库（Vault）必须先归档（否则返回 400 `failed_precondition_error`）。归档保留元数据记录，删除则移除记录。仍绑定到该凭据库（Vault）的会话不会被检查，并将失去对其凭据的访问。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 凭据库（Vault）ID。 schema: type: string responses: '204': description: 凭据库（Vault）及其全部凭据已删除。 '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 凭据库 /v1/vaults/{id}/archive: post: operationId: archiveVault summary: 归档凭据库（Vault） description: 归档凭据库（Vault）及其全部活跃凭据，并清除其秘密值。已归档的凭据不再对会话可用。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 凭据库（Vault）ID。 schema: type: string responses: '204': description: 凭据库（Vault）及其活跃凭据已归档。 '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 凭据库 /v1/vaults/{id}/credentials: post: operationId: createVaultCredential summary: 创建凭据 description: |- 在凭据库（Vault）中存储一条凭据。秘密值为只写：仅在请求中接受，静态加密存储，且在任何响应中都不返回。 - 凭据的唯一键——`mcp_oauth`/`static_bearer` 为规范化后的 `mcp_server_url`，`environment_variable` 为 `secret_name`——不得与凭据库（Vault）中的另一条活跃凭据冲突（409 `conflict_error`）。 - 一个凭据库（Vault）最多持有 20 条活跃凭据（400 `failed_precondition_error`）。已归档的凭据库（Vault）拒绝新凭据。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 凭据库（Vault）ID。 schema: type: string responses: '201': description: 已创建的凭据，秘密值不返回。 content: application/json: schema: $ref: '#/components/schemas/VaultCredential' example: id: vcrd_01h455vb4pex5vsknk084sn02q vault_id: vlt_01h455vb4pex5vsknk084sn02q display_name: MCP access auth: type: static_bearer mcp_server_url: https://example.invalid/mcp created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 凭据库 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateVaultCredentialRequest' example: display_name: MCP access auth: type: static_bearer mcp_server_url: https://example.invalid/mcp token: sk-example get: operationId: listVaultCredentials summary: 列出凭据 description: 返回凭据库（Vault）中的凭据，最新者在前，秘密值不返回。除非 `include_archived` 为 true，否则不包含已归档的凭据。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 凭据库（Vault）ID。 schema: type: string - name: include_archived in: query required: false description: 包含已归档的凭据。省略时不包含。 schema: type: boolean explode: false - $ref: '#/components/parameters/PaginationQuery.page_size' - $ref: '#/components/parameters/PaginationQuery.page_token' responses: '200': description: 一页凭据，最新者在前，秘密值不返回。 content: application/json: schema: $ref: '#/components/schemas/VaultCredentialList' example: items: - id: vcrd_01h455vb4pex5vsknk084sn02q vault_id: vlt_01h455vb4pex5vsknk084sn02q display_name: MCP access auth: type: static_bearer mcp_server_url: https://example.invalid/mcp created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' next_page_token: next-page-token '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 凭据库 /v1/vaults/{id}/credentials/batch: post: operationId: batchCreateVaultCredentials summary: 批量创建凭据 description: |- 以原子方式创建 1–20 条凭据：任一条目校验失败则全部不创建。 每个条目遵循单条创建规则，并计入凭据库（Vault）的 20 条活跃凭据上限。批次内出现重复键返回 400 `invalid_request_error`。响应按请求顺序列出已创建的凭据。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 凭据库（Vault）ID。 schema: type: string responses: '201': description: 按请求顺序创建的凭据，秘密值不返回。 content: application/json: schema: $ref: '#/components/schemas/BatchCreateVaultCredentialsResponse' example: items: - id: vcrd_01h455vb4pex5vsknk084sn02q vault_id: vlt_01h455vb4pex5vsknk084sn02q display_name: MCP access auth: type: static_bearer mcp_server_url: https://example.invalid/mcp created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '409': description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 凭据库 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchCreateVaultCredentialsRequest' example: items: - display_name: MCP access auth: type: static_bearer mcp_server_url: https://example.invalid/mcp token: sk-example /v1/vaults/{id}/credentials/{credential_id}: get: operationId: getVaultCredential summary: 获取凭据 description: 返回一条凭据的非秘密设置。秘密值不返回。已归档的凭据仍可读取。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 凭据库（Vault）ID。 schema: type: string - name: credential_id in: path required: true description: 凭据 ID。 schema: type: string responses: '200': description: 凭据详情，秘密值不返回。 content: application/json: schema: $ref: '#/components/schemas/VaultCredential' example: id: vcrd_01h455vb4pex5vsknk084sn02q vault_id: vlt_01h455vb4pex5vsknk084sn02q display_name: MCP access auth: type: static_bearer mcp_server_url: https://example.invalid/mcp created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-01T00:00:00Z' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 凭据库 patch: operationId: updateVaultCredential summary: 更新凭据 description: |- 重命名凭据或轮换其秘密设置。 字段按字段合并（见 `UpdateVaultCredentialRequest`）：秘密值不能清空为空，凭据类型及其标识字段不可变更。刷新出现终态失败后，轮换 `access_token` 或 `refresh_token` 可恢复托管刷新。更新已归档的凭据返回 404。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 凭据库（Vault）ID。 schema: type: string - name: credential_id in: path required: true description: 凭据 ID。 schema: type: string responses: '200': description: 更新后的凭据，秘密值不返回。 content: application/json: schema: $ref: '#/components/schemas/VaultCredential' example: id: vcrd_01h455vb4pex5vsknk084sn02q vault_id: vlt_01h455vb4pex5vsknk084sn02q display_name: Updated MCP access auth: type: static_bearer mcp_server_url: https://example.invalid/mcp created_at: '2026-01-01T00:00:00Z' updated_at: '2026-01-02T00:00:00Z' '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 凭据库 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateVaultCredentialRequest' example: display_name: Updated MCP access delete: operationId: deleteVaultCredential summary: 删除凭据 description: 永久删除一条已归档的凭据。凭据必须先归档（否则返回 400 `failed_precondition_error`）。需要保留记录时请使用归档。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 凭据库（Vault）ID。 schema: type: string - name: credential_id in: path required: true description: 凭据 ID。 schema: type: string responses: '204': description: 凭据已删除。 '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 凭据库 /v1/vaults/{id}/credentials/{credential_id}/archive: post: operationId: archiveVaultCredential summary: 归档凭据 description: 归档凭据，清除其秘密值并释放其唯一键，可用于新建替代凭据。已归档的凭据不再对会话可用，但仍可读取。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 凭据库（Vault）ID。 schema: type: string - name: credential_id in: path required: true description: 凭据 ID。 schema: type: string responses: '204': description: 凭据已归档，秘密值已清除。 '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 凭据库 /v1/vaults/{id}/oauth-sessions: post: operationId: createVaultOAuthSession summary: 创建 OAuth 会话 description: |- 为一个 MCP 服务器发起 OAuth 授权流程，并返回需在浏览器中打开的 URL。完成授权会在凭据库（Vault）中创建一条 `mcp_oauth` 凭据。 - 省略 `client` 时，会通过动态客户端注册自动注册一个客户端。`client.scope` 会替换探测到的权限范围。 - 同一服务器已有进行中的授权流程时再次发起，返回该进行中的 OAuth 会话。同一服务器 URL 已有活跃凭据时返回 409 `conflict_error`——先归档该凭据再重新授权。 - 用 `GET /v1/vaults/{id}/oauth-sessions/{session_id}` 轮询结果。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 凭据库（Vault）ID。 schema: type: string responses: '201': description: OAuth 会话 ID 与待打开的 `authorize_url`。 content: application/json: schema: $ref: '#/components/schemas/CreateVaultOAuthSessionResponse' example: oauth_session_id: voss_01h455vb4pex5vsknk084sn02q authorize_url: https://example.invalid/authorize mcp_server_url: https://example.invalid/mcp '400': description: 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '409': description: 凭据库（Vault）已持有同一规范化服务器 URL（`mcp_oauth` 或 `static_bearer`）的活跃凭据。先归档该凭据再重新授权。`POST /v1/vaults/credentials/check` 可在不发起流程的情况下预检覆盖情况。 content: application/json: schema: $ref: '#/components/schemas/VaultOAuthSessionConflictErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 凭据库 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateVaultOAuthSessionRequest' example: mcp_server_url: https://example.invalid/mcp display_name: MCP access client: client_id: client-example /v1/vaults/{id}/oauth-sessions/{session_id}: get: operationId: getVaultOAuthSession summary: 获取 OAuth 会话 description: 返回 OAuth 授权流程的当前状态：进行中为 `pending`。成功为 `authorized`，并携带已创建的 `credential_id`。失败为 `failed`，并携带人类可读的 `error`。未知或已过期的 OAuth 会话返回 404。 parameters: - $ref: '#/components/parameters/APIVersionHeader' - name: id in: path required: true description: 凭据库（Vault）ID。 schema: type: string - name: session_id in: path required: true description: OAuth 会话 ID。 schema: type: string responses: '200': description: 当前授权状态（`pending`、`authorized` 携带 `credential_id`，或 `failed` 携带 `error`）。 content: application/json: schema: $ref: '#/components/schemas/VaultOAuthSession' example: status: authorized credential_id: vcrd_01h455vb4pex5vsknk084sn02q '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 headers: Retry-After: required: false description: 重试前需要等待的秒数。仅当 `error.type` 为 `rate_limit_reached_error` 时携带；配额错误不携带该响应头。 schema: type: integer format: int32 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' tags: - 凭据库 security: - BearerAuth: [] components: parameters: APIVersionHeader: name: kimi-api-version in: header required: false description: 本次请求使用的 API 版本，格式为 `YYYY-MM-DD`。发送 `2026-09-01-beta` 即使用本文档所述版本。`/v1/files*` 之外必传：未携带请求头将被拒绝并返回 400 `invalid_request_error`；在 `/v1/files*` 上缺省时选择兼容行为。所有端点对未知取值均返回 400 `invalid_request_error`。 schema: $ref: '#/components/schemas/APIVersion' IdempotencyKeyHeader: name: Idempotency-Key in: header required: false description: 可选的幂等键。相同的键与请求体会在 24 小时内重放首个响应；以不同的请求体复用，或在首个请求仍在处理时复用，返回 409。 schema: type: string PaginationQuery.page_size: name: page_size in: query required: false description: 返回的条目数，1 到 1000（默认 50）。 schema: type: integer format: int32 minimum: 1 maximum: 1000 default: 50 explode: false PaginationQuery.page_token: name: page_token in: query required: false description: 来自上一次响应 `next_page_token` 的不透明分页令牌。 schema: type: string explode: false schemas: APIError: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' description: 错误详情。 APIVersion: type: string enum: - 2026-09-01-beta description: 平台当前支持的 API 版本。新的日期版本发布时加入；版本在公告的 Sunset 日期后移除。 AckWorkItemRequest: type: object required: - worker_id - generation properties: worker_id: type: string minLength: 1 description: 持有租约的 worker。 generation: type: integer format: int64 minimum: 1 description: 投递时返回的 fencing token。 description: '`POST /v1/environments/{environment_id}/work/{id}/ack` 的请求体。' AddSessionResourceRequest: type: object required: - type - file_id properties: type: type: string enum: - file description: 资源类型。创建后只能添加文件资源。 file_id: type: string description: 要挂载的已上传文件 ID。 description: 为会话添加文件资源的请求体。凭据库（Vault）和记忆库的绑定在创建时即已固定。 Agent: type: object required: - id - name - model - version - created_at - updated_at - scope properties: id: type: string description: 智能体 ID。 name: type: string description: 人类可读的智能体名称。 model: $ref: '#/components/schemas/ModelRef' description: 所选模型。 description: type: string description: 可选的人类可读描述。 system: type: string description: 系统提示词。 tools: type: array items: $ref: '#/components/schemas/Tool' description: 智能体可用的工具。 mcp_servers: type: array items: $ref: '#/components/schemas/McpServer' description: 智能体可用的 MCP 服务器连接。 skills: type: array items: $ref: '#/components/schemas/SkillRef' description: 智能体可用的技能版本。空版本在写入时冻结；"latest" 原样保留，每次唤醒现解最新版。 plugins: type: array items: $ref: '#/components/schemas/PluginRef' description: 智能体可用的插件，在写入时冻结。 metadata: $ref: '#/components/schemas/StringMetadata' description: 用户自定义元数据（最多 16 条）。 version: type: string description: 智能体当前的不可变版本。 created_at: type: string format: date-time description: 创建时间戳。 updated_at: type: string format: date-time description: 最后更新时间戳。 archived_at: type: string format: date-time description: 归档时间戳。处于活跃状态时不存在。 scope: $ref: '#/components/schemas/ResourceScope' description: 可见性范围。 multiagent: $ref: '#/components/schemas/Multiagent' description: 解析后的子智能体配置。单智能体时不存在。 description: 持久化的、带版本管理的智能体配置。 AgentCustomToolUseEvent: type: object required: - id - processed_at - type - data properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - agent.custom_tool_use data: $ref: '#/components/schemas/AgentCustomToolUsePayload' description: 智能体请求 API 调用方执行一次自定义工具调用。 title: 自定义工具调用 AgentCustomToolUsePayload: type: object required: - name - input properties: name: type: string description: 自定义工具名称。 input: type: object unevaluatedProperties: {} description: 自由格式的工具输入。 description: 智能体请求 API 调用方执行一次自定义工具调用。 AgentDeltaEvent: type: object required: - id - processed_at - type - data properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - agent.delta data: $ref: '#/components/schemas/DeltaPayload' description: 智能体的增量输出，只出现在以 `include_deltas=true` 打开的实时事件流中，不写入历史。`data` 恰好是某一种增量（文本、推理或工具调用输入）。 title: Agent 增量 AgentList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/Agent' description: 本页中的智能体。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 一页智能体。已归档的智能体不会出现在列表中。 AgentMessageEvent: type: object required: - id - processed_at - type - data properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - agent.message data: $ref: '#/components/schemas/AgentMessagePayload' description: 智能体产生了一条消息。`data.content` 为按序排列的内容块。 title: Agent 消息 AgentMessagePayload: type: object required: - content properties: content: type: array items: $ref: '#/components/schemas/ContentBlock' description: 模型产出的有序内容部分。 description: '`agent.message` 与 `agent.thinking` 事件中模型产出的内容。' AgentMessageStartedEvent: type: object required: - id - processed_at - type properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - agent.message_started description: 收到模型生成的首个可见消息 token。 title: Agent 消息开始 AgentModelStartedEvent: type: object required: - id - processed_at - type properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - agent.model_started description: 智能体开始发起模型生成请求。 title: Agent 模型开始 AgentOrder: type: string enum: - created_at - created_at_desc description: 智能体列表的排序方式：`created_at` 最旧在前，`created_at_desc` 最新在前（默认）。 AgentReference: type: object required: - id - version properties: type: type: string description: 条目类型，固定为 `agent`。 id: type: string description: 智能体 ID。 version: type: string description: 精确且不可变的智能体版本。 description: 协调者可用的固定智能体版本。 AgentThinkingEvent: type: object required: - id - processed_at - type - data properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - agent.thinking data: $ref: '#/components/schemas/AgentMessagePayload' description: 智能体产生了推理内容。`data.content` 为推理块。 title: Agent 推理 AgentThinkingStartedEvent: type: object required: - id - processed_at - type properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - agent.thinking_started description: 收到模型生成的首个推理 token。 title: Agent 推理开始 AgentThreadContextCompactedEvent: type: object required: - id - processed_at - type properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - agent.thread_context_compacted description: 线程的上下文被压缩以适配模型窗口。不携带 `data`。 title: 线程上下文压缩 AgentThreadMessageReceivedEvent: type: object required: - id - processed_at - type - data properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - agent.thread_message_received data: $ref: '#/components/schemas/ThreadMessageReceivedPayload' description: 线程收到了来自另一个线程的消息。`data` 标明发送方。 title: 收到线程消息 AgentThreadMessageSentEvent: type: object required: - id - processed_at - type - data properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - agent.thread_message_sent data: $ref: '#/components/schemas/ThreadMessageSentPayload' description: 线程向另一个线程发送了消息。`data` 标明接收方。 title: 发送线程消息 AgentToolResultEvent: type: object required: - id - processed_at - type - data properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - agent.tool_result data: $ref: '#/components/schemas/AgentToolResultPayload' description: 一次工具调用完成。`data` 携带结果内容部分与错误标记。 title: Agent 工具调用结果 AgentToolResultPayload: type: object required: - tool_result properties: tool_result: $ref: '#/components/schemas/ToolResultBlock' description: 已完成的工具结果。 description: '`agent.tool_result` 的负载。' AgentToolStartedEvent: type: object required: - id - processed_at - type - data properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - agent.tool_started data: $ref: '#/components/schemas/AgentToolStartedPayload' description: 工具调用即将执行。 title: Agent 工具开始 AgentToolStartedPayload: type: object required: - tool_use properties: tool_use: $ref: '#/components/schemas/ToolUseBlock' description: 即将执行的工具调用。 mcp: $ref: '#/components/schemas/MCPInfo' description: MCP 来源信息。当工具由 MCP 服务器提供时存在。 description: '`agent.tool_started` 的负载。' AgentToolUseEvent: type: object required: - id - processed_at - type - data properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - agent.tool_use data: $ref: '#/components/schemas/AgentToolUsePayload' description: 智能体请求了一次工具调用。`data` 携带调用本身、评估后的权限，以及工具来自 MCP 服务器时的 MCP 来源信息。 title: Agent 工具调用 AgentToolUsePayload: type: object required: - tool_use - evaluated_permission properties: tool_use: $ref: '#/components/schemas/ToolUseBlock' description: 请求的工具调用。 evaluated_permission: $ref: '#/components/schemas/PermissionPolicy' description: 应用于本次调用的权限判定。 mcp: $ref: '#/components/schemas/MCPInfo' description: MCP 来源信息。当工具由 MCP 服务器提供时存在。 description: '`agent.tool_use` 的负载：请求的调用、评估后的权限，以及工具来自 MCP 服务器时的 MCP 来源信息。' AgentToolset: type: object required: - type - name properties: type: type: string enum: - agent_toolset name: $ref: '#/components/schemas/AgentToolsetName' description: |- 要加载的内置工具集。 `default_toolset_20260901` 包含以下内置工具： [read_file, write_file, edit_file, shell, ipython, todo_read, todo_write, web_open_url, web_search, search_image_by_text, search_image_by_image, save_artifact]。 default_config: $ref: '#/components/schemas/ToolsetDefaultConfig' description: 工具集内每个工具的默认配置。 configs: type: array items: $ref: '#/components/schemas/ToolConfig' description: 单个工具的覆盖配置。 description: 内置智能体工具集声明。同一 `name` 出现多次时，只使用首份声明及其 `default_config`、`configs`，不合并后续声明。 title: Agent 工具集 AgentToolsetName: type: string enum: - default_toolset_20260901 description: 内置工具集名称。`default_toolset_20260901` 提供 `read_file`、`write_file`、`edit_file`、`shell`、`ipython`、`todo_read`、`todo_write`、`web_search`、`web_open_url`、`search_image_by_text`、`search_image_by_image`、`save_artifact`。`configs[].name` 填写这些名称。 AgentVersionList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/Agent' description: 本页中的版本，最新的在前。每个条目为该不可变版本捕获的完整智能体配置，顶层 `version` 标识版本。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 一页不可变智能体版本，最新在前。 AllowedHost: type: string maxLength: 256 description: 主机匹配器：精确主机名（大小写不敏感）、匹配任意深度子域的 `*.example.com` 通配（不含根域本身）、`~` 前缀的正则表达式，或 IP 地址/CIDR 网段。模式语法在会话开始使用该凭据时校验，而非写入时。 Artifact: type: object required: - id - session_id - path - name - mime_type - size_bytes - version - delivered_at properties: id: type: string description: 产物 ID，跨版本不变。 session_id: type: string description: 产生该产物的会话。 path: type: string description: 源文件在沙箱内的路径。在其会话内标识该产物。 name: type: string description: 文件名（`path` 的基础名），用于显示与下载。 mime_type: type: string description: 该版本的 MIME 类型。 size_bytes: type: integer format: int64 description: 该版本的字节大小。 version: type: string description: 本次交付的版本（`"1"`、`"2"`……，每次保存该路径都会递增）。获取与下载时作为 `version` 参数传入。 delivered_at: type: string format: date-time description: 该版本产生的时间。 description: 由 `save_artifact` 工具交付的文件。产物归项目所有，绑定到产生它的会话。在同一会话中再次交付同一路径，会为同一产物新增一个版本。列出与获取在未指定 `version` 时返回最新版本。 ArtifactList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/Artifact' description: 本页中的产物。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 一页产物，最近交付的在前。每个条目为该产物的最新版本。 ArtifactToolResultContent: type: object required: - type - id - version - name - path - mime_type - size_bytes properties: type: type: string enum: - artifact id: type: string description: 跨版本保持不变的 Artifact ID。 version: type: string description: 本次调用交付的版本（`"1"`、`"2"`……）。将其作为 content 下载接口的 `version` 查询参数，即可下载同一版本。 name: type: string description: 文件名（`path` 的末级名称），用于页面展示和下载文件名。 path: type: string description: 源文件在沙箱中的路径。 mime_type: type: string description: 此版本检测出的 MIME 类型。 size_bytes: type: integer format: int64 description: 此版本的文件大小，单位为字节。 description: '`save_artifact` 调用返回的一份已交付 Artifact 版本。其中包含渲染下载卡片所需的信息。完整 Artifact 由 Artifact 接口提供，内容由`GET /v1/artifacts/{id}/content?version=` 获取。' title: 产物 ArtifactVersionList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/Artifact' description: 本页中的版本。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 一个产物的一页版本，按数字版本号倒序。每个条目为该版本下的完整产物。 BadRequestErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' BatchCreateVaultCredentialsRequest: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/CreateVaultCredentialRequest' minItems: 1 maxItems: 20 description: 本次批量创建的凭据（1–20 条），按相同顺序返回。 description: 在单个原子请求中一并创建的凭据。 BatchCreateVaultCredentialsResponse: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/VaultCredential' description: 按请求顺序创建的凭据。 description: 原子批量请求创建的凭据，按请求顺序排列。 CheckMcpServerUrl: type: string minLength: 1 maxLength: 2048 description: 待检查凭据覆盖情况的一个 MCP 服务器 URL。 CheckVaultCredentialsRequest: type: object required: - mcp_server_urls properties: mcp_server_urls: type: array items: $ref: '#/components/schemas/CheckMcpServerUrl' minItems: 1 maxItems: 50 description: 1–50 个不重复的 MCP 服务器 URL。每个 URL 在匹配前会做规范化。规范化失败的 URL 不匹配任何凭据。 uniqueItems: true vault_ids: type: array items: type: string maxItems: 16 description: 最多 16 个不重复的凭据库（Vault）ID，限定搜索范围。省略时搜索调用方可见的所有凭据库（Vault）。 uniqueItems: true description: 凭据覆盖批量检查的请求体。 CheckVaultCredentialsResponse: type: object required: - coverage properties: coverage: type: array items: $ref: '#/components/schemas/CredentialCoverage' description: 每个请求 URL 的覆盖情况。 description: 每个请求 URL 的覆盖情况，按请求顺序排列。 CloudEnvironmentConfig: type: object required: - type properties: type: type: string enum: - cloud networking: $ref: '#/components/schemas/EnvironmentNetworking' description: 出站网络策略。省略时默认为 `unrestricted`。 packages: $ref: '#/components/schemas/EnvironmentPackages' description: 沙箱准备期间预装的软件包。 setup_script: type: string maxLength: 65536 description: 在快照构建时运行一次的 shell 脚本，于软件包安装之后，通过 `bash -c` 并启用 `set -eo pipefail` 执行。非零退出码会使构建失败。 description: 云环境的配置：出向网络、软件包与初始化脚本。 title: 云环境 ConflictErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' ContentBlock: type: object oneOf: - title: 文本 $ref: '#/components/schemas/TextContentBlock' - title: 推理 $ref: '#/components/schemas/ThinkingContentBlock' - title: 工具调用 $ref: '#/components/schemas/ToolUseContentBlock' - title: 工具调用结果 $ref: '#/components/schemas/ToolResultContentBlock' - title: 文件 $ref: '#/components/schemas/FileToolResultContent' discriminator: propertyName: type mapping: text: '#/components/schemas/TextContentBlock' thinking: '#/components/schemas/ThinkingContentBlock' tool_use: '#/components/schemas/ToolUseContentBlock' tool_result: '#/components/schemas/ToolResultContentBlock' file: '#/components/schemas/FileToolResultContent' description: 一个消息内容块，负载与 `type` 值并排。 ControlEpoch: type: string maxLength: 19 pattern: ^(0|[1-9][0-9]{0,18})$ description: 十进制字符串表示的非负控制版本，范围为 `0` 至 `9223372036854775807`。 CreateAgentRequest: type: object required: - name - model properties: name: type: string minLength: 1 maxLength: 256 description: 人类可读的智能体名称。 model: $ref: '#/components/schemas/ModelRef' description: 所选模型。 description: type: string maxLength: 2048 description: 可选的人类可读描述。 system: type: string maxLength: 100000 description: 系统提示词。 tools: type: array items: $ref: '#/components/schemas/Tool' maxItems: 128 description: 智能体可用的工具。 mcp_servers: type: array items: $ref: '#/components/schemas/McpServer' maxItems: 20 description: 智能体可用的 MCP 服务器连接。名称必须唯一。 skills: type: array items: $ref: '#/components/schemas/SkillRef' description: 智能体可用的技能。 plugins: type: array items: $ref: '#/components/schemas/PluginRef' description: 智能体可用的插件。 metadata: $ref: '#/components/schemas/StringMetadata' description: 用户自定义元数据（最多 16 条）。 multiagent: $ref: '#/components/schemas/MultiagentCoordinator' description: 允许智能体创建子线程的配置。 description: 创建智能体的请求体。同时创建第一个不可变版本。 CreateEnvironmentRequest: type: object required: - name - config properties: name: type: string minLength: 1 maxLength: 256 description: 人类可读的环境名称。不要求唯一。 description: type: string maxLength: 2048 description: 可选的人类可读描述。 config: $ref: '#/components/schemas/EnvironmentConfig' description: 执行配置。 metadata: $ref: '#/components/schemas/StringMetadata' description: 用户自定义元数据（最多 16 条）。 description: 创建环境的请求体。 CreateMemoryRequest: type: object required: - path properties: path: type: string minLength: 1 maxLength: 900 description: 文件的相对 POSIX 路径，最长 900 UTF-8 字节。路径会被严格校验、绝不静默改写：绝对路径、反斜杠、百分号编码、空段或 `.`/`..` 段、控制字符，以及任何未规范化的值（例如 `a/../b` 或 `a//b`）都会被拒绝。 content: type: string description: 文件内容，base64 编码，解码后不超过 20 MiB。缺省或为空时创建空文件。 description: 创建记忆文件的请求体。 CreateMemoryStoreRequest: type: object required: - name properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[\p{L}\p{N}][\p{L}\p{N}_-]{0,63}$ description: 用作会话挂载目录的名称。项目内唯一，活跃和已归档的记忆库均不可重名。必须以 Unicode 字母或数字开头。后续字符还可以使用 `_` 或 `-`。 description: type: string maxLength: 4096 description: 展示给模型的人类可读描述。 description: 创建记忆库的请求体。 CreatePluginResponse: type: object required: - plugin - version - report properties: plugin: $ref: '#/components/schemas/Plugin' description: 发布之后的插件；`latest_version` 已包含新版本。 version: $ref: '#/components/schemas/PluginVersion' description: 根据提交的插件包创建的不可变版本。 report: $ref: '#/components/schemas/PluginValidationReport' description: 所提交插件包的校验结果。此处 `ok` 恒为 true，但可能携带 `warn` 结论。 description: 发布插件后返回的插件、已发布版本与插件包校验结果。 CreateSessionRequest: type: object required: - agent_id - environment_id properties: agent_id: type: string description: 要运行的智能体。 agent_version: type: string maxLength: 128 description: 可选的精确智能体版本（`"1"`、`"2"`……）。默认为创建时的最新版本。 title: type: string maxLength: 256 description: 可选的人类可读标题。 metadata: $ref: '#/components/schemas/StringMetadata' description: 用户自定义元数据（最多 16 条）。 resources: type: array items: $ref: '#/components/schemas/SessionResource' description: 创建时要绑定的资源：文件、凭据库（Vault）和记忆库。每个会话最多包含 16 个凭据库和 8 个记忆库，它们的绑定在创建后不能再添加或替换。 agent_overrides: $ref: '#/components/schemas/SessionAgentOverrides' description: 自创建起生效的会话级智能体配置覆盖。 environment_id: type: string maxLength: 128 description: 会话使用的环境。其最新构建就绪的版本会在会话的整个生命周期内固定。环境必须可见、活跃且具有构建就绪的版本。 description: 创建会话的请求体。仅 `agent_id` 与 `environment_id` 必填。 CreateSkillResponse: type: object required: - skill - version properties: skill: $ref: '#/components/schemas/Skill' description: 新创建的技能。 version: $ref: '#/components/schemas/SkillVersion' description: 根据提交的软件包创建的第一个不可变版本。 description: 创建技能的结果：目录资源及其第一个版本。 CreateTriggerRequest: type: object required: - name - agent_id - environment_id - policy properties: name: type: string minLength: 1 maxLength: 256 description: 人类可读的触发器名称。 agent_id: type: string minLength: 1 maxLength: 128 description: 每次运行启动的智能体。 agent_version: type: string maxLength: 128 description: 精确的智能体版本（`"1"`、`"2"`……）。省略时选择触发时刻的最新版本。 environment_id: type: string minLength: 1 maxLength: 128 description: 承载触发器所启动会话的环境。 resources: type: array items: $ref: '#/components/schemas/SessionResource' maxItems: 16 description: 绑定到触发器所启动会话的资源。 initial_events: type: array items: $ref: '#/components/schemas/QueuedUserEventInput' maxItems: 16 description: 每次运行时添加到目标会话的开场消息，只支持 `user.message`。 session_mode: $ref: '#/components/schemas/SessionMode' description: 每次触发器运行使用哪个会话。 notification: $ref: '#/components/schemas/TriggerNotification' description: TriggerRun 通知的 webhook 配置。缺省则禁用投递。 policy: $ref: '#/components/schemas/TriggerPolicy' description: 决定触发器何时运行的策略。 description: 创建触发器的请求体。 CreateVaultCredentialRequest: type: object required: - auth properties: display_name: type: string minLength: 1 maxLength: 256 description: 人类可读的凭据名称。 auth: $ref: '#/components/schemas/VaultCredentialAuth' description: 认证负载。类型在创建后不可更改。 description: |- 向凭据库（Vault）添加一条凭据的请求体。 每条凭据都有一个唯一键——`mcp_oauth`/`static_bearer` 为规范化后的 `mcp_server_url`，`environment_variable` 为 `secret_name`——在该凭据库（Vault）的活跃凭据中唯一。 CreateVaultOAuthSessionRequest: type: object required: - mcp_server_url properties: mcp_server_url: type: string minLength: 1 maxLength: 2048 description: 要授权访问的 MCP 服务器 URL。 display_name: type: string maxLength: 128 description: 授权完成后创建的凭据的显示名称。省略时回退为服务器 URL。 client: $ref: '#/components/schemas/VaultOAuthClient' description: 要使用的 OAuth 客户端。省略时会向授权服务器自动注册一个客户端（动态客户端注册）。 egress_environment_id: type: string maxLength: 64 description: 可选的环境（Environment）绑定，应用于授权完成后创建的凭据，语义与 `MCPOAuthCredential.egress_environment_id` 相同。 description: 发起 MCP OAuth 授权流程的请求体。 CreateVaultOAuthSessionResponse: type: object required: - oauth_session_id - authorize_url - mcp_server_url properties: oauth_session_id: type: string description: OAuth 会话 ID，用于轮询授权状态。 authorize_url: type: string description: 提供方的 authorize URL（已应用 PKCE S256）。请在弹窗中打开。 mcp_server_url: type: string description: 规范化后的 MCP 服务器 URL——成功时即为凭据的键。 description: 需在弹窗中打开的提供方 authorize URL。 CreateVaultRequest: type: object required: - display_name properties: display_name: type: string minLength: 1 maxLength: 256 description: 人类可读的凭据库（Vault）名称。不要求唯一。 metadata: $ref: '#/components/schemas/StringMetadata' description: 调用方自定义的字符串元数据，最多 16 条。 description: 创建凭据库（Vault）的请求体。 CredentialCoverage: type: object required: - mcp_server_url - matching_vault_ids properties: mcp_server_url: type: string description: 该 MCP 服务器 URL，按请求原样回显。 matching_vault_ids: type: array items: type: string description: 调用方可见的、拥有此 URL 有效凭据的所有凭据库（Vault）。 description: 单个 MCP 服务器 URL 的活跃凭据覆盖情况。只有 `mcp_oauth` 和 `static_bearer` 凭据计入覆盖。`environment_variable` 凭据从不作为覆盖出现。 CredentialInjectionLocation: type: object properties: header: type: boolean description: 允许注入到请求头的值中（默认 true）。 body: type: boolean description: 允许注入到请求体中（默认 true）。 description: 出站请求中可注入机密的部分。 CredentialNetworkAccess: type: string enum: - limited - unrestricted description: |- 控制秘密值可被发送到哪些出站主机。 - `limited`：仅匹配 `allowed_hosts` 的主机。 - `unrestricted`：任意主机。 CredentialNetworking: type: object required: - type properties: type: $ref: '#/components/schemas/CredentialNetworkAccess' description: 指定替换仅限 `allowed_hosts`，还是允许替换到任意主机。 allowed_hosts: type: array items: $ref: '#/components/schemas/AllowedHost' maxItems: 128 description: 仅 `limited` 时可接收机密的主机。不匹配端口，请求中的端口会被忽略。 description: 机密注入的网络限制。 CronTriggerPolicy: type: object required: - type - expression - timezone properties: type: type: string enum: - cron expression: type: string minLength: 1 maxLength: 256 description: 5 字段 cron 表达式（分钟粒度）。不支持秒和年字段。 timezone: type: string minLength: 1 maxLength: 128 description: IANA 时区名称，用于计算计划运行时间。 description: 按存储时区求值的调度策略，使用 5 字段 cron 表达式。 title: cron 调度 CustomTool: type: object required: - type - name - description - input_schema properties: type: type: string enum: - custom name: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9_-]+$ description: 工具的唯一名称，只能包含字母、数字、下划线或连字符。 description: type: string minLength: 1 maxLength: 4096 description: 供模型判断何时调用该工具的说明。 input_schema: $ref: '#/components/schemas/CustomToolInputSchema' description: 描述工具输入参数的 JSON Schema。 description: 由 API 调用方执行的客户端自定义工具。 title: 自定义工具 CustomToolInputSchema: type: object required: - type properties: type: type: string enum: - object description: 自定义工具的输入必须是 JSON object。 properties: type: object unevaluatedProperties: {} description: 按输入字段名索引的属性 schema。 required: type: array items: type: string description: 模型必须提供的输入字段名。 description: 客户端自定义工具的输入 JSON Schema。 DeltaPayload: type: object oneOf: - title: 文本增量 $ref: '#/components/schemas/TextDeltaPayload' - title: 推理增量 $ref: '#/components/schemas/ThinkingDeltaPayload' - title: 工具调用增量 $ref: '#/components/schemas/ToolUseDeltaPayload' discriminator: propertyName: kind mapping: text: '#/components/schemas/TextDeltaPayload' thinking: '#/components/schemas/ThinkingDeltaPayload' tool_use: '#/components/schemas/ToolUseDeltaPayload' description: '`agent.delta` 的负载。每个事件恰好包含一个变体。' DreamActivityTrigger: type: object required: - enabled properties: enabled: type: boolean description: 发生变化的会话活动是否可以创建自动 Dreams。 min_changed_sessions: type: integer format: uint32 minimum: 1 maximum: 100 description: 触发条件的不同已变更会话数阈值。`enabled` 为 true 时必填（1–100）。 description: |- 活动条件。当足够多的会话发生变化时启动一次 Dreams。 自该条件上次触发以来，发生变化的不同会话数达到 `min_changed_sessions` 时，条件满足。 DreamPolicy: type: object required: - memory_store_id - activity - schedule properties: memory_store_id: type: string description: 受此策略控制的记忆库。 agent_id: type: string description: 运行 Dreams 会话的智能体。缺省表示使用平台默认 Dreams 智能体。 activity: $ref: '#/components/schemas/DreamActivityTrigger' description: 活动条件。始终存在，包括禁用时。 schedule: $ref: '#/components/schemas/DreamScheduleTrigger' description: 定时条件。始终存在，包括禁用时。 trigger_id: type: string description: 此策略持有的触发器。未配置策略时缺省。 environment_id: type: string description: 承载 Dreams 会话的环境。未配置策略时缺省。 updated_at: type: string format: date-time description: 策略上次更新的时间。未配置策略时缺省。 description: |- 单个记忆库的 Dreams 设置。 活动条件和定时条件分别判断，任一满足即触发。每次触发都会新建一个以读写方式挂载该记忆库的会话，并在策略持有的触发器下记录为一次触发器运行。 DreamScheduleTrigger: type: object required: - enabled properties: enabled: type: boolean description: 每日定时是否可创建自动 Dreams。 local_time: type: string maxLength: 5 pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ description: HH:mm 格式的本地时间。`enabled` 为 true 时必填。 timezone: type: string maxLength: 128 description: IANA 时区名称。`enabled` 为 true 时必填。 description: 每日定时条件。在固定的本地时间启动一次 Dreams。 Environment: type: object required: - id - name - config - created_at - updated_at - scope properties: id: type: string description: 环境 ID。 name: type: string description: 人类可读的环境名称。 description: type: string description: 可选的人类可读描述。 config: $ref: '#/components/schemas/EnvironmentConfig' description: 执行配置。 metadata: $ref: '#/components/schemas/StringMetadata' description: 用户自定义元数据（最多 16 条）。 build_status: $ref: '#/components/schemas/EnvironmentBuildStatus' description: 最新版本快照构建的生命周期状态。 created_at: type: string format: date-time description: 创建时间戳。 updated_at: type: string format: date-time description: 上次更新时间戳。 archived_at: type: string format: date-time description: 归档时间戳。活跃期间缺省。已归档的环境为只读：不可新建会话，已有会话不受影响，且不可取消归档。 scope: $ref: '#/components/schemas/ResourceScope' description: 可见性范围。 description: 持久化的执行环境，用于托管智能体会话。 EnvironmentBuildStatus: type: string enum: - building - ready - failed description: 环境版本的构建状态。会话只能固定 `ready` 的版本。 EnvironmentConfig: type: object oneOf: - title: 云环境 $ref: '#/components/schemas/CloudEnvironmentConfig' - title: 自托管环境 $ref: '#/components/schemas/SelfHostedEnvironmentConfig' discriminator: propertyName: type mapping: cloud: '#/components/schemas/CloudEnvironmentConfig' self_hosted: '#/components/schemas/SelfHostedEnvironmentConfig' description: 环境的执行配置。 EnvironmentList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/Environment' description: 本页中的环境。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 一页环境，最新在前。 EnvironmentNetworking: type: object required: - type properties: type: $ref: '#/components/schemas/NetworkAccess' description: 网络访问级别。 allowed_hosts: type: array items: $ref: '#/components/schemas/AllowedHost' maxItems: 128 description: '`type` 为 `limited` 时沙箱内可达的主机。域名条目可带端口（`host:port`），不带端口时仅放行 80 与 443 端口；IP 与 CIDR 条目按 TCP 直连放行且不限端口，不得带端口。如 `kimi.com`、`*.kimi.com`、`api.kimi.com:8443`、`1.2.3.4`、`10.0.0.0/8`。' allow_package_managers: type: boolean description: '`type` 为 `limited` 时把公共包管理器的官方注册表加进白名单。' allow_mcp_servers: type: boolean description: '`type` 为 `limited` 时把智能体上声明的 MCP 服务器加进白名单。' proxy: $ref: '#/components/schemas/EnvironmentProxy' description: 两种网络访问类型下均可选的代理。 description: 应用于云环境沙箱的网络策略。仅控制沙箱进程的出站访问。平台级工具不受影响。 EnvironmentPackages: type: object properties: apt: type: array items: $ref: '#/components/schemas/PackageSpec' maxItems: 128 description: 通过 apt 安装的 Debian/Ubuntu 系统包。 pip: type: array items: $ref: '#/components/schemas/PackageSpec' maxItems: 128 description: 通过 pip 安装的 Python 包。 npm: type: array items: $ref: '#/components/schemas/PackageSpec' maxItems: 128 description: 通过 npm 安装的 Node.js 包。 go: type: array items: $ref: '#/components/schemas/PackageSpec' maxItems: 128 description: 通过 go install 安装的 Go 包。 cargo: type: array items: $ref: '#/components/schemas/PackageSpec' maxItems: 128 description: 通过 cargo install 安装的 Rust 包。 description: 预装到云环境沙箱中的包，按包管理器分组。条目使用各包管理器的原生版本语法。未固定版本时安装最新版本。 EnvironmentProxy: type: object required: - url - hosts properties: url: type: string maxLength: 512 description: 代理 URL，严格为 `http(s)://host[:port]`，不含 userinfo。非机密（凭据存放在 `auth` 中）。使用 `client_cert` 认证时必须为 `https`（mTLS 发生在 TLS 握手阶段）。 auth: $ref: '#/components/schemas/EnvironmentProxyAuth' description: 代理认证。可选。无认证的代理可省略。 ca: type: string maxLength: 65536 description: 可选的 PEM CA 证书包（非机密），追加到会话出站路径的信任根：URL 为 https 时校验代理自身的 TLS 证书，也校验经代理可达的源站（例如由私有 CA 签发的客户内网站点）。无论认证类型均生效。 hosts: type: array items: $ref: '#/components/schemas/AllowedHost' maxItems: 128 description: |- 经此代理转发的主机名单。 `limited` 下名单内的主机经代理直接可达，无需再写进白名单。 平台内部接口恒直连。 route_all: type: boolean description: |- 全部出站主机默认经此代理转发。 平台内部接口仍绕过代理。`limited` 下白名单不再生效——可达性完全由该代理自行决定。 description: |- 引用此环境的会话所使用的 HTTP 代理。 `hosts` 名单内的主机经由此代理转发，而不走平台默认路径；设置 `route_all` 后全部出站主机默认经此代理转发。 代理之间不链式叠加。 EnvironmentProxyAuth: type: object required: - type - vault_id - credential_id properties: type: $ref: '#/components/schemas/ProxyAuthType' description: 认证方案。 vault_id: type: string maxLength: 128 description: 持有凭据的凭据库（Vault）。 credential_id: type: string maxLength: 128 description: 凭据库（Vault）内的凭据 ID。 description: 环境上游代理的认证。凭据存储在项目凭据库（Vault）中并按 ID 引用。明文值从不出现在环境上。引用的凭据必须是调用方项目可见的凭据库中活跃的 `environment_variable` 凭据，其 `secret_value` 携带对应认证方式所需的材料（`basic` 为 `user:password` 对，`client_cert` 为 PEM 包）。运行时机密只发往代理主机。 EnvironmentVariableCredential: type: object required: - type - secret_name properties: type: type: string enum: - environment_variable secret_name: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z_][A-Za-z0-9_]*$ description: 环境变量名。在同一凭据库（Vault）的有效凭据中唯一。不可变。 secret_value: type: string maxLength: 8192 description: 机密值。请求中可提交，绝不在响应中返回。 networking: $ref: '#/components/schemas/CredentialNetworking' description: 替换秘密值的网络限制。省略时表示 `limited` 加空允许列表，即秘密值不会被替换到任何主机。 injection_location: $ref: '#/components/schemas/CredentialInjectionLocation' description: 秘密值可被注入的请求位置。省略时请求头和请求体都允许。 description: 以环境变量形式暴露给沙箱、并在出站时替换的机密。 title: 环境变量凭据 ErrorObject: type: object required: - type - message properties: type: $ref: '#/components/schemas/ErrorType' description: 来自注册词汇表的机器可读错误类型。 message: type: string description: 人类可读的错误消息。 param: type: string description: 适用时，为与错误相关的请求参数或请求体字段。在 `invalid_parameter_error` 上始终存在。 request_id: type: string description: 服务端分配的请求标识符，用于支持查询。在错误响应上始终存在，与 `Msh-Request-Id` 头一致。 description: 所有 API 版本共用的机器可读错误详情。 ErrorType: type: string enum: - invalid_parameter_error - invalid_request_error - failed_precondition_error - authentication_error - permission_denied_error - resource_not_found_error - conflict_error - rate_limit_reached_error - exceeded_current_quota_error - server_error description: 已注册的机器可读错误类型，每种客户端恢复策略对应一个。该集合对客户端封闭，可穷尽处理，但响应侧保持开放：客户端必须容忍未来新增的取值（新增取值不属于破坏性变更）。 EventOrder: type: string enum: - asc - desc - processed_at_asc - processed_at_desc description: 事件列表的排序方式：`asc`（默认，最旧在前）或 `desc`（最新在前）。`processed_at_asc` 与 `processed_at_desc` 是同一两个方向的完整写法。事件只追加，因此只有处理顺序。 FileMetadata: type: object required: - id - filename - mime_type - size_bytes - created_at - extract_status properties: id: type: string description: 文件 ID。 filename: type: string description: 原始文件名（可能带有服务器分配的去重后缀）。 mime_type: type: string description: 上传时检测到的 MIME 类型。 size_bytes: type: integer format: int64 description: 文件大小（字节）。 created_at: type: string format: date-time description: 上传时间戳。 purpose: $ref: '#/components/schemas/FilePurpose' description: 处理用途。 extract_status: $ref: '#/components/schemas/FileStatus' description: 当前处理状态。 description: 上传到调用方项目的文件元数据。 FileMetadataList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/FileMetadata' description: 调用方可见的文件，最新在前。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 调用方可见的已上传文件列表。不带 `page_size` 时端点返回完整列表。 FilePurpose: type: string enum: - file-extract - image - video - batch description: |- 上传文件的处理用途。默认为 `file-extract`。 - `file-extract`：文档（包括表格和公式）会解析为供模型使用的 Markdown。内容端点返回一个携带解析出的 Markdown 的 JSON 对象，而非原始上传内容。图片和视频由媒体解析处理，因此其内容端点不可用。 - `image`/`video`：跳过文档解析。只有检测为图片或视频的文件才会进行媒体处理。图片不做 OCR，内容端点不可用。 - `batch`：上传文件作为批处理输入。内容端点返回上传的文件；文件在上传时经解析规范化，返回的字节可能与原文件不同。只有上传者本人可以读取或删除。该文件不能挂载到会话。 FileStatus: type: string enum: - ready - error description: |- 文件的处理状态。 - `ready`：文件可按指定用途使用。图片或视频解析失败不会改变此状态。 - `error`：文档解析失败。文件仍可见、可删除，也可以挂载到新的会话。 FileToolResultContent: type: object required: - type - mime_type - title - path - file_id properties: type: type: string enum: - file mime_type: type: string description: 被引用文件的 MIME 类型。 title: type: string description: 被引用文件的显示标题。 path: type: string description: 被引用文件在沙箱内的路径。 file_id: type: string description: 平台文件标识符。 description: 文件引用结果内容。 title: 文件 ForbiddenErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' HeartbeatWorkItemRequest: type: object required: - worker_id - generation properties: worker_id: type: string minLength: 1 description: 持有租约的 worker。 generation: type: integer format: int64 minimum: 1 description: 认领时返回的 fencing token。 description: '`POST /v1/environments/{environment_id}/work/{id}/heartbeat` 的请求体。' ImageToolResultContent: type: object required: - type - url - mime_type properties: type: type: string enum: - image url: type: string description: 可获取图片的 URL。 mime_type: type: string description: 图片的 MIME 类型。 description: 按 URL 引用图片的结果内容。 title: 图片 InputEventType: type: string enum: - next_turn - steer description: |- 决定排队输入事件何时被处理。 - `next_turn`（缺省时的默认值）：按到达顺序排队，当前轮次（turn）结束后加载一条。 - `steer`：在当前步骤（step）结束边界注入正在运行的轮次。所有待处理的 steer 输入一并注入。 MCPInfo: type: object required: - server_name properties: server_name: type: string description: 提供该工具的 MCP 服务器名称。 description: 工具调用的 MCP 来源信息。 MCPOAuthCredential: type: object required: - type - mcp_server_url properties: type: type: string enum: - mcp_oauth mcp_server_url: type: string maxLength: 512 description: MCP 服务器的绝对 URI。创建后不可修改。 access_token: type: string maxLength: 8192 description: OAuth 访问令牌。仅在请求中接受，从不在响应中返回。 expires_at: type: string format: date-time description: 访问令牌的过期时间。缺省表示令牌不会过期。 refresh: $ref: '#/components/schemas/MCPOAuthRefresh' description: 可选的刷新配置，用于启用托管令牌刷新。 egress_environment_id: type: string maxLength: 64 description: 可选的环境（Environment）绑定。绑定后，该凭据的 OAuth 授权流程（发现、动态客户端注册、令牌交换）与后台令牌刷新都经该环境的代理转发，不走平台默认路径，仅该环境可达的 MCP server 与授权服务器也能连通。更新时传空字符串清除绑定；省略表示未绑定。 description: MCP 服务器的 OAuth 2.0 凭据。 title: MCP OAuth 凭据 MCPOAuthRefresh: type: object required: - token_endpoint - client_id - token_endpoint_auth_type properties: token_endpoint: type: string maxLength: 512 description: OAuth 令牌端点 URL。创建后不可修改。 client_id: type: string maxLength: 256 description: OAuth 客户端 ID。创建后不可修改。 scope: type: string maxLength: 1024 description: 刷新时请求的 OAuth 权限范围，以空格分隔。 refresh_token: type: string maxLength: 8192 description: OAuth 刷新令牌。仅在请求中接受，从不在响应中返回。 token_endpoint_auth_type: $ref: '#/components/schemas/TokenEndpointAuthType' description: 刷新调用的认证方式。必须显式指定。 client_secret: type: string maxLength: 8192 description: 客户端密钥。仅在请求中接受，响应中不返回。 description: mcp_oauth 凭据的 OAuth 刷新配置。 ManualTriggerContext: type: object required: - type - actor properties: type: type: string enum: - manual actor: type: string description: 运行触发器的用户 ID。 description: 手动运行的上下文。 title: 手动 McpServer: type: object required: - type - name - url properties: type: $ref: '#/components/schemas/McpServerType' description: 服务器类型。目前仅支持 "url"。 name: type: string minLength: 1 description: 在工具声明中引用此服务器的唯一名称。 url: type: string minLength: 1 description: MCP 服务器端点 URL。 headers: $ref: '#/components/schemas/McpServerHeaders' description: |- 每次连接此服务器时发送的非敏感 HTTP 请求头，例如 User-Agent 或租户路由头。 请求中接受，响应中省略。 由于响应中省略，更新时 headers 按服务器身份合并，而不是直接整体替换：服务器的 `headers` 缺省或为空时，继承未发生变化的服务器（name、type、url 均一致）的已存储 headers；`headers` 非空时整体替换；值为空字符串表示删除该键（传入任意一个空字符串值的键即可清空该服务器的全部 headers）。改名或变更 URL 的服务器视为新声明，不继承。 密钥类 token 不得在此声明：应通过 Vault 凭据注入。 description: 在智能体上声明的 MCP 服务器连接。 McpServerHeaders: type: object description: MCP 服务器连接上声明的 HTTP 请求头：最多 16 个条目，键最长 128 个字符，值最长 2048 个字符。键必须是 RFC 7230 合法的请求头名称，且不得仅大小写不同而重名；值不得包含 CR/LF。 maxProperties: 16 propertyNames: type: string maxLength: 128 additionalProperties: type: string maxLength: 2048 McpServerType: type: string enum: - url description: MCP 服务器连接的类型。 McpToolset: type: object required: - type - mcp_server_name properties: type: type: string enum: - mcp_toolset mcp_server_name: type: string minLength: 1 description: 在同一智能体上声明的 MCP 服务器名称。 default_config: $ref: '#/components/schemas/ToolsetDefaultConfig' description: 此 MCP 服务器所提供工具的默认配置。 configs: type: array items: $ref: '#/components/schemas/ToolConfig' description: 逐工具的覆盖配置。 description: 暴露已连接 MCP 服务器所提供工具的工具集。 title: MCP 工具集 Memory: type: object required: - id - memory_store_id - path - content_sha256 - content_size_bytes - created_at - updated_at properties: id: type: string description: 记忆文件 ID。文件重命名时保持不变。 memory_store_id: type: string description: 所属记忆库的 ID。 path: type: string description: 相对于记忆库根目录的路径。 content: type: string description: 文件内容，经 base64 编码。在创建/获取/更新响应中存在。列表响应中省略。该字段存在与否可区分空文件与内容未加载两种情况。 content_sha256: type: string description: 解码后内容的 SHA-256 哈希。更新时回传用作乐观并发检查。 content_size_bytes: type: integer format: int64 description: 解码后内容的大小，单位为字节。 created_at: type: string format: date-time description: 创建时间戳。 updated_at: type: string format: date-time description: 最近一次内容或路径更新的时间戳。 description: |- 记忆库中的一个文件。 `id` 在重命名后保持不变。删除文件后，其 ID 和版本历史仍可读取。 MemoryAccess: type: string enum: - read_only - read_write description: |- 授予会话对记忆库的权限。 - `read_only`：会话可以读取记忆库。 - `read_write`：会话还可以写入记忆库。每次写入都记录为一个记忆版本。 MemoryList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/Memory' description: 本页中的记忆。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 单页当前记忆文件，最新在前。不包含文件内容。 MemoryStore: type: object required: - id - name - created_at - updated_at properties: id: type: string description: 记忆库 ID。 name: type: string description: 展示给智能体并用作会话挂载目录的名称。项目内唯一，活跃和已归档的记忆库均不可重名。 description: type: string description: 展示给模型的人类可读描述。 created_at: type: string format: date-time description: 创建时间戳。 updated_at: type: string format: date-time description: 最近一次元数据更新的时间戳。 archived_at: type: string format: date-time description: 归档时间戳。处于活跃状态时缺省。 description: |- 项目作用域的文件存储，挂载进会话。 会话经挂载读取或更新记忆库。每次文件变更都记录为一个不可变的记忆版本。 MemoryStoreList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/MemoryStore' description: 本页中的记忆库。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 单页记忆库，最新在前。 MemoryVersion: type: object required: - id - memory_store_id - memory_id - path - operation - source - created_at properties: id: type: string description: 记忆版本 ID。 memory_store_id: type: string description: 所属记忆库的 ID。 memory_id: type: string description: 被更改文件的稳定记忆 ID。 path: type: string description: 更改后的文件路径。 operation: $ref: '#/components/schemas/MemoryVersionOperation' description: 此版本记录的文件操作。 content: type: string description: 历史文件正文，经 base64 编码。`deleted` 版本以及正文被删除后不返回。 content_sha256: type: string description: 更改后内容的 SHA-256。删除时缺省。 content_size_bytes: type: integer format: int64 description: 更改后内容的大小，单位为字节。删除时缺省。 source: $ref: '#/components/schemas/MemoryVersionSource' description: 更改的来源（`api` 或 `session`）。 source_id: type: string description: 产生此更改的会话。仅当 `source` 为 `session` 时存在。 created_at: type: string format: date-time description: 平台接受此版本记录的时间。 redacted_at: type: string format: date-time description: 历史正文被删除的时间。可读期间缺省。 revision: type: integer format: int64 description: 在成为过文件当前状态的版本序列中的单调位置。从未成为当前状态的乱序写入缺省。 description: |- 对记忆文件一次更改的不可变记录。 每次变更都会记录，包括从未成为文件当前状态的乱序写入。 MemoryVersionList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/MemoryVersion' description: 本页中的版本。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 单页记忆版本。不包含版本内容。 MemoryVersionOperation: type: string enum: - created - modified - deleted - renamed description: |- 记忆文件版本历史中记录的更改。 - `created`：在此路径创建了文件。 - `modified`：内容原地更改。 - `deleted`：文件被删除。该版本不携带内容。 - `renamed`：路径更改，可同时带有内容更改。 MemoryVersionOrder: type: string enum: - asc - desc description: 版本历史的排序方式：`asc` 最旧在前（默认），`desc` 最新在前。 MemoryVersionSource: type: string enum: - api - session description: |- 记忆文件版本的来源。 - `api`：经记忆库 API 直接写入。 - `session`：由会话经读写挂载写回。版本的 `source_id` 携带会话 ID。 ModelConfig: type: object required: - id properties: id: type: string minLength: 1 description: 模型 ID。 reasoning_effort: $ref: '#/components/schemas/ReasoningEffort' description: 可选的推理强度提示。 provider: type: string description: 模型提供方 ID。留空则选择平台默认提供方。 description: 需要按模型细调参数时使用的结构化模型选择。 ModelRef: anyOf: - type: string - $ref: '#/components/schemas/ModelConfig' description: 模型选择：裸模型 ID 字符串或结构化配置。 Multiagent: type: object required: - agents properties: type: type: string description: 配置类型，固定为 `coordinator`。 agents: type: array items: $ref: '#/components/schemas/AgentReference' description: 该协调者可创建为子线程的固定智能体版本。 description: 存储在智能体版本上的、已解析的协调者配置。 MultiagentCoordinator: type: object required: - type - agents properties: type: type: string enum: - coordinator description: 配置类型，固定为 `coordinator`。 agents: type: array items: $ref: '#/components/schemas/RosterEntry' maxItems: 20 description: 可委派的子智能体名单：协调者可用这些智能体创建子线程，不是已创建的子线程列表。每个条目都在写入时解析为固定的智能体版本。创建时要求 1–20 条；更新时可发送空数组以清空协调者配置。未配置子智能体名单时创建的会话不提供子智能体编排工具，包括 `send_message`、`wait_for_message`、`interrupt_subagent`。 description: 创建和更新请求所接受的协调者配置。 NetworkAccess: type: string enum: - limited - unrestricted description: 云环境沙箱的网络访问级别。 NotFoundErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' NotificationVaultRef: type: object required: - vault_id properties: vault_id: type: string minLength: 1 maxLength: 128 description: 存放签名密钥的凭据库（Vault），密钥位于凭据键 `webhook_secret` 下。 description: 存放 webhook HMAC 签名密钥的凭据库（Vault）。 PackageSpec: type: string maxLength: 256 description: 一条包安装条目，采用包管理器原生的版本语法。 PausedReason: type: object required: - type properties: type: $ref: '#/components/schemas/PausedReasonType' description: 暂停来源。 error: $ref: '#/components/schemas/TriggerError' description: 结构化错误详情。仅当 `type` 为 `error` 时存在。 description: 触发器被暂停的原因。处于活跃状态时缺省。 PausedReasonType: type: string enum: - manual - error description: 触发器暂停的原因：显式请求，或在不可恢复的运行错误后自动暂停。 PendingEvent: type: object required: - event_id - type - events - queued_at properties: event_id: type: string description: 排队输入的事件 ID。 type: $ref: '#/components/schemas/InputEventType' description: 待处理输入的类型。 events: type: array items: $ref: '#/components/schemas/QueuedUserEventInput' description: 排队输入携带的用户事件。 queued_at: type: string format: date-time description: 输入入队的时间。 description: 会话的一条排队输入事件，携带其内容与入队时间。 PendingEventList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/PendingEvent' description: 按到达顺序排列的待处理事件。 description: 会话的待处理输入事件，按到达顺序排列。 PermissionPolicy: type: string enum: - always_allow - always_ask description: '应用于工具或工具集的权限策略。`always_allow` 表示模型调用时直接运行该工具。`always_ask` 会暂停线程，在工具执行前等待客户端确认。用 `enabled: false` 禁用工具。被禁用的工具不对模型暴露。' Plugin: type: object required: - id - name - display_name - description - version - created_at - updated_at - scope - status - latest_version properties: id: type: string description: 插件 ID，由共享目录分配。 name: type: string description: kebab-case 风格的插件名称，在所属市场内唯一：`official` 名称由共享目录分配，project 名称在项目内唯一。两个市场可以存在同名插件，引用一律按 id。 display_name: type: string description: 向用户展示的插件名称。 icon_url: type: string description: 图标 URL。 description: type: string description: 向用户展示的插件描述。 keywords: type: array items: type: string description: 搜索关键词。 version: type: string description: 当前采纳的插件版本。智能体配置在写入时固定该版本。 categories: type: array items: $ref: '#/components/schemas/PluginCategory' description: 插件的展示分类列表，来自固定词表。插件未分类时缺省。仅用于展示，不影响智能体配置。 mcp_servers: type: array items: $ref: '#/components/schemas/PluginMcpServer' description: 此插件捆绑的远程 MCP 服务器。 skills: type: array items: $ref: '#/components/schemas/PluginSkill' description: 此插件捆绑的技能。 created_at: type: string format: date-time description: 创建时间戳。 updated_at: type: string format: date-time description: 最近更新时间戳。 scope: $ref: '#/components/schemas/ResourceScope' description: 可见性范围。`official` 插件由平台提供，通过本 API 只读。 status: $ref: '#/components/schemas/PluginStatus' description: 当前的生命周期状态。 latest_version: type: string description: 最新发布的版本。`official` 插件与其采纳的 `version` 相同；项目自有插件按语义版本优先级取最高的正式版本，尚无正式版本时取最高的预发布版本。 description: 目录中的一个条目，为智能体配置捆绑远程 MCP 服务器与技能。 PluginCategory: type: string enum: - finance - productivity - creative_3d - dev_tools - learning - featured description: 插件的展示分类，来自固定词表。 PluginIssueSeverity: type: string enum: - error - warn description: 校验发现是否阻止发布。 PluginList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/Plugin' description: 本页中的插件。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 一页插件，按 ID 升序排列。 PluginMcpServer: type: object required: - mcp_key - name - description - needs_oauth properties: mcp_key: type: string description: 跨插件版本保持稳定的服务器键。 name: type: string description: 向用户展示的服务器名称。 description: type: string description: 该服务器提供的能力说明。 needs_oauth: type: boolean description: 该服务器是否声明需要终端用户凭据（OAuth 或 static bearer）。仅作凭据配置引导的展示提示，不是运行时要求。`static_bearer` 凭据同样满足。 url: type: string description: 用于预填凭据表单的远程服务器 URL。stdio 服务器缺省。 description: 插件包中捆绑的 MCP 服务器，附带展示元数据与凭据提示。 PluginRef: type: object required: - plugin_id properties: plugin_id: type: string minLength: 1 description: 要附加的插件 ID。 version: type: string description: 插件版本。版本规则由插件所属市场决定：`official` 插件由平台定版，必须省略 `version`，显式传值将被拒绝，返回 400；`project` 插件可指定其已发布的某个版本，可省略（写入时固定为当时的最新发布版本），也可使用字面量 `"latest"`（原样保留，每次唤醒时现解为采用版本）。 description: 对附加到智能体的已列出插件的引用。 PluginSkill: type: object required: - name - description properties: name: type: string description: 向用户展示的技能名称。 description: type: string description: 向用户展示的技能描述。 description: 插件包中捆绑的技能。 PluginStatus: type: string enum: - active - archived description: 插件当前的生命周期状态。 PluginValidationIssue: type: object required: - code - severity - message properties: code: type: string description: 标识该结论的稳定代码，例如 `manifest.name.pattern`，可用于程序分支。 field: type: string description: 该结论所指的 manifest 字段，例如 `interface.hostKind`。结论针对整个插件包时缺省。 severity: $ref: '#/components/schemas/PluginIssueSeverity' description: 该结论是否阻止发布。 message: type: string description: 该结论的说明。 description: 插件包校验的一条结论，面向插件包作者。 PluginValidationReport: type: object required: - ok - issues properties: ok: type: boolean description: 该插件包是否可以发布。任一结论为 `error` 时为 false。 issues: type: array items: $ref: '#/components/schemas/PluginValidationIssue' description: 本次校验的全部结论，包含 error 与 warn。插件包无问题时为空数组。 description: 一次插件包校验的结果。 PluginVersion: type: object required: - plugin_id - version - name - description - created_at properties: plugin_id: type: string description: 拥有该版本的插件 ID。 version: type: string description: 该版本的 manifest 声明的语义版本，例如 `"1.2.0"`。 name: type: string description: 该版本的 manifest 声明的插件名称。 description: type: string description: 该版本的 manifest 声明的插件描述。 created_at: type: string format: date-time description: 该版本的发布时间。 description: 插件的一个不可变发布版本。 PluginVersionList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/PluginVersion' description: 本页中的版本。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 一页插件版本，语义版本最新的在前。 PreconditionFailedErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' ProxyAuthType: type: string enum: - basic - client_cert description: 环境上游代理的认证方案。 QueuedUserEventInput: type: object oneOf: - title: 用户消息 $ref: '#/components/schemas/UserMessageInput' discriminator: propertyName: type mapping: user.message: '#/components/schemas/UserMessageInput' description: 可在输入队列中等待处理的用户内容。中断命令不能入队。 ReasoningEffort: type: string enum: - low - medium - high - max description: 推理强度提示。所选模型可能会忽略它。 ResourceScope: type: string enum: - official - org - project - user description: 资源的可见范围。`official` 资源由平台提供，通过本 API 只读。 RosterAgentEntry: type: object required: - type - id properties: type: type: string enum: - agent id: type: string minLength: 1 maxLength: 128 description: 智能体 ID。 version: type: string maxLength: 128 description: 精确的智能体版本（`"1"`、`"2"`……）。省略时使用写入时刻的最新版本。 description: 可委派的子智能体名单条目，允许协调者用另一个智能体创建子线程。 title: 智能体 RosterEntry: type: object oneOf: - title: 智能体 $ref: '#/components/schemas/RosterAgentEntry' - title: 自身 $ref: '#/components/schemas/RosterSelfEntry' discriminator: propertyName: type mapping: agent: '#/components/schemas/RosterAgentEntry' self: '#/components/schemas/RosterSelfEntry' description: 可委派的子智能体名单条目，协调者可据此创建子线程。 RosterSelfEntry: type: object required: - type properties: type: type: string enum: - self description: 可委派的子智能体名单条目，引用协调者自身的智能体版本。 title: 自身 RunTriggerRequest: type: object properties: payload: type: string maxLength: 4096 description: 可选的自由格式负载，以用户消息形式投递到本次运行的会话。 description: 手动运行触发器的请求体。 ScheduleTriggerContext: type: object required: - type - scheduled_at properties: type: type: string enum: - schedule scheduled_at: type: string format: date-time description: 本次运行的计划时间。 description: 调度（cron）运行的上下文。 title: 调度 SelfHostedEnvironmentConfig: type: object required: - type properties: type: type: string enum: - self_hosted description: 自托管环境的配置：工具调用在调用方一侧执行，并通过会话事件流应答；平台不为其构建沙箱镜像。 title: 自托管环境 SendEventsRequest: type: object required: - events properties: type: $ref: '#/components/schemas/InputEventType' description: 排队输入的类型。省略时视为 `next_turn`。 events: type: array items: $ref: '#/components/schemas/UserEventInput' minItems: 1 description: 要按顺序追加的事件。 description: 要入队的用户事件，或用于停止会话的单条 `user.interrupt`。 SendEventsResponse: type: object properties: event_id: type: string description: 已接受排队输入的事件 ID。待处理列表、撤回与消费回显（复用该 ID 作为自身事件 `id`）通过它进行关联。当部署提供输入队列时，每个排队输入都会设置此字段。否则不存在。`user.interrupt` 请求不产生排队输入，此字段始终不存在。 control_epoch: $ref: '#/components/schemas/ControlEpoch' description: 接受 `user.interrupt` 后的控制版本。排队输入不携带此字段。 description: 以 `event_id` 确认排队输入，或以 `control_epoch` 确认 `user.interrupt` 请求。中断请求不入队。 Session: type: object required: - id - agent_id - environment_id - status - created_at - updated_at properties: id: type: string description: 会话 ID。 agent_id: type: string description: 此会话运行的智能体。 environment_id: type: string description: 托管此会话的环境。 status: $ref: '#/components/schemas/SessionState' description: 当前生命周期状态。 interrupted: type: boolean description: 已提交的停止是否暂停执行。新消息或显式继续可以恢复执行。 control_epoch: $ref: '#/components/schemas/ControlEpoch' description: 会话当前的控制版本。 continue_pending: type: boolean description: 已接受继续请求，但尚未开始执行。 title: type: string description: 人类可读的标题。 metadata: $ref: '#/components/schemas/StringMetadata' description: 用户自定义元数据（最多 16 条）。 agent_overrides: $ref: '#/components/schemas/SessionAgentOverrides' description: 会话级智能体配置覆盖。未存储任何覆盖时不存在。 created_at: type: string format: date-time description: 创建时间戳。 updated_at: type: string format: date-time description: 最后更新时间戳。 archived_at: type: string format: date-time description: 归档时间戳。活跃期间不存在。 resources: type: array items: $ref: '#/components/schemas/SessionResource' description: 绑定到此会话的资源。在 `GET /v1/sessions` 的列表项中省略。 agent: $ref: '#/components/schemas/SessionAgent' description: 协调者线程使用的智能体版本快照。 description: 带版本智能体配置的一个运行实例。 SessionAgent: type: object required: - id - version - name properties: id: type: string description: 智能体 ID。 version: type: string description: 精确且不可变的智能体版本。 name: type: string description: 人类可读的智能体名称。 description: type: string description: 可选的智能体描述。 model: $ref: '#/components/schemas/ModelRef' description: 所选模型。 system: type: string description: 系统提示词。 tools: type: array items: $ref: '#/components/schemas/Tool' description: 线程可用的工具。 mcp_servers: type: array items: $ref: '#/components/schemas/McpServer' description: 线程可用的 MCP 服务器。 skills: type: array items: $ref: '#/components/schemas/SkillRef' description: 线程可用的精确技能版本。 multiagent: $ref: '#/components/schemas/SessionMultiagent' description: 协调者可创建为子线程的完整智能体定义。 description: 会话使用的智能体版本快照。 SessionAgentOverrides: type: object properties: mcp_servers: type: array items: $ref: '#/components/schemas/McpServer' maxItems: 20 description: 替换此会话的 MCP 服务器连接。 skills: type: array items: $ref: '#/components/schemas/SkillRef' maxItems: 64 description: 替换此会话的技能引用。空版本在写入时冻结为当时最新版；"latest" 原样保留，每次唤醒现解最新版。 plugins: type: array items: $ref: '#/components/schemas/PluginRef' maxItems: 64 description: 替换此会话的插件引用。每个条目按所属市场的版本规则处理（见 `PluginRef.version`）：`official` 条目必须省略 `version`，`project` 条目可指定已发布的版本。 tools: type: array items: $ref: '#/components/schemas/Tool' maxItems: 128 description: 替换此会话的工具配置。自定义工具使用与智能体工具相同的校验规则。 model: $ref: '#/components/schemas/ModelRef' description: 替换此会话的模型。provider 必须与会话的 model provider 一致（网关按 provider 注入 endpoint/key）。 system: type: string description: 替换此会话的系统提示词（空字符串表示清空）。无效的提示词模板返回 400 `invalid_parameter_error`。 roster: type: array items: $ref: '#/components/schemas/AgentReference' maxItems: 20 description: 替换此会话的多智能体名册；条目在写入时解析并冻结为精确版本。仅创建会话时可写：更新会话时携带此字段返回 400 `invalid_parameter_error`。 description: |- 会话级智能体配置覆盖（整体替换，绝不合并）。每个集合字段为三态： - 缺省：继承冻结智能体版本的值（创建时），或保持覆盖不变（更新时）。 - 显式空数组：清空此会话的该集合（创建时），或清除覆盖并回退到冻结值（更新时）。 - 非空数组：整体替换该集合。 SessionControlResponse: type: object required: - control_epoch properties: control_epoch: $ref: '#/components/schemas/ControlEpoch' description: 操作后的控制版本。 description: 已接受的会话生命周期操作。轮询会话以确认操作完成。 SessionErrorEvent: type: object required: - id - processed_at - type - data properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - session.error data: $ref: '#/components/schemas/SessionErrorPayload' description: 会话运行失败。`data` 携带机器可读的 `error_type` 与消息；它不是 HTTP 错误响应。 title: 会话错误 SessionErrorPayload: type: object required: - error_type - message properties: error_type: $ref: '#/components/schemas/SessionErrorType' description: |- 来自会话执行词汇表的机器可读错误类别： | `error_type` | 含义 → 恢复方式 | | --- | --- | | `internal_error` | 未归类的平台内部错误——联系支持并提供 request_id | | `model_error` | 模型服务出错——按 message 处理或稍后重试 | | `model_unavailable` | 当前 Session 的模型路由不可用——重新创建 Session | | `rate_limited` | 模型请求被限流——稍后重试 | | `engine_overloaded` | 模型引擎暂时过载——稍后重试 | | `quota_exceeded` | 模型配额耗尽或账户欠费——充值后发送新消息继续 | | `context_length_exceeded` | 对话超出模型上下文窗口——缩短输入或新建 Session | | `invalid_request` | 请求被模型拒绝——按 message 修改请求 | | `timeout` | 模型请求超时——稍后重试 | | `max_steps` | 本轮达到步数上限——发送新消息继续 | | `mcp_connection_failed` | MCP 连接或 transport 失败——稍后重试 | | `mcp_authentication_failed` | MCP server 拒绝鉴权——到 vault 页面重新连接 | message: type: string description: 人类可读的错误消息。 mcp_server_name: type: string description: 失败所属 MCP server 的声明名；仅 `mcp_connection_failed` 与 `mcp_authentication_failed` 携带。其他错误类型及该字段引入前写入的事件不含该字段。 description: '`session.error` 的负载。' SessionErrorType: type: string enum: - internal_error - model_error - model_unavailable - rate_limited - engine_overloaded - quota_exceeded - context_length_exceeded - invalid_request - timeout - max_steps - mcp_connection_failed - mcp_authentication_failed description: 运行中的会话发出的错误类别。 SessionEvent: type: object oneOf: - title: 用户消息 $ref: '#/components/schemas/UserMessageEvent' - title: 用户中断 $ref: '#/components/schemas/UserInterruptEvent' - title: 用户工具确认 $ref: '#/components/schemas/UserToolConfirmationEvent' - title: 自定义工具结果 $ref: '#/components/schemas/UserCustomToolResultEvent' - title: Agent 消息 $ref: '#/components/schemas/AgentMessageEvent' - title: Agent 推理 $ref: '#/components/schemas/AgentThinkingEvent' - title: Agent 工具调用 $ref: '#/components/schemas/AgentToolUseEvent' - title: Agent 工具调用结果 $ref: '#/components/schemas/AgentToolResultEvent' - title: Agent 模型开始 $ref: '#/components/schemas/AgentModelStartedEvent' - title: Agent 推理开始 $ref: '#/components/schemas/AgentThinkingStartedEvent' - title: Agent 消息开始 $ref: '#/components/schemas/AgentMessageStartedEvent' - title: Agent 工具开始 $ref: '#/components/schemas/AgentToolStartedEvent' - title: 自定义工具调用 $ref: '#/components/schemas/AgentCustomToolUseEvent' - title: 收到线程消息 $ref: '#/components/schemas/AgentThreadMessageReceivedEvent' - title: 发送线程消息 $ref: '#/components/schemas/AgentThreadMessageSentEvent' - title: 线程上下文压缩 $ref: '#/components/schemas/AgentThreadContextCompactedEvent' - title: Agent 增量 $ref: '#/components/schemas/AgentDeltaEvent' - title: 会话状态 $ref: '#/components/schemas/SessionStatusEvent' - title: 会话错误 $ref: '#/components/schemas/SessionErrorEvent' - title: 线程创建 $ref: '#/components/schemas/SessionThreadCreatedEvent' - title: 线程状态 $ref: '#/components/schemas/SessionThreadStatusEvent' - title: 会话标题更新 $ref: '#/components/schemas/SessionTitleUpdatedEvent' - title: 会话更新 $ref: '#/components/schemas/SessionUpdatedEvent' discriminator: propertyName: type mapping: user.message: '#/components/schemas/UserMessageEvent' user.interrupt: '#/components/schemas/UserInterruptEvent' user.tool_confirmation: '#/components/schemas/UserToolConfirmationEvent' user.custom_tool_result: '#/components/schemas/UserCustomToolResultEvent' agent.message: '#/components/schemas/AgentMessageEvent' agent.thinking: '#/components/schemas/AgentThinkingEvent' agent.tool_use: '#/components/schemas/AgentToolUseEvent' agent.tool_result: '#/components/schemas/AgentToolResultEvent' agent.model_started: '#/components/schemas/AgentModelStartedEvent' agent.thinking_started: '#/components/schemas/AgentThinkingStartedEvent' agent.message_started: '#/components/schemas/AgentMessageStartedEvent' agent.tool_started: '#/components/schemas/AgentToolStartedEvent' agent.custom_tool_use: '#/components/schemas/AgentCustomToolUseEvent' agent.thread_message_received: '#/components/schemas/AgentThreadMessageReceivedEvent' agent.thread_message_sent: '#/components/schemas/AgentThreadMessageSentEvent' agent.thread_context_compacted: '#/components/schemas/AgentThreadContextCompactedEvent' agent.delta: '#/components/schemas/AgentDeltaEvent' session.status: '#/components/schemas/SessionStatusEvent' session.error: '#/components/schemas/SessionErrorEvent' session.thread_created: '#/components/schemas/SessionThreadCreatedEvent' session.thread_status: '#/components/schemas/SessionThreadStatusEvent' session.title_updated: '#/components/schemas/SessionTitleUpdatedEvent' session.updated: '#/components/schemas/SessionUpdatedEvent' description: 会话事件联合类型。`type` 字段用于区分具体变体。每个变体将其负载放在 `data` 之下（负载为空的变体省略 `data`）。`agent.delta` 变体只会出现在以 `include_deltas=true` 打开的实时事件流中，绝不会出现在持久化历史中。 SessionEventList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/SessionEvent' description: 本页的事件，最旧的排在最前。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 stream_cursor: type: string description: 用于从本页末尾恢复实时事件流的游标。恢复点随服务端的每个追加批次推进，因此恢复时可能会重复投递本页已返回的少量事件。客户端必须按事件 `id` 去重。 description: 一页会话事件历史，最旧的在前。 SessionFSList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/SessionFSNode' description: 所请求目录中的文件与目录。 description: 会话文件系统中指定目录的直接子项。 SessionFSNode: type: object required: - name - size_bytes - is_dir - path properties: name: type: string description: 文件或目录名称。 size_bytes: type: integer format: int64 description: 文件大小（字节）。目录为 `0`。 is_dir: type: boolean description: 该节点是否为目录。 last_modified: type: string format: date-time description: 最后修改时间戳。 path: type: string description: 相对于会话文件根目录的路径。根目录的值为空。将该值传给原始下载端点即可读取文件内容。 description: 会话文件系统列表中的文件或目录。 SessionList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/Session' description: 本页的会话。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 一页会话。列表项省略 `resources` 绑定。 SessionMode: type: string enum: - new_session - reuse_session description: 每次触发器运行是新建会话还是复用平台管理的会话。 SessionMultiagent: type: object required: - agents properties: agents: type: array items: $ref: '#/components/schemas/SessionThreadAgent' description: 协调者可用的智能体版本完整快照。 description: Session.agent 中已解析的协调者名册。 SessionOrder: type: string enum: - created_at - created_at_desc - updated_at - updated_at_desc description: 列出会话时使用的排序：`updated_at_desc`（默认）、`updated_at`、`created_at_desc` 或 `created_at`。 SessionResource: type: object oneOf: - title: 文件 $ref: '#/components/schemas/SessionResourceFile' - title: 凭据库 $ref: '#/components/schemas/SessionResourceVault' - title: 记忆库 $ref: '#/components/schemas/SessionResourceMemoryStore' discriminator: propertyName: type mapping: file: '#/components/schemas/SessionResourceFile' vault: '#/components/schemas/SessionResourceVault' memory_store: '#/components/schemas/SessionResourceMemoryStore' description: 绑定到会话的资源（文件、凭据库（Vault）或记忆库）。 SessionResourceFile: type: object required: - type - file_id properties: type: type: string enum: - file id: type: string description: 绑定时分配的会话资源 ID。 file_id: type: string description: 引用的已上传文件。 mime_type: type: string description: 文件 MIME 类型，读取时从存储的元数据解析。 title: type: string description: 显示标题，读取时从存储的元数据解析。 path: type: string description: 文件在会话工作区内链接的路径，位于 `upload/` 下。 description: 作为资源绑定到会话的文件。 title: 文件 SessionResourceList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/SessionResource' description: 本页的资源。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 绑定到会话的一页资源。 SessionResourceMemoryStore: type: object required: - type - memory_store_id - access properties: type: type: string enum: - memory_store id: type: string description: 绑定时分配的会话资源 ID。 memory_store_id: type: string minLength: 1 description: 要绑定的记忆库。 access: $ref: '#/components/schemas/MemoryAccess' description: 此会话挂载的访问模式。 instructions: type: string maxLength: 4096 description: 针对此绑定向模型展示的附加指引。 description: 创建时绑定到会话的记忆库。 title: 记忆库 SessionResourceVault: type: object required: - type - vault_id properties: type: type: string enum: - vault id: type: string description: 绑定时分配的会话资源 ID。 vault_id: type: string minLength: 1 maxLength: 128 description: 要绑定的凭据库（Vault）。 description: 绑定到会话的凭据库（Vault）。其凭据应用于该会话。 title: 凭据库 SessionState: type: string enum: - idle - running - stopping - terminated description: |- 会话或线程的当前生命周期状态。 - `idle`：未在执行。接受新输入。 - `running`：正在执行一个轮次。 - `terminated`：归档后的最终状态。 SessionStatusEvent: type: object required: - id - processed_at - type - data properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - session.status data: $ref: '#/components/schemas/SessionStatusPayload' description: 会话的状态发生变化。`data` 携带新状态，以及转为 `idle` 时的停止原因。 title: 会话状态 SessionStatusPayload: type: object required: - status properties: status: $ref: '#/components/schemas/SessionState' description: 新的会话状态。 stop_reason: $ref: '#/components/schemas/StopReasonInfo' description: 运行结束时的停止详情。 description: '`session.status` 的负载。' SessionThread: type: object required: - id - session_id - status - created_at - updated_at properties: id: type: string description: 线程 ID。 session_id: type: string description: 此线程所属的会话。 parent_thread_id: type: string description: 父线程。协调者线程不存在此字段。 agent: $ref: '#/components/schemas/SessionThreadAgent' description: 此线程使用的固定智能体版本。 status: $ref: '#/components/schemas/SessionState' description: 当前生命周期状态。 interrupted: type: boolean description: 执行是否因中断而暂停。 control_epoch: $ref: '#/components/schemas/ControlEpoch' description: 此线程当前的控制版本，与其他线程相互独立。 archived_at: type: string format: date-time description: 归档时间戳。活跃期间不存在。 created_at: type: string format: date-time description: 创建时间戳。 updated_at: type: string format: date-time description: 最后更新时间戳。 description: 逻辑会话内一个可独立执行的线程。 SessionThreadAgent: type: object required: - id - version - name properties: id: type: string description: 智能体 ID。 version: type: string description: 精确且不可变的智能体版本。 name: type: string description: 人类可读的智能体名称。 description: type: string description: 可选的智能体描述。 model: $ref: '#/components/schemas/ModelRef' description: 所选模型。 system: type: string description: 系统提示词。 tools: type: array items: $ref: '#/components/schemas/Tool' description: 线程可用的工具。 mcp_servers: type: array items: $ref: '#/components/schemas/McpServer' description: 线程可用的 MCP 服务器。 skills: type: array items: $ref: '#/components/schemas/SkillRef' description: 线程可用的精确技能版本。 description: 一个会话线程使用的固定智能体版本。 SessionThreadCreatedEvent: type: object required: - id - processed_at - type - data properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - session.thread_created data: $ref: '#/components/schemas/SessionThreadCreatedPayload' description: 会话中创建了一个子线程。`data` 携带新智能体的显示名。 title: 线程创建 SessionThreadCreatedPayload: type: object required: - agent_name properties: agent_name: type: string description: 新线程智能体的显示名称。 description: '`session.thread_created` 的负载。' SessionThreadList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/SessionThread' description: 本页的线程：协调者在前，然后是按创建顺序排列的子线程。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 一页线程：协调者在前，随后按创建顺序列出子线程。 SessionThreadStatusEvent: type: object required: - id - processed_at - type - data properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - session.thread_status data: $ref: '#/components/schemas/SessionThreadStatusPayload' description: 线程的状态发生变化。`data` 携带新状态，以及转为空闲时的停止原因。 title: 线程状态 SessionThreadStatusPayload: type: object required: - status properties: status: $ref: '#/components/schemas/SessionState' description: 线程的新状态。 stop_reason: $ref: '#/components/schemas/StopReasonInfo' description: 运行结束时的停止详情。 description: '`session.thread_status` 的负载。' SessionTitleUpdatedEvent: type: object required: - id - processed_at - type - data properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - session.title_updated data: $ref: '#/components/schemas/SessionTitleUpdatedPayload' description: 会话标题发生变化。`data` 携带新标题。 title: 会话标题更新 SessionTitleUpdatedPayload: type: object required: - title properties: title: type: string description: 会话的新标题。 description: '`session.title_updated` 的负载。' SessionUpdatedEvent: type: object required: - id - processed_at - type - data properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - session.updated data: $ref: '#/components/schemas/SessionUpdatedPayload' description: 会话更新实际变更了一个或多个字段。 title: 会话更新 SessionUpdatedPayload: type: object properties: agent: $ref: '#/components/schemas/SessionAgent' description: 变更后的生效智能体快照（已应用覆盖）；仅覆盖实际变化时携带。 agent_overrides: $ref: '#/components/schemas/SessionAgentOverrides' description: 变更后的会话级智能体配置覆盖（增量合并落库后的全量），仅当覆盖实际变化时携带，为空表示本次更新清空了全部覆盖。 title: type: string description: 会话的新标题；仅本次更新改了标题时携带。 description: '`session.updated` 的负载：会话更新实际变更至少一个字段时发出，只携带变更字段。同一会话的更新按提交顺序发布。配置变更自下一次唤醒生效；此通知不标记运行中的智能体何时开始使用该配置。' Skill: type: object required: - id - name - description - latest_version - status - created_at - updated_at - scope properties: id: type: string description: 技能 ID。 name: type: string description: 目录名称，是稳定的挂载与面向模型的标识符。同一项目内处于 active 状态的项目自有技能名称必须互不相同。归档技能会释放其名称，供后续技能使用。 description: type: string description: 向调用方展示的目录描述。 latest_version: type: string description: 当前可用的最新不可变版本（`"1"`、`"2"`……）。 status: $ref: '#/components/schemas/SkillStatus' description: 当前的目录状态。 created_at: type: string format: date-time description: 创建时间戳。 updated_at: type: string format: date-time description: 最后更新时间戳。 scope: $ref: '#/components/schemas/ResourceScope' description: 可见性范围。 display_name: type: string description: 向用户展示的技能名称。 icon_url: type: string description: 官方技能可选提供的图标 URL。 categories: type: array items: $ref: '#/components/schemas/SkillCategory' description: 技能的展示分类列表，来自固定词表。技能未分类时缺省。仅用于展示。 description: 稳定的技能身份。项目技能的元数据和包在创建时固定，官方技能的展示字段可由管理员维护。 SkillCategory: type: string enum: - featured - office_productivity - business_finance - content_creation - academic_research - marketing_growth - engineering description: 技能的展示分类，来自固定词表。 SkillList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/Skill' description: 本页中的技能。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 一页技能，按创建时间升序排列。已归档的技能不会出现在列表中。 SkillRef: type: object required: - skill_id properties: skill_id: type: string minLength: 1 description: 技能标识符。内置技能与自定义技能共用一个 ID 命名空间，二者通过 ID 前缀区分。 version: type: string description: 技能版本（`"1"`、`"2"`……）。省略时为当时的最新版本并固定；指定精确版本时固定使用该版本；传入 `"latest"` 时保留该值，并在读取或唤醒时重新解析。 description: 对附加到智能体的某个技能版本的引用。 SkillStatus: type: string enum: - active - archived description: 技能当前的目录状态。 SkillVersion: type: object required: - skill_id - version - name - description - created_at properties: skill_id: type: string description: 所属技能的 ID。 version: type: string description: 此 Skill 内 Hosted Agents 分配的不可变版本标识符（`"1"`、`"2"`……）。 name: type: string description: 此版本的 SKILL.md 声明的技能名称。 description: type: string description: 此版本的 SKILL.md 声明的技能描述。 created_at: type: string format: date-time description: 此版本的创建时间。 description: 技能的一个不可变包快照。 SkillVersionList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/SkillVersion' description: 本页中的版本。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 一页技能版本，最新在前。 StaticBearerCredential: type: object required: - type - mcp_server_url properties: type: type: string enum: - static_bearer mcp_server_url: type: string maxLength: 512 description: MCP 服务器的绝对 URI。创建后不可修改。 token: type: string maxLength: 8192 description: Bearer 令牌。请求中可携带，响应中绝不返回。 description: 用于 MCP 服务器的固定 Bearer 令牌凭据。无刷新流程。 title: 静态 Bearer 凭据 StopReason: type: string enum: - end_turn - canceled - internal_error - requires_action description: 会话运行停止的原因：`end_turn`：轮次正常完成，会话转为空闲并接受新输入。`canceled`：经 `user.interrupt` 事件取消，会话转为空闲并接受新输入。`internal_error`：平台内部失败，会话转为空闲，可重试。 StopReasonInfo: type: object required: - type properties: type: $ref: '#/components/schemas/StopReason' description: 运行停止的原因。仅在会话或线程转为空闲的状态事件上携带。 event_ids: type: array items: type: string description: 等待用户决定的待处理工具调用事件 ID；仅当 `type` 为 `requires_action` 时携带。`session.status` 事件汇总会话内全部等待线程，`session.thread_status` 事件只覆盖该线程。 description: 状态事件携带的停止详情。 StopWorkItemRequest: type: object required: - worker_id - generation properties: worker_id: type: string minLength: 1 description: 持有租约的 worker。 generation: type: integer format: int64 minimum: 1 description: 投递时返回的 fencing token。 final_status: type: string enum: - completed description: 省略时请求优雅停止；工具执行与结果回写结束后传入 `completed`，用于确认停止或释放空闲租约。 description: '`POST /v1/environments/{environment_id}/work/{id}/stop` 的请求体。' StringMetadata: type: object description: 用户定义的字符串值元数据（最多 16 个条目；键最长 64 个字符，值最长 512 个字符）。 maxProperties: 16 propertyNames: type: string maxLength: 64 additionalProperties: type: string maxLength: 512 StructuredToolResultContent: type: object oneOf: - title: 文本 $ref: '#/components/schemas/TextContentBlock' - title: 文件 $ref: '#/components/schemas/FileToolResultContent' - title: 图片 $ref: '#/components/schemas/ImageToolResultContent' - title: 产物 $ref: '#/components/schemas/ArtifactToolResultContent' discriminator: propertyName: type mapping: text: '#/components/schemas/TextContentBlock' file: '#/components/schemas/FileToolResultContent' image: '#/components/schemas/ImageToolResultContent' artifact: '#/components/schemas/ArtifactToolResultContent' description: 工具结果中的一个用户向渲染部分：Display 优先投影词汇，额外携带模型看不到的文件/产物卡片。 SystemTriggerContext: type: object required: - type properties: type: type: string enum: - system description: 由平台为管理该触发器的资源发起的运行上下文，例如 Dreams 策略的活跃度检查。 title: 系统 TextContentBlock: type: object required: - type - text properties: type: type: string enum: - text text: type: string description: 文本内容。 description: 纯文本块。 title: 文本 TextDeltaPayload: type: object required: - kind - delta properties: kind: type: string enum: - text delta: type: string description: 追加到进行中消息的增量文本。 description: 事件 `agent.delta` 的文本增量。 title: 文本增量 ThinkingContentBlock: type: object required: - type - thinking properties: type: type: string enum: - thinking thinking: type: string description: 推理内容。 description: 模型推理块。 title: 推理 ThinkingDeltaPayload: type: object required: - kind - delta properties: kind: type: string enum: - thinking delta: type: string description: 追加到进行中推理的增量文本。 description: 事件 `agent.delta` 的推理增量。 title: 推理增量 ThreadMessageReceivedPayload: type: object required: - content - from_session_thread_id properties: content: type: array items: $ref: '#/components/schemas/ContentBlock' description: 有序的内容部分。 from_session_thread_id: type: string description: 消息来源的线程。 from_agent_name: type: string description: 发送方智能体的显示名称（如果已知）。 description: '`agent.thread_message_received` 的负载。' ThreadMessageSentPayload: type: object required: - content - to_session_thread_id properties: content: type: array items: $ref: '#/components/schemas/ContentBlock' description: 有序的内容部分。 to_session_thread_id: type: string description: 消息发送目标的线程。 to_agent_name: type: string description: 接收方智能体的显示名称（如果已知）。 description: '`agent.thread_message_sent` 的负载。' TokenEndpointAuthType: type: string enum: - none - client_secret_basic - client_secret_post description: |- 刷新 OAuth 令牌时使用的认证方式。 - `none`：不做客户端认证。 - `client_secret_basic`：客户端凭据放在 Authorization 请求头中。 - `client_secret_post`：客户端凭据放在请求体中。 TooManyRequestsErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' Tool: type: object oneOf: - title: Agent 工具集 $ref: '#/components/schemas/AgentToolset' - title: 自定义工具 $ref: '#/components/schemas/CustomTool' - title: MCP 工具集 $ref: '#/components/schemas/McpToolset' discriminator: propertyName: type mapping: agent_toolset: '#/components/schemas/AgentToolset' custom: '#/components/schemas/CustomTool' mcp_toolset: '#/components/schemas/McpToolset' description: 智能体上的工具声明：内置工具集、客户端自定义工具或 MCP 工具集。 ToolConfig: type: object required: - name properties: name: type: string minLength: 1 description: 要配置的工具名称。 enabled: type: boolean description: 该工具是否启用。 permission_policy: $ref: '#/components/schemas/PermissionPolicy' description: 该工具的权限策略。 result_hint: type: string maxLength: 4096 description: 用于格式化成功结果的可选指令。 load_mode: $ref: '#/components/schemas/ToolLoadMode' description: 工具 schema 加载模式的覆盖设置。 description: 工具集内针对单个工具的覆盖设置。 ToolLoadMode: type: string enum: - eager - on_demand description: 控制工具 schema 的加载时机：`eager` 随智能体配置加载。`on_demand` 在首次需要该工具时加载，不支持按需加载时回退为 eager 加载。 ToolResultBlock: type: object required: - tool_use_id - structured_content - content - is_error properties: tool_use_id: type: string description: 此结果所属工具调用的标识符。 structured_content: type: array items: $ref: '#/components/schemas/StructuredToolResultContent' description: 按展示顺序排列的用户向渲染部分，Display 优先投影：工具提供 Display 块时为其内容；调用失败且无 Display 块时为统一失败文案；否则为模型向内容部分的投影。 content: type: array items: $ref: '#/components/schemas/ToolResultContent' description: 工具产出的模型向内容部分（其 Content），恒出现——即使与 `structured_content` 相同（接受重复，客户端无需跨字段回退）。工具无模型向内容时为空数组。调用失败时，这里携带 `structured_content` 的统一失败文案有意隐去的错误详情。 is_error: type: boolean description: 工具调用是否失败。 description: 一次已完成工具调用的结果。 ToolResultContent: type: object oneOf: - title: 文本 $ref: '#/components/schemas/TextContentBlock' - title: 图片 $ref: '#/components/schemas/ImageToolResultContent' - title: 视频 $ref: '#/components/schemas/VideoToolResultContent' discriminator: propertyName: type mapping: text: '#/components/schemas/TextContentBlock' image: '#/components/schemas/ImageToolResultContent' video: '#/components/schemas/VideoToolResultContent' description: 工具结果中的一个模型向内容部分：模型实际可消费的词汇（文本与媒体部分）；与用户向的 `StructuredToolResultContent` 不同，后者额外携带模型看不到的文件/产物卡片。 ToolResultContentBlock: type: object required: - type - tool_use_id - structured_content - content - is_error properties: type: type: string enum: - tool_result tool_use_id: type: string description: 此结果所属工具调用的标识符。 structured_content: type: array items: $ref: '#/components/schemas/StructuredToolResultContent' description: 按展示顺序排列的用户向渲染部分，Display 优先投影：工具提供 Display 块时为其内容；调用失败且无 Display 块时为统一失败文案；否则为模型向内容部分的投影。 content: type: array items: $ref: '#/components/schemas/ToolResultContent' description: 工具产出的模型向内容部分（其 Content），恒出现——即使与 `structured_content` 相同（接受重复，客户端无需跨字段回退）。工具无模型向内容时为空数组。调用失败时，这里携带 `structured_content` 的统一失败文案有意隐去的错误详情。 is_error: type: boolean description: 工具调用是否失败。 description: 工具结果块。工具结果的各字段与 `type` 值并排展开。 title: 工具调用结果 ToolUseBlock: type: object required: - id - name - input properties: id: type: string description: 服务端分配的工具调用标识符。 name: type: string minLength: 1 description: 被调用工具的名称。 input: type: object unevaluatedProperties: {} description: 自由格式的工具输入负载。 description: 智能体请求的一次工具调用。 ToolUseContentBlock: type: object required: - type - id - name - input properties: type: type: string enum: - tool_use id: type: string description: 服务端分配的工具调用标识符。 name: type: string minLength: 1 description: 被调用工具的名称。 input: type: object unevaluatedProperties: {} description: 自由格式的工具输入负载。 description: 工具调用块。工具调用的各字段与 `type` 值并排展开。 title: 工具调用 ToolUseDeltaPayload: type: object required: - kind - tool_use_id - input_delta properties: kind: type: string enum: - tool_use tool_use_id: type: string description: 正在流式传输的工具调用的标识符。 name: type: string description: 工具名称，仅在该次调用的首个增量中出现。 mcp: $ref: '#/components/schemas/MCPInfo' description: MCP 来源信息。工具为远程工具时，仅在首个增量中出现。 input_delta: type: string description: 工具输入的增量 JSON 片段。 description: 一次 `agent.delta` 事件的工具输入增量。 title: 工具调用增量 ToolsetDefaultConfig: type: object properties: enabled: type: boolean description: 工具集中的工具是否默认启用。 permission_policy: $ref: '#/components/schemas/PermissionPolicy' description: 默认权限策略。 load_mode: $ref: '#/components/schemas/ToolLoadMode' description: 默认的工具 schema 加载模式。未设置时，MCP 工具集使用 `on_demand`。`default_toolset_20260901` 中的 `search_image_by_text` 与 `search_image_by_image` 使用 `on_demand`，其余工具使用 `eager`。 description: 应用于工具集中每个工具的默认配置。 Trigger: type: object required: - id - name - status - agent_id - session_mode - policy - scope - created_by - created_at - updated_at properties: id: type: string description: 触发器 ID。 name: type: string description: 人类可读的触发器名称。 status: $ref: '#/components/schemas/TriggerStatus' description: 当前生命周期状态。 paused_reason: $ref: '#/components/schemas/PausedReason' description: 触发器暂停的原因。处于活跃状态时不存在。 agent_id: type: string description: 每次运行启动的智能体。 agent_version: type: string description: 精确的智能体版本（`"1"`、`"2"`……）。缺省时在触发时刻选择最新版本。使用 `reuse_session` 时，版本在首次运行创建托管会话时确定。 environment_id: type: string description: 承载触发器所启动会话的环境。 resources: type: array items: $ref: '#/components/schemas/SessionResource' description: 绑定到触发器所启动会话的资源。 initial_events: type: array items: $ref: '#/components/schemas/QueuedUserEventInput' description: 每次运行时添加到目标会话的开场消息，只支持 `user.message`。 session_mode: $ref: '#/components/schemas/SessionMode' description: 每次触发器运行使用哪个会话。 policy: $ref: '#/components/schemas/TriggerPolicy' description: 决定触发器何时运行的策略。 origin_type: type: string description: 创建或最后更新此触发器的不可变配置的类型，目前为 `dream_policy_version`。平台管理的触发器（此字段已设置）拒绝更新、暂停、恢复与归档——其生命周期跟随所属资源。仍可手动运行。 origin_id: type: string description: 该不可变配置的 ID，例如 Dreams 策略版本 ID。 last_run_at: type: string format: date-time description: 触发器上次触发的时间。 upcoming_runs_at: type: array items: type: string format: date-time description: 即将到来的运行时间的近似值（UTC，最多 5 个）。仅活跃的 cron 触发器存在。 scope: $ref: '#/components/schemas/ResourceScope' description: 可见性范围。 created_by: type: string description: 创建者的用户 ID。 created_at: type: string format: date-time description: 创建时间戳。 updated_at: type: string format: date-time description: 最后更新时间戳。 archived_at: type: string format: date-time description: 归档时间戳。处于活跃或暂停状态时不存在。 notification: $ref: '#/components/schemas/TriggerNotification' description: TriggerRun 通知的 webhook 配置。缺省则禁用投递。 description: 保存的规则，按计划或按需启动智能体。 TriggerContext: type: object oneOf: - title: 调度 $ref: '#/components/schemas/ScheduleTriggerContext' - title: 手动 $ref: '#/components/schemas/ManualTriggerContext' - title: 系统 $ref: '#/components/schemas/SystemTriggerContext' discriminator: propertyName: type mapping: schedule: '#/components/schemas/ScheduleTriggerContext' manual: '#/components/schemas/ManualTriggerContext' system: '#/components/schemas/SystemTriggerContext' description: 触发器运行的成因：cron 调度、手动运行或平台发起。客户端须容忍新增的上下文类型。 TriggerError: type: object required: - type - message properties: type: type: string description: |- 仅供展示的领域取值，不属于 HTTP `error.type` 词汇表。客户端须容忍列表外的新增取值。除 `session_failed`、`session_queue_full`、`fire_failed` 与 `overlap_in_flight` 外，其余取值将运行记为 `failed` 并自动暂停触发器；`fire_failed` 将运行记为 `failed`，下一次调度重试；`session_failed`、`session_queue_full` 与 `overlap_in_flight` 将运行记为 `skipped` 并推进调度，其中同一会话连续 3 次因前两类原因跳过才暂停触发器，其他结果重置计数。 | 取值 | 含义 | | ---- | ---- | | `agent_not_found` | 智能体已不存在。 | | `agent_archived` | 智能体已归档。 | | `environment_missing` | 触发器未绑定环境（仅存量触发器可能没有绑定环境）。 | | `environment_not_found` | 环境已不存在。 | | `environment_archived` | 环境已归档。 | | `vault_not_found` | 绑定的凭据库已不存在。 | | `vault_archived` | 绑定的凭据库已归档。 | | `memory_store_not_found` | 绑定的记忆库已不存在。 | | `memory_store_archived` | 绑定的记忆库已归档。 | | `model_route_invalid` | 触发器的模型路由不可用。 | | `session_terminated` | `reuse_session` 触发器的托管会话已终止。 | | `session_failed` | 托管会话上次因执行错误停止，当前空闲。 | | `session_queue_full` | 托管会话的输入队列已满。 | | `fire_failed` | 触发链路失败。 | | `overlap_in_flight` | 上一次运行或托管会话仍在执行中。 | message: type: string description: 人类可读的失败详情。 description: 触发器运行或错误暂停的触发器携带的结构化失败信息。 TriggerList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/Trigger' description: 本页中的触发器。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 一页触发器，最新在前。 TriggerNotification: type: object required: - url - secret_vault properties: url: type: string maxLength: 1024 description: 接收运行和自动暂停通知的 HTTPS 端点。 secret_vault: $ref: '#/components/schemas/NotificationVaultRef' description: 存放签名密钥的凭据库（Vault）：其中名为 `webhook_secret` 的 `environment_variable` 凭据。其值从不出现在 API 读取中。凭据在投递时解析，创建时不校验。 description: |- 运行和自动暂停通知的 webhook 配置。缺省则禁用投递。 仅计划（cron）运行会投递，手动运行不投递。每次投递都是一次 HTTPS POST，JSON 负载为 `{"type": "event", "id": <投递 id>, "created_at": , "data": {"type": <事件>, "id": <资源 id>, "scope_ref": <项目 scope>}}`。运行事件为 `trigger_run.started`、`trigger_run.succeeded` 和 `trigger_run.failed`，`data.id` 为 TriggerRun ID。从活跃状态自动转为暂停时，还会发送 `trigger.paused`，`data.id` 为触发器 ID；查询该触发器即可获取 `paused_reason`。跳过的运行不发送运行事件，但可能触发这条暂停事件。每次投递携带 `Webhook-Id`、`Webhook-Timestamp` 与 `Webhook-Signature: v1,` 三个头。签名是对 `"..<原始正文>"` 的 HMAC-SHA256 的 base64 编码（standard-webhooks 方案）。投递为至少一次：最多 3 次尝试，按 5s/10s 退避。2xx 视为成功，重试耗尽的投递会被丢弃。 TriggerPolicy: type: object oneOf: - title: cron 调度 $ref: '#/components/schemas/CronTriggerPolicy' discriminator: propertyName: type mapping: cron: '#/components/schemas/CronTriggerPolicy' description: 决定触发器何时触发的规则。 TriggerPolicyType: type: string enum: - cron description: 策略种类，用作列表筛选条件。 TriggerRun: type: object required: - id - trigger_id - status - created_at properties: id: type: string description: 触发器运行 ID。 trigger_id: type: string description: 本次运行所属的触发器。 status: $ref: '#/components/schemas/TriggerRunStatus' description: 当前运行状态。 context: $ref: '#/components/schemas/TriggerContext' description: 本次运行发生的原因。 session_id: type: string description: 本次运行创建的会话。分配前不存在。 agent_version: type: string description: '`session_id` 对应会话的智能体版本，在运行投递到该会话时记录，之后更新触发器不会改变它。运行未记录会话时缺省，2026-10-14 之前记录的运行也缺省。' error: $ref: '#/components/schemas/TriggerError' description: 本次运行的结构化失败或跳过原因。`failed` 运行，以及因重叠、会话执行错误或队列满而 `skipped` 的运行携带。 created_at: type: string format: date-time description: 创建时间戳。 finished_at: type: string format: date-time description: 终止时间戳。运行进行期间不存在。 description: 一次触发器运行的记录：其目标会话、终态状态，以及失败时的失败详情。 TriggerRunList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/TriggerRun' description: 本页中的运行。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 一页触发器运行，最新在前。 TriggerRunStatus: type: string enum: - pending - running - completed - failed - skipped description: 一次触发器运行的生命周期状态。 TriggerStatus: type: string enum: - active - paused - archived description: 触发器的生命周期状态。 UnauthorizedErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' UpdateAgentRequest: type: object properties: version: type: string description: 智能体当前的 `version`。如果智能体在此之后发生变更，请求返回 409 `conflict_error`。 name: type: string maxLength: 256 description: 人类可读的智能体名称。 model: $ref: '#/components/schemas/ModelRef' description: 所选模型。 description: type: string maxLength: 2048 description: 可选的人类可读描述。 system: type: string maxLength: 100000 description: 系统提示词。 tools: type: array items: $ref: '#/components/schemas/Tool' maxItems: 128 description: 替换工具列表。 mcp_servers: type: array items: $ref: '#/components/schemas/McpServer' maxItems: 20 description: 替换 MCP 服务器连接列表。名称必须唯一。 skills: type: array items: $ref: '#/components/schemas/SkillRef' description: 替换技能列表。 plugins: type: array items: $ref: '#/components/schemas/PluginRef' description: 替换插件列表。 metadata: $ref: '#/components/schemas/StringMetadata' description: 替换元数据（最多 16 个条目）。 multiagent: $ref: '#/components/schemas/MultiagentCoordinator' description: 替换当前协调者配置。发送空的 `agents` 数组即可清空。 description: 更新智能体的部分更新请求体。只有出现的字段会变更，且更新会创建一个新的不可变版本。出现的数组与 metadata 映射会整体替换已存储的值（发送空值即可清空）。 UpdateDreamPolicyRequest: type: object required: - activity - schedule properties: agent_id: type: string maxLength: 128 description: 自动 Dreams 使用的智能体。留空则选择平台官方 Dreams 智能体。 activity: $ref: '#/components/schemas/DreamActivityTrigger' description: 活动条件。即使未启用，该对象也必填。 schedule: $ref: '#/components/schemas/DreamScheduleTrigger' description: 调度条件。即使未启用，该对象也必填。 environment_id: type: string maxLength: 128 description: 承载 Dreams 会话的环境。任一条件启用时必填。 description: 用于整体替换某个记忆库的 Dreams 设置。两个触发器都会整体替换。两者都禁用时，策略处于非活跃状态。 UpdateEnvironmentRequest: type: object properties: name: type: string maxLength: 256 description: 人类可读的环境名称。空值会被拒绝：名称不能清空。 description: type: string maxLength: 2048 description: 可选的人类可读描述。空值会清空描述。 config: $ref: '#/components/schemas/EnvironmentConfig' description: 替换执行配置。 metadata: $ref: '#/components/schemas/StringMetadata' description: 替换元数据。空值会清空整个映射。 description: 更新环境的部分更新请求体。展示字段就地更新。替换 config 会生成一个新的不可变版本，仅由之后创建的会话固定使用。config 类型不可变更。 UpdateMemoryRequest: type: object properties: path: type: string minLength: 1 maxLength: 900 description: 新路径，最长 900 UTF-8 字节。校验规则与创建相同。 content: type: string description: 替换后的内容，base64 编码，解码后不超过 20 MiB。 content_sha256: type: string pattern: ^[0-9a-f]{64}$ description: |- 可选的乐观并发检查：回显该记忆当前的 `content_sha256`。 不匹配时更新将失败并返回 409。 description: |- 更新记忆文件的部分更新请求体：可更新内容、路径或两者。 `content_sha256` 是针对当前文件正文的乐观并发检查。 UpdateMemoryStoreRequest: type: object properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[\p{L}\p{N}][\p{L}\p{N}_-]{0,63}$ description: 新名称（命名规则与创建时相同）。 description: type: string maxLength: 4096 description: 新描述。 description: 更新记忆库的部分更新请求体。 UpdateSessionRequest: type: object properties: title: type: string maxLength: 256 description: 新的人类可读标题。 agent_overrides: $ref: '#/components/schemas/SessionAgentOverrides' description: 替换会话级的智能体覆盖配置：每个出现的集合都会整体替换该集合的覆盖值（空数组会清空它并回退到冻结的智能体值）。未出现的集合保持当前覆盖值不变。 description: 更新会话的部分更新请求体。目前仅 `title` 和 `agent_overrides` 可修改。 UpdateTriggerNotification: type: object properties: url: type: string maxLength: 1024 description: 接收 TriggerRun 通知的 HTTPS 端点。 secret_vault: $ref: '#/components/schemas/NotificationVaultRef' description: 存放签名密钥的凭据库（Vault）：其中名为 `webhook_secret` 的 `environment_variable` 凭据。其值从不出现在 API 读取中。 description: |- 更新用的 webhook 配置：提供对象时替换当前配置，提供空对象 `{}` 时解除当前配置。 `url` 与 `secret_vault` 必须同时设置——服务端在配置投递时始终要求签名密钥。只设置其一会被拒绝（400 `invalid_parameter_error`）。 UpdateTriggerRequest: type: object properties: name: type: string minLength: 1 maxLength: 256 description: 人类可读的触发器名称。 agent_id: type: string minLength: 1 maxLength: 128 description: 每次运行启动的智能体。 agent_version: type: string maxLength: 128 description: 精确的智能体版本（`"1"`、`"2"`……）。空值表示在触发时刻选择最新版本。 environment_id: type: string maxLength: 128 description: 承载触发器所启动会话的环境。省略时沿用当前环境；空值会被拒绝。 resources: type: array items: $ref: '#/components/schemas/SessionResource' maxItems: 16 description: 替换绑定到触发器所启动会话的资源。 initial_events: type: array items: $ref: '#/components/schemas/QueuedUserEventInput' maxItems: 16 description: 替换每次运行时投递的开场消息，只支持 `user.message`；空数组清空这些消息。 session_mode: $ref: '#/components/schemas/SessionMode' description: 每次触发器运行使用哪个会话。 notification: $ref: '#/components/schemas/UpdateTriggerNotification' description: 替换 TriggerRun 通知的 webhook 配置。提供空对象 `{}` 时解除当前配置。 policy: $ref: '#/components/schemas/TriggerPolicy' description: 替换决定触发器何时运行的策略。 description: 更新触发器的部分更新请求体：只有出现的字段会变更。状态流转不通过更新进行。请使用暂停、恢复或归档操作。 UpdateVaultCredentialRequest: type: object properties: display_name: type: string minLength: 1 maxLength: 256 description: 人类可读的凭据名称。 auth: $ref: '#/components/schemas/VaultCredentialAuth' description: 替换后的认证负载。类型必须与现有凭据一致。 description: 轮换或重命名凭据的部分更新请求体。字段按字段合并：提供的值替换已存储的值，省略、null 或空值保留原值——秘密值无法通过更新清空。对于 environment_variable 凭据，networking 为整体替换、injection_location 按字段合并。对于 mcp_oauth，refresh 块按字段合并，唯一例外是 `mcp_oauth.egress_environment_id`：传空字符串会清除绑定。认证类型及其标识字段（secret_name、mcp_server_url、token_endpoint、client_id）不可变。 UpdateVaultRequest: type: object properties: display_name: type: string minLength: 1 maxLength: 256 description: 人类可读的凭据库（Vault）名称。 metadata: $ref: '#/components/schemas/StringMetadata' description: 整体替换现有元数据。传入空对象则清空。 description: 修改凭据库（Vault）的请求体。省略的字段保持不变。 UploadFilename: type: string maxLength: 4096 description: 上传时显式指定的文件名，覆盖文件部分自身的名称。 UserCustomToolResultEvent: type: object required: - id - processed_at - type - data properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - user.custom_tool_result data: $ref: '#/components/schemas/UserCustomToolResultPayload' description: API 调用方返回了一次自定义工具调用的结果。 title: 自定义工具结果 UserCustomToolResultInput: type: object required: - type - data properties: type: type: string enum: - user.custom_tool_result data: $ref: '#/components/schemas/UserCustomToolResultPayload' description: 返回一次自定义工具调用的结果。 title: 自定义工具结果 UserCustomToolResultPayload: type: object required: - event_id properties: event_id: type: string minLength: 1 description: 本结果所回复的 `agent.custom_tool_use` 事件 ID。 content: type: array items: $ref: '#/components/schemas/ToolResultContent' description: 按顺序排列的模型向结果内容；缺省或空数组表示空结果。 is_error: type: boolean description: 工具调用是否失败，默认为 `false`。 description: API 调用方为一次自定义工具调用返回的结果。 UserEventInput: type: object oneOf: - title: 用户消息 $ref: '#/components/schemas/UserMessageInput' - title: 用户中断 $ref: '#/components/schemas/UserInterruptInput' - title: 用户工具确认 $ref: '#/components/schemas/UserToolConfirmationInput' - title: 自定义工具结果 $ref: '#/components/schemas/UserCustomToolResultInput' - title: 用户工具结果 $ref: '#/components/schemas/UserToolResultInput' discriminator: propertyName: type mapping: user.message: '#/components/schemas/UserMessageInput' user.interrupt: '#/components/schemas/UserInterruptInput' user.tool_confirmation: '#/components/schemas/UserToolConfirmationInput' user.custom_tool_result: '#/components/schemas/UserCustomToolResultInput' user.tool_result: '#/components/schemas/UserToolResultInput' description: 客户端可发送给会话的入站事件。与相应会话事件具有相同的 `type` + `data` 结构，但不含服务器分配的错误响应 JSON 字段。 UserInterruptEvent: type: object required: - id - processed_at - type properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - user.interrupt description: 记录用户请求的会话停止。事件到达时，会话可能仍处于 `stopping`。不携带 `data`。 title: 用户中断 UserInterruptInput: type: object required: - type properties: type: type: string enum: - user.interrupt data: type: object properties: expected_control_epoch: $ref: '#/components/schemas/ControlEpoch' description: 期望的 `control_epoch`。省略时停止当前控制版本。已中断时，当前或紧邻的前一个版本均返回相同结果，不递增版本；未中断时只接受当前版本。其他值返回 409 `conflict_error`。 description: 可选的并发检查，避免误停更新的控制版本。 description: '停止会话及其活跃线程，空闲会话也接受停止。它必须是请求中唯一的事件，请求的 `type` 字段会被忽略。响应在收尾完成前确认停止请求。GET 会话的 `control_epoch` 大于停止响应中的值时，无论状态如何都可结束等待；两者相等时，须等待状态为 `idle` 或 `terminated`。未归档会话收尾后处于 `idle`，并保持 `interrupted: true`，直到恢复。中断暂停待处理输入，不会将其丢弃。显式继续不需要令牌，恢复当前已停止的会话。' title: 用户中断 UserMessageEvent: type: object required: - id - processed_at - type - data properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - user.message data: $ref: '#/components/schemas/UserMessagePayload' description: 用户消息已投递给智能体。`data` 携带按序排列的内容块；当消息来自输入队列时，事件复用该输入的 `event_id` 作为自己的 `id`。 title: 用户消息 UserMessageInput: type: object required: - type - data properties: type: type: string enum: - user.message data: $ref: '#/components/schemas/UserMessagePayload' description: 发送用户消息。 title: 用户消息 UserMessagePayload: type: object properties: content: type: array items: $ref: '#/components/schemas/ContentBlock' description: 用户消息的有序内容部分。内容缺省或为空时，将以平台默认提示词（`Continue.`）唤醒智能体。 description: 事件 `user.message` 的负载。 UserToolConfirmationEvent: type: object required: - id - processed_at - type - data properties: id: type: string description: 服务端分配的事件标识符。 processed_at: type: string format: date-time description: 事件被处理并写入会话历史的时刻。列表排序与分页以此字段为准。 session_thread_id: type: string description: 产生该事件的线程。协调者级别的事件不存在此字段。 epoch: $ref: '#/components/schemas/ControlEpoch' description: 产生该事件的线程的控制版本。旧事件和辅助事件不携带此字段。 type: type: string enum: - user.tool_confirmation data: $ref: '#/components/schemas/UserToolConfirmationPayload' description: 用户允许或拒绝了一个待处理的工具调用。 title: 用户工具确认 UserToolConfirmationInput: type: object required: - type - data properties: type: type: string enum: - user.tool_confirmation data: $ref: '#/components/schemas/UserToolConfirmationPayload' description: 确认或拒绝待处理的工具调用。 title: 用户工具确认 UserToolConfirmationPayload: type: object required: - event_id - result properties: event_id: type: string minLength: 1 description: 要确认的工具调用事件 ID。 result: $ref: '#/components/schemas/UserToolConfirmationResult' description: 用户是否允许该工具调用。 deny_message: type: string maxLength: 10000 description: 拒绝时的可选说明。允许执行时必须为空。 description: 待处理工具调用的确认决定。 UserToolConfirmationResult: type: string enum: - allow - deny description: 待处理工具调用的确认结果。 UserToolResultInput: type: object required: - type - data properties: type: type: string enum: - user.tool_result data: $ref: '#/components/schemas/UserToolResultPayload' description: 返回在自托管环境中执行的工具调用的结果。 title: 用户工具结果 UserToolResultPayload: type: object required: - tool_use_id - is_error properties: tool_use_id: type: string minLength: 1 description: 该结果所应答的 `agent.tool_use` 调用标识（`tool_use.id`）。 content: type: array items: $ref: '#/components/schemas/ContentBlock' description: 按序排列的结果内容块；缺省或为空时，等待中的工具调用收到空结果。 is_error: type: boolean description: 工具调用是否失败。 session_thread_id: type: string description: 发出对应 `agent.tool_use` 事件的线程。省略时应答主线程的调用。 description: 在自托管环境中执行的工具调用所返回的结果。 ValidatePluginResponse: type: object required: - report properties: report: $ref: '#/components/schemas/PluginValidationReport' description: 所提交插件包的校验结果，`ok` 为 true 或 false 均通过本响应返回。 description: 仅校验、不发布时返回的插件包校验结果。 Vault: type: object required: - id - display_name - created_at - updated_at properties: id: type: string description: 凭据库（Vault）ID。 display_name: type: string description: 人类可读的凭据库（Vault）名称。不要求唯一。 metadata: $ref: '#/components/schemas/StringMetadata' description: 调用方自定义的字符串元数据，最多 16 条。 created_at: type: string format: date-time description: 创建时间戳。 updated_at: type: string format: date-time description: 最后更新时间戳。 archived_at: type: string format: date-time description: 归档时间戳。活跃期间不含此字段。 description: 凭据库（Vault）：与单个最终用户关联的凭据集合。 VaultCredential: type: object required: - id - vault_id - display_name - auth - created_at - updated_at properties: id: type: string description: 凭据 ID。 vault_id: type: string description: 所属凭据库（Vault）的 ID。 display_name: type: string description: 人类可读的凭据名称。 auth: $ref: '#/components/schemas/VaultCredentialAuth' description: 认证负载。敏感字段在响应中一律被清除。 created_at: type: string format: date-time description: 创建时间戳。 updated_at: type: string format: date-time description: 最后更新时间戳。 archived_at: type: string format: date-time description: 归档时间戳。活跃期间不含此字段。 description: 凭据库（Vault）中存储的一条凭据。唯一键——`mcp_oauth`/`static_bearer` 为规范化后的 `mcp_server_url`，`environment_variable` 为 `secret_name`——在同一凭据库的活跃凭据中不可重复。 VaultCredentialAuth: type: object oneOf: - title: MCP OAuth 凭据 $ref: '#/components/schemas/MCPOAuthCredential' - title: 静态 Bearer 凭据 $ref: '#/components/schemas/StaticBearerCredential' - title: 环境变量凭据 $ref: '#/components/schemas/EnvironmentVariableCredential' discriminator: propertyName: type mapping: mcp_oauth: '#/components/schemas/MCPOAuthCredential' static_bearer: '#/components/schemas/StaticBearerCredential' environment_variable: '#/components/schemas/EnvironmentVariableCredential' description: 凭据库（Vault）凭据的认证负载。类型在创建后不可更改。所有敏感字段均为只写：请求中可提交，在所有响应中都会被清除。 VaultCredentialList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/VaultCredential' description: 本次请求返回的凭据。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 一页凭据，最新者在前。秘密值不返回。 VaultList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/Vault' description: 本次请求返回的凭据库（Vault）。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 一页凭据库（Vault），最新者在前。 VaultOAuthClient: type: object required: - client_id properties: client_id: type: string minLength: 1 maxLength: 256 description: 在授权服务器注册的 OAuth 客户端 ID。 client_secret: type: string maxLength: 8192 description: 客户端密钥。仅在请求中接受，响应中不返回。 token_endpoint_auth_type: $ref: '#/components/schemas/TokenEndpointAuthType' description: 令牌端点的认证方式。省略时按是否提供客户端密钥推导：提供了客户端密钥为 `client_secret_post`，否则为 `none`。 scope: type: string maxLength: 1024 description: 覆盖自动发现的范围集合（以空格分隔）。 description: 用户自带的授权流程 OAuth 客户端（BYO）。 VaultOAuthSession: type: object required: - status properties: status: $ref: '#/components/schemas/VaultOAuthSessionStatus' description: 当前状态。 error: type: string description: 人类可读的失败原因。仅当 `status` 为 `failed` 时存在。 credential_id: type: string description: 已创建的凭据的 ID。仅当 `status` 为 `authorized` 时存在。 description: 一次 OAuth 授权会话的当前状态。 VaultOAuthSessionConflictErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' VaultOAuthSessionStatus: type: string enum: - pending - authorized - failed description: |- MCP OAuth 授权会话的当前状态。 - `pending`：授权流程进行中。 - `authorized`：授权成功。`credential_id` 存在。 - `failed`：授权流程失败。`error` 携带原因。 VideoToolResultContent: type: object required: - type - url - mime_type properties: type: type: string enum: - video url: type: string description: 可获取视频的 URL。 mime_type: type: string description: 视频的 MIME 类型。 description: 展示给模型的视频部分（video part）的 URL。 title: 视频 WorkHeartbeat: type: object required: - last_heartbeat - lease_extended - state - ttl_seconds - generation properties: last_heartbeat: type: string format: date-time description: 最近一次续租时刻。 lease_extended: type: boolean description: 心跳是否续租成功（成功时恒为 true；失败返回 412）。 state: $ref: '#/components/schemas/WorkItemStatus' description: 更新后的生命周期状态。 ttl_seconds: type: integer format: int64 description: 自心跳时刻起生效的租约时长（秒）。 generation: type: integer format: int64 description: 工作行的当前 fencing token，与心跳后的租约状态一起返回。 description: 心跳成功后工作行的租约状态。 WorkItem: type: object required: - id - session_id - environment_id - status - generation - lease_ttl_ms - created_at properties: id: type: string description: 工作行 ID。 session_id: type: string description: 该工作行所属的会话。 environment_id: type: string description: 可认领该工作行的环境。 status: $ref: '#/components/schemas/WorkItemStatus' description: 生命周期状态；poll 只返回 `queued`。 generation: type: integer format: int64 minimum: 1 description: fencing token：从 1 开始，平台每次将失联 worker 的工作行重新入队时加 1。在心跳、ack、stop 时携带当前值；过期的 token 将被拒绝并返回 412 `failed_precondition_error`。工具结果回写改由会话级 work token 承载 fencing，该路径无需显式携带 generation。 worker_id: type: string description: 持有租约的 worker。 lease_ttl_ms: type: integer format: int64 description: 租约时长（毫秒）；心跳会续租。 created_at: type: string format: date-time description: 工作行的入队时间。 claimed_at: type: string format: date-time description: 当前认领的发生时间。 acknowledged_at: type: string format: date-time description: worker 确认投递的时间——在投递窗口内由 ack 调用打戳。 started_at: type: string format: date-time description: 首次心跳把行激活为 active 的时间（starting → active 时打戳）。 latest_heartbeat_at: type: string format: date-time description: 最近一次心跳落库时间；首次心跳前缺省。 stop_requested_at: type: string format: date-time description: 首次停止请求时间，租约回收后保留。 stopped_at: type: string format: date-time description: 工作行进入终态的时间；活跃期间缺省。 secret: type: string description: '工作行所属会话的凭据包，仅在认领该工作行的 poll 响应中出现：base64url 编码的 JSON 对象。worker 解码该包，将其 `sessions_token` 成员作为 `Authorization: Bearer` 凭据用于该会话的写路径（如 `POST /v1/sessions/{id}/events`）以及该工作行的 ack/heartbeat/stop，作用域仅限该会话。包内其余成员保留，不得消费。凭据在工作行终结或被回收后失效——回收会将工作行交给持有新凭据的接替 worker，本凭据随即作废。任何其他端点都不会返回它。按机密处理：不要记录日志或持久化。' description: 自托管工作队列中的一行：其沙箱工具调用在环境属主的 worker 上执行的会话。`GET /v1/environments/{environment_id}/work/poll` 投递工作行（ack 前仍为 `queued`）；其携带的 `generation` 是 fencing token，后续每次 ack、心跳、stop 都必须携带。`user.tool_result` 回写无需显式携带：`secret` 中的会话级 work token 已绑定签发代次，平台由它派生 fencing。 WorkItemList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/WorkItem' description: 本页中的工作行。 next_page_token: type: string description: 下一页的分页令牌。列表耗尽时缺省。 description: 一页工作行，最新在前。 WorkItemStatus: type: string enum: - queued - starting - active - stopping - completed - failed - cancelled description: 工作行（WorkItem）的生命周期状态：`queued` 覆盖未投递与已投递未确认（等待 ack 的投递仍属队列事务）；ack 后进入 `starting`；首个心跳激活为 `active`；停止请求进入 `stopping`，worker 确认收尾后记为 `completed`。空闲 worker 可直接完成。历史 `failed` 和 `cancelled` 行仍可读取。 WorkQueueStats: type: object required: - depth - claimed - workers properties: depth: type: integer format: int64 description: 待认领的工作行数。 claimed: type: integer format: int64 description: 租约中的工作行数。 workers: type: integer format: int64 description: 当前持有租约的不同 worker 数。 oldest_queued_at: type: string format: date-time description: 最老待认领行的入队时间；无待认领行时缺省。 description: 环境工作队列的统计，按活跃行实时计算。 securitySchemes: BearerAuth: type: http scheme: Bearer servers: - url: https://api.moonshot.cn description: 生产环境 variables: {}