> ## 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. # 获取会话 > 返回单个会话，包含其资源绑定和协调者的智能体快照（含系统提示词）。 ## OpenAPI ````yaml /openapi-hosted-agents.yaml get /v1/sessions/{id} 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/sessions/{id}: get: tags: - 会话 summary: 获取会话 description: 返回单个会话，包含其资源绑定和协调者的智能体快照（含系统提示词）。 operationId: getSession parameters: - name: id in: path required: true schema: type: string pattern: ^sesn_[0-9a-hjkmnp-tv-z]{26}$ description: 会话 ID。 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:00.000Z' updated_at: '2026-01-01T00:00:00.000Z' '401': description: 凭据缺失或被拒绝。 content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: 资源不存在或对调用方不可见。 content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '429': description: 已达速率限制或配额耗尽。 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponse' default: description: 意外的错误响应。 content: application/json: schema: $ref: '#/components/schemas/APIError' components: schemas: Session: type: object required: - id - agent_id - environment_id - status - created_at - updated_at properties: id: type: string pattern: ^sesn_[0-9a-hjkmnp-tv-z]{26}$ description: 会话 ID。 agent_id: type: string pattern: ^agent_[0-9a-hjkmnp-tv-z]{26}$ description: 此会话运行的智能体。 environment_id: type: string pattern: ^env_[0-9a-hjkmnp-tv-z]{26}$ description: 托管此会话的环境。 status: $ref: '#/components/schemas/SessionState' 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: 带版本智能体配置的一个运行实例。 UnauthorizedErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' description: 凭据缺失或被拒绝。 NotFoundErrorResponse: 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 格式。 SessionState: type: string enum: - idle - running - terminated description: |- 会话或线程的当前生命周期状态。 - `idle`：未在执行。接受新输入。 - `running`：正在执行一个轮次。 - `terminated`：归档后的最终状态。 StringMetadata: type: object description: 用户定义的字符串值元数据（最多 16 个条目；键最长 64 个字符，值最长 512 个字符）。 maxProperties: 16 propertyNames: type: string maxLength: 64 additionalProperties: type: string maxLength: 512 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: 替换此会话的技能引用。 description: |- 会话级智能体配置覆盖（整体替换，绝不合并）。每个集合字段为三态： - 缺省：继承冻结智能体版本的值（创建时），或保持覆盖不变（更新时）。 - 显式空数组：清空此会话的该集合（创建时），或清除覆盖并回退到冻结值（更新时）。 - 非空数组：整体替换该集合。 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）或记忆库）。 SessionAgent: type: object required: - id - version - name properties: id: type: string pattern: ^agent_[0-9a-hjkmnp-tv-z]{26}$ 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: 会话使用的智能体版本快照。 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 版本共用的机器可读错误详情。 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。 description: 在智能体上声明的 MCP 服务器连接。 SkillRef: type: object required: - skill_id properties: skill_id: type: string minLength: 1 description: 技能标识符。内置技能与自定义技能共用一个 ID 命名空间，二者通过 ID 前缀区分。 version: type: string description: 技能版本（`"1"`、`"2"`……）。省略或为 `"latest"` 时，在写入时解析为具体版本。 description: 对附加到智能体的某个技能版本的引用。 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: 记忆库 ModelRef: anyOf: - type: string - $ref: '#/components/schemas/ModelConfig' description: 模型选择：裸模型 ID 字符串或结构化配置。 Tool: type: object oneOf: - $ref: '#/components/schemas/AgentToolset' title: Agent 工具集 - $ref: '#/components/schemas/McpToolset' title: MCP 工具集 discriminator: propertyName: type mapping: agent_toolset: $ref: '#/components/schemas/AgentToolset' mcp_toolset: $ref: '#/components/schemas/McpToolset' description: 智能体上的工具声明：内置工具集或 MCP 工具集。 SessionMultiagent: type: object required: - agents properties: agents: type: array items: $ref: '#/components/schemas/SessionThreadAgent' description: 协调者可用的智能体版本完整快照。 description: Session.agent 中已解析的协调者名册。 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: >- 已注册的机器可读错误类型，每种客户端恢复策略对应一个。该集合对客户端封闭，可穷尽处理，但响应侧保持开放：客户端必须容忍未来新增的取值（新增取值不属于破坏性变更）。 McpServerType: type: string enum: - url description: MCP 服务器连接的类型。 MemoryAccess: type: string enum: - read_only - read_write description: |- 授予会话对记忆库的权限。 - `read_only`：会话可以读取记忆库。 - `read_write`：会话还可以写入记忆库。每次写入都记录为一个记忆版本。 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: 需要按模型细调参数时使用的结构化模型选择。 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: 内置智能体工具集声明。 title: Agent 工具集 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 工具集 SessionThreadAgent: type: object required: - id - version - name properties: id: type: string pattern: ^agent_[0-9a-hjkmnp-tv-z]{26}$ 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: 一个会话线程使用的固定智能体版本。 ReasoningEffort: type: string enum: - low - medium - high description: 推理强度提示。所选模型可能会忽略它。 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` 填写这些名称。 ToolsetDefaultConfig: type: object properties: enabled: type: boolean description: 工具集中的工具是否默认启用。 permission_policy: $ref: '#/components/schemas/PermissionPolicy' description: 默认权限策略。 load_mode: $ref: '#/components/schemas/ToolLoadMode' description: 默认的工具 schema 加载模式。 description: 应用于工具集中每个工具的默认配置。 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: 工具集内针对单个工具的覆盖设置。 PermissionPolicy: type: string enum: - always_allow description: >- 应用于工具或工具集的权限策略。`always_allow` 表示模型调用时直接运行该工具。用 `enabled: false` 禁用工具。被禁用的工具不对模型暴露。 ToolLoadMode: type: string enum: - eager - on_demand description: >- 控制工具 schema 的加载时机：`eager` 随智能体配置加载。`on_demand` 在首次需要该工具时加载，不支持按需加载时回退为 eager 加载。 securitySchemes: BearerAuth: type: http scheme: Bearer ````