> ## Documentation Index > Fetch the complete documentation index at: https://platform.kimi.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 创建触发器 > 创建一个处于活跃状态的触发器，为智能体启动会话。 - cron 策略接受分钟粒度的五字段表达式和一个 IANA `timezone`。实际触发会加入少量抖动。 - 智能体、环境、凭据库与记忆库引用在创建时校验。一个项目最多持有 200 个未归档的触发器。 - 每次触发向本次运行的会话投递 `initial_events` 和一条平台上下文消息。 ## OpenAPI ````yaml /openapi-hosted-agents.yaml post /v1/triggers openapi: 3.1.0 info: title: Kimi 托管智能体 version: 2026-09-01-beta description: >- Kimi 托管智能体的公共 REST API。 ## 认证 每个操作都使用 `Authorization: Bearer sk-...` 认证。不要在其他请求头中发送 API 凭据。 ## 资源标识符 资源 ID 是带资源专属前缀的不透明字符串。客户端应将 ID 作为完整值使用，不要解析后缀。 ## 核心概念 **智能体（Agent）**是版本化的智能体配置。**会话（Session）**是绑定到冻结智能体版本的一次进行中的对话。会话运行在一个协调者**线程**上，线程可以把工作委托给子线程。线程的每个轮次都会向会话事件流发送事件。 **凭据库（Vault）**持有项目级凭据，秘密值为只写。**环境（Environment）**描述会话运行所在的云沙箱。**记忆库（Memory Store）**是项目级文件存储，挂载进会话。**梦境（Dream）**是平台对一个记忆库执行的记忆维护。 **触发器（Trigger）**按计划或手动启动会话，每次执行记录为一次 **TriggerRun**。**产物（Artifact）**是会话交付的可下载文件。**插件（Plugin）**为智能体打包 MCP 服务器与技能。 **协调者**是会话的主线程，用户输入先到达它。模型提供方操作中的 `provider binding` 指调用方为该提供方配置的接入。 ## 版本控制 `kimi-api-version` 请求头选择本次请求使用的 API 版本（`YYYY-MM-DD`，与每个规范修订版的 `info.version` 对应）。未知值将被拒绝，返回 400 `invalid_request_error`。若要使用本文档所述版本，请在请求中携带 `kimi-api-version: 2026-09-01-beta`。省略请求头时，兼容行为仅适用于 `/v1/files*`：上传与删除将返回 200（而非 201/204），文件记录使用 `status`、`status_details` 字段（而非 `extract_status`），且上传的文件不能挂载到会话。其他端点均按本文档契约处理。 **破坏性变更只会随新的带日期版本发布。** 破坏性变更包括： - 删除或重命名端点、字段或枚举值 - 改变字段的类型或含义 - 新增必填请求字段或收窄可接受的输入 - 改变默认行为 - 删除错误类型或改变其含义 非破坏性变更（可随时发布；客户端必须容忍）：新端点、新的可选请求字段、新的响应字段或响应头、响应侧枚举中的新值（包括错误类型词汇表）、新的错误类型，以及文档或消息措辞更新。 带 `-beta` 后缀的版本是预览版：行为仍可能调整、不承诺完全兼容，但调用方可见的变更会在 ChangeLog 与发布说明中通知。稳定版在其后继版本发布后仍然可用。退役会提前在发布说明中公告，但不承诺固定窗口。版本进入退役状态后，其响应会携带 `Deprecation: true` 和 `Sunset: ` 响应头。Sunset 日期之后，该退役值会被视为未知值而拒绝。 ## 幂等 创建操作（创建资源或触发运行的 `POST` 端点）接受可选的 `Idempotency-Key` 请求头（最长 255 个字符；UUID 是不错的选择）。第一个请求的响应会保存 24 小时，作用域限定在你的项目和该端点：用相同的键和相同的请求体重试，会原样重放该响应（状态码和响应体）而不会重新执行。用不同的请求体复用同一个键，或在第一个请求仍在处理中时复用，返回 409 `conflict_error`。校验失败（400）和服务器错误（5xx）从不会被保存，因此重试这些请求总是安全的。键在 24 小时后过期，之后被视为新键。 ## 错误 所有非 2xx 响应共用一个错误响应 JSON 格式：`{"error": {type, message, request_id, param?}}`。每个响应（无论成功还是错误）都携带 `Msh-Request-Id` 响应头，其值与错误体中的 `request_id` 一致。 `error.type` 是一个包含 10 个值的封闭词汇表——每个值对应一种客户端恢复策略，且各自固定映射到一个 HTTP 状态码： | 错误类型 | 状态码 | 含义 → 恢复方式 | | --- | --- | --- | | `invalid_parameter_error` | 400 | 某个字段未通过校验。`param` 指出该字段——修复字段后重试 | | `invalid_request_error` | 400 | 请求本身格式错误（无法解析的请求体、错误的方法、请求体过大、未知的 API 版本）——修复请求 | | `failed_precondition_error` | 400 | 资源当前状态不允许该操作——先改变状态（消息中说明了方法） | | `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 | 平台内部故障，包括暂时不可用——通用消息。退避（1s → 2s → 4s）后重试 | 可定位到字段的失败始终是带 `param` 的 `invalid_parameter_error`。无法归咎于单一字段的失败是不带 `param` 的 `invalid_request_error`。只有 `rate_limit_reached_error` 携带 `Retry-After`。 嵌入资源内部的错误字段（例如 `TriggerRun.error`）复用同一错误响应 JSON，但其 `type` 是领域专属的分类（例如 `fire_failed`），不属于上述 10 个值——仅用于展示。客户端必须容忍未知值。 ## 会话执行错误 `session_error` 事件报告已创建会话期间发生的失败。它不是 HTTP 错误响应。其 `error_type` 使用独立于 HTTP `error.type` 的封闭词表： | `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` | 本轮达到步数上限——发送新消息继续 | 这些值描述失败的模型轮次，其 message 会给出下一步操作。客户端必须将该事件与 HTTP `error.type` 分开处理。 ## 分页 列表操作接受 `page_size`（1–1000，默认 50）和不透明的 `page_token`，返回 `{items, next_page_token}`。`next_page_token` 缺失表示已到最后一页。 ## 速率限制与大小上限 请求可能受到速率限制。被限流的请求返回 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` | 每个 Skill 包 64 MiB | ## 事件流（SSE） Session 和线程事件流（`GET .../events/stream`）将事件封装为：`event:` = 事件类型，`id:` = 恢复游标，`data:` = 完整的事件 JSON，并每 30 秒发送一个 `: hb` 心跳。流建立之前发生的失败返回标准错误响应 JSON。流中途发生的失败以一个携带相同错误响应 JSON 的终止帧 `event: error` 到达，随后流关闭。重连时，以最后收到的帧 `id` 作为 `cursor`（或使用 `Last-Event-ID` 头）。不可用的游标返回 `invalid_parameter_error` 且 `param=cursor`：修正它，或从保留的起点重新订阅。如果消息提示游标已过期（其位置已被回收），丢弃已有的部分预览，打开 `cursor=now` 流并等待控制帧，通过 `GET .../events` 补齐数据，然后继续实时流。 ## Files 更新 上传、浏览、下载和删除用户文件。 - 新增 `kimi-api-version` 请求头：传与不传对应两套不同的 API 规格。只有 ID 带 `file_` 前缀的文件才能用于 Hosted Agents。 - 提升文档解析能力：优化表格、公式等复杂文档内容的解析效果。 - 调整图片处理方式：图片不再进行 OCR 文本提取。 - 自动处理同名文件：上传与已有文件同名的文件时，服务端自动为新文件重命名，避免文件名冲突。 - 调整文件删除机制：文件删除后，仍可能残留在活跃会话的工具调用中。 ## ChangeLog servers: - url: https://api.moonshot.cn description: 生产环境 variables: {} security: - BearerAuth: [] tags: - name: 智能体 description: 管理智能体配置及其版本。 - name: 会话 description: 管理会话、线程、资源、消息和事件。 - name: 文件 description: 上传、浏览、下载和删除用户文件。 - name: 产物 description: 查看已交付的产物，下载指定版本。 - name: 技能 description: 管理 Skill 包及不可变版本。 - name: 环境 description: 管理执行环境及其配置。 - name: 凭据库 description: 管理凭据库、凭据和 OAuth 会话。 - name: 插件 description: 列出并查看可用插件。 - name: 记忆库 description: 管理记忆库、文件、版本和梦境策略。 - name: 触发器 description: 创建、管理和运行 Trigger。 paths: /v1/triggers: post: tags: - 触发器 summary: 创建触发器 description: |- 创建一个处于活跃状态的触发器，为智能体启动会话。 - cron 策略接受分钟粒度的五字段表达式和一个 IANA `timezone`。实际触发会加入少量抖动。 - 智能体、环境、凭据库与记忆库引用在创建时校验。一个项目最多持有 200 个未归档的触发器。 - 每次触发向本次运行的会话投递 `initial_events` 和一条平台上下文消息。 operationId: createTrigger parameters: - name: Idempotency-Key in: header required: false description: 可选的幂等键。相同的键与请求体会在 24 小时内重放首个响应；以不同的请求体复用，或在首个请求仍在处理时复用，返回 409。 schema: type: string 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 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:00.000Z' updated_at: '2026-08-01T09:00:00.000Z' '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: 已达速率限制或配额耗尽。 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' components: schemas: CreateTriggerRequest: type: object required: - name - agent_id - environment_id - policy properties: name: type: string minLength: 1 maxLength: 256 description: 人类可读的触发器名称。 agent_id: type: string pattern: ^agent_[0-9a-hjkmnp-tv-z]{26}$ minLength: 1 maxLength: 128 description: 每次运行启动的智能体。 agent_version: type: string maxLength: 128 description: 精确的智能体版本（`"1"`、`"2"`……）。省略时选择触发时刻的最新版本。 environment_id: type: string pattern: ^env_[0-9a-hjkmnp-tv-z]{26}$ minLength: 1 maxLength: 128 description: 承载触发器所启动会话的环境。 resources: type: array items: $ref: '#/components/schemas/SessionResource' maxItems: 16 description: 绑定到触发器所启动会话的资源。 initial_events: type: array items: $ref: '#/components/schemas/UserEventInput' maxItems: 16 description: 每次运行时添加到目标会话的开场事件。 session_mode: $ref: '#/components/schemas/SessionMode' description: 每次触发器运行使用哪个会话。 notification: $ref: '#/components/schemas/TriggerNotification' description: TriggerRun 通知的 webhook 配置。缺省则禁用投递。 policy: $ref: '#/components/schemas/TriggerPolicy' description: 决定触发器何时运行的策略。 description: 创建触发器的请求体。 Trigger: type: object required: - id - name - status - agent_id - session_mode - policy - scope - created_by - created_at - updated_at properties: id: type: string pattern: ^trig_[0-9a-hjkmnp-tv-z]{26}$ description: 触发器 ID。 name: type: string description: 人类可读的触发器名称。 status: $ref: '#/components/schemas/TriggerStatus' description: 当前生命周期状态。 paused_reason: $ref: '#/components/schemas/PausedReason' description: 触发器暂停的原因。处于活跃状态时不存在。 agent_id: type: string pattern: ^agent_[0-9a-hjkmnp-tv-z]{26}$ description: 每次运行启动的智能体。 agent_version: type: string description: 精确的智能体版本（`"1"`、`"2"`……）。缺省时在触发时刻选择最新版本。 environment_id: type: string pattern: ^env_[0-9a-hjkmnp-tv-z]{26}$ description: 承载触发器所启动会话的环境。 resources: type: array items: $ref: '#/components/schemas/SessionResource' description: 绑定到触发器所启动会话的资源。 initial_events: type: array items: $ref: '#/components/schemas/UserEventInput' description: 每次运行时添加到目标会话的开场事件。 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，例如梦境策略版本 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: 保存的规则，按计划或按需启动智能体。 BadRequestErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' description: >- 请求无效——字段校验未通过（`invalid_parameter_error`）、请求本身格式有误（`invalid_request_error`），或资源当前状态拒绝该操作（`failed_precondition_error`）。具体原因见 `message`。 UnauthorizedErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' description: 凭据缺失或被拒绝。 NotFoundErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' description: 资源不存在或对调用方不可见。 ConflictErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' description: 名称或唯一键已被占用，或资源发生了并发变更——重新读取后重试。 TooManyRequestsErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' description: 已达速率限制或配额耗尽。 APIError: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' description: 错误详情。 description: 所有非 2xx 响应共用的标准错误响应 JSON 格式。 SessionResource: type: object oneOf: - $ref: '#/components/schemas/SessionResourceFile' title: 文件 - $ref: '#/components/schemas/SessionResourceVault' title: 凭据库 - $ref: '#/components/schemas/SessionResourceMemoryStore' title: 记忆库 discriminator: propertyName: type mapping: file: $ref: '#/components/schemas/SessionResourceFile' vault: $ref: '#/components/schemas/SessionResourceVault' memory_store: $ref: '#/components/schemas/SessionResourceMemoryStore' description: 绑定到会话的资源（文件、凭据库（Vault）或记忆库）。 UserEventInput: type: object oneOf: - $ref: '#/components/schemas/UserMessageInput' title: 用户消息 - $ref: '#/components/schemas/UserInterruptInput' title: 用户中断 discriminator: propertyName: type mapping: user.message: $ref: '#/components/schemas/UserMessageInput' user.interrupt: $ref: '#/components/schemas/UserInterruptInput' description: 客户端可发送给会话的入站事件。与相应会话事件具有相同的 `type` + `data` 结构，但不含服务器分配的错误响应 JSON 字段。 SessionMode: type: string enum: - new_session - reuse_session description: 每次触发器运行是新建会话还是复用平台管理的会话。 TriggerNotification: type: object required: - url - secret_vault properties: url: type: string maxLength: 1024 description: 接收 TriggerRun 通知的 HTTPS 端点。 secret_vault: $ref: '#/components/schemas/NotificationVaultRef' description: >- 存放签名密钥的凭据库（Vault）：其中名为 `webhook_secret` 的 `environment_variable` 凭据。其值从不出现在 API 读取中。凭据在投递时解析，创建时不校验。 description: >- TriggerRun 通知的 webhook 配置。缺省则禁用投递。 仅计划（cron）运行会投递，手动运行不投递。每次投递都是一次 HTTPS POST，JSON 负载为 `{"type": "event", "id": <投递 id>, "created_at": , "data": {"type": <事件>, "id": , "scope_ref": <项目 scope>}}`，事件为 `trigger_run.started`、`trigger_run.succeeded` 或 `trigger_run.failed` 之一。每次投递携带 `Webhook-Id`、`Webhook-Timestamp` 与 `Webhook-Signature: v1,` 三个头。签名是对 `"..<原始正文>"` 的 HMAC-SHA256 的 base64 编码（standard-webhooks 方案）。投递为至少一次：最多 3 次尝试，按 5s/10s 退避。2xx 视为成功，重试耗尽的投递会被丢弃。 TriggerPolicy: type: object oneOf: - $ref: '#/components/schemas/CronTriggerPolicy' title: cron 调度 discriminator: propertyName: type mapping: cron: $ref: '#/components/schemas/CronTriggerPolicy' description: 决定触发器何时触发的规则。 TriggerStatus: type: string enum: - active - paused - archived description: 触发器的生命周期状态。 PausedReason: type: object required: - type properties: type: $ref: '#/components/schemas/PausedReasonType' description: 暂停来源。 error: $ref: '#/components/schemas/ErrorObject' description: 结构化错误详情。仅当 `type` 为 `error` 时存在。 description: 触发器被暂停的原因。处于活跃状态时缺省。 ResourceScope: type: string enum: - official - org - project - user description: 资源的可见范围。`official` 资源由平台提供，通过本 API 只读。 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 版本共用的机器可读错误详情。 SessionResourceFile: type: object required: - type - file_id properties: type: type: string enum: - file id: type: string pattern: ^sres_[0-9a-hjkmnp-tv-z]{26}$ description: 绑定时分配的会话资源 ID。 file_id: type: string pattern: ^file_[0-9a-hjkmnp-tv-z]{26}$ description: 引用的已上传文件。 mime_type: type: string description: 文件 MIME 类型，读取时从存储的元数据解析。 title: type: string description: 显示标题，读取时从存储的元数据解析。 path: type: string description: 文件在会话工作区内链接的路径，位于 `upload/` 下。 description: 作为资源绑定到会话的文件。 title: 文件 SessionResourceVault: type: object required: - type - vault_id properties: type: type: string enum: - vault id: type: string pattern: ^sres_[0-9a-hjkmnp-tv-z]{26}$ description: 绑定时分配的会话资源 ID。 vault_id: type: string pattern: ^vlt_[0-9a-hjkmnp-tv-z]{26}$ minLength: 1 maxLength: 128 description: 要绑定的凭据库（Vault）。 description: 绑定到会话的凭据库（Vault）。其凭据应用于该会话。 title: 凭据库 SessionResourceMemoryStore: type: object required: - type - memory_store_id - access properties: type: type: string enum: - memory_store id: type: string pattern: ^sres_[0-9a-hjkmnp-tv-z]{26}$ description: 绑定时分配的会话资源 ID。 memory_store_id: type: string pattern: ^mstr_[0-9a-hjkmnp-tv-z]{26}$ minLength: 1 description: 要绑定的记忆库。 access: $ref: '#/components/schemas/MemoryAccess' description: 此会话挂载的访问模式。 instructions: type: string maxLength: 4096 description: 针对此绑定向模型展示的附加指引。 description: 创建时绑定到会话的记忆库。 title: 记忆库 UserMessageInput: type: object required: - type - data properties: type: type: string enum: - user.message data: $ref: '#/components/schemas/UserMessagePayload' description: 发送用户消息。 title: 用户消息 UserInterruptInput: type: object required: - type properties: type: type: string enum: - user.interrupt description: >- 停止会话当前正在运行的轮次：轮次被中断，会话以停止原因 `canceled` 回到 `idle`。它必须是请求中唯一的事件，请求的 `type` 字段对它不适用。对不处于 `running` 的会话发送它会返回 400 `failed_precondition_error`。 title: 用户中断 NotificationVaultRef: type: object required: - vault_id properties: vault_id: type: string pattern: ^vlt_[0-9a-hjkmnp-tv-z]{26}$ minLength: 1 maxLength: 128 description: 存放签名密钥的凭据库（Vault），密钥位于凭据键 `webhook_secret` 下。 description: 存放 webhook HMAC 签名密钥的凭据库（Vault）。 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 调度 PausedReasonType: type: string enum: - manual - error description: 触发器暂停的原因：显式请求，或在不可恢复的运行错误后自动暂停。 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: >- 已注册的机器可读错误类型，每种客户端恢复策略对应一个。该集合对客户端封闭，可穷尽处理，但响应侧保持开放：客户端必须容忍未来新增的取值（新增取值不属于破坏性变更）。 MemoryAccess: type: string enum: - read_only - read_write description: |- 授予会话对记忆库的权限。 - `read_only`：会话可以读取记忆库。 - `read_write`：会话还可以写入记忆库。每次写入都记录为一个记忆版本。 UserMessagePayload: type: object properties: content: type: array items: $ref: '#/components/schemas/ContentBlock' description: 用户消息的有序内容部分。内容缺省或为空时，将以平台默认提示词（`Continue.`）唤醒智能体。 description: 事件 `user.message` 的负载。 ContentBlock: type: object oneOf: - $ref: '#/components/schemas/TextContentBlock' title: 文本 - $ref: '#/components/schemas/ThinkingContentBlock' title: 推理 - $ref: '#/components/schemas/ToolUseContentBlock' title: 工具调用 - $ref: '#/components/schemas/ToolResultContentBlock' title: 工具调用结果 - $ref: '#/components/schemas/FileToolResultContent' title: 文件 discriminator: propertyName: type mapping: text: $ref: '#/components/schemas/TextContentBlock' thinking: $ref: '#/components/schemas/ThinkingContentBlock' tool_use: $ref: '#/components/schemas/ToolUseContentBlock' tool_result: $ref: '#/components/schemas/ToolResultContentBlock' file: $ref: '#/components/schemas/FileToolResultContent' description: 一个消息内容块，负载与 `type` 值并排。 TextContentBlock: type: object required: - type - text properties: type: type: string enum: - text text: type: string description: 文本内容。 description: 纯文本块。 title: 文本 ThinkingContentBlock: type: object required: - type - thinking properties: type: type: string enum: - thinking thinking: type: string description: 推理内容。 description: 模型推理块。 title: 推理 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: 工具调用 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: 工具调用结果 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 pattern: ^file_[0-9a-hjkmnp-tv-z]{26}$ description: 平台文件标识符。 description: 文件引用结果内容。 title: 文件 StructuredToolResultContent: type: object oneOf: - $ref: '#/components/schemas/TextContentBlock' title: 文本 - $ref: '#/components/schemas/FileToolResultContent' title: 文件 - $ref: '#/components/schemas/ImageToolResultContent' title: 图片 - $ref: '#/components/schemas/ArtifactToolResultContent' title: 产物 discriminator: propertyName: type mapping: text: $ref: '#/components/schemas/TextContentBlock' file: $ref: '#/components/schemas/FileToolResultContent' image: $ref: '#/components/schemas/ImageToolResultContent' artifact: $ref: '#/components/schemas/ArtifactToolResultContent' description: 工具结果中的一个用户向渲染部分：Display 优先投影词汇，额外携带模型看不到的文件/产物卡片。 ToolResultContent: type: object oneOf: - $ref: '#/components/schemas/TextContentBlock' title: 文本 - $ref: '#/components/schemas/ImageToolResultContent' title: 图片 - $ref: '#/components/schemas/VideoToolResultContent' title: 视频 discriminator: propertyName: type mapping: text: $ref: '#/components/schemas/TextContentBlock' image: $ref: '#/components/schemas/ImageToolResultContent' video: $ref: '#/components/schemas/VideoToolResultContent' description: >- 工具结果中的一个模型向内容部分：模型实际可消费的词汇（文本与媒体部分）；与用户向的 `StructuredToolResultContent` 不同，后者额外携带模型看不到的文件/产物卡片。 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: 图片 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: 产物 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: 视频 securitySchemes: BearerAuth: type: http scheme: Bearer ````