快速开始

准备工作

注册 Kimi 开放平台账号。
使用 kha CLI 或 cURL 时，在组织管理 - API 管理创建 API Key。
使用控制台时无需 API Key，登录账号即可。

export KIMI_API_KEY="你的_KIMI_API_KEY"

核心概念

概念	说明
智能体（Agent）	模型、system prompt、工具、MCP 服务器、技能与插件
技能（Skill）	智能体能力的定义，可按需挂载到智能体配置中，扩展其领域知识或优化其工作流，除官方技能外也支持自定义
插件（Plugin）	可复用的能力组合，包含 MCP 服务和技能；支持平台官方插件与自定义插件
会话（Session）	执行环境中的一次智能体运行实例，执行具体任务并产生输出
环境（Environment）	会话运行的云沙箱配置：预装依赖、网络访问策略、初始化脚本
凭据库（Vault）	集中保存第三方服务凭据，创建会话时绑定使用

这些概念在控制台中都有对应的管理页面，详见使用控制台。

选择使用方式

推荐使用 kha CLI 跑通第一个任务。安装并完成认证后，你可以在 Kimi Code、Claude Code、Codex 等 AI 编程助手中，用自然语言创建和配置智能体、提交和继续任务、查看执行状态并获取产物，无需先手写 API 请求。以 macOS 或 Linux 为例，安装 kha CLI 并登录：

curl -fsSL https://ha-static.moonshot.cn/kha/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
kha login

运行 login 后，在出现的无回显提示中粘贴 API Key（在 Kimi 开放平台创建），按回车即完成。多账号配置，以及在 AI 编程助手中配套使用的 kha 技能包，见 kha CLI。

方式	适合场景	入口
CLI（推荐）	在 AI 编程助手中用自然语言完成第一个任务，并继续管理智能体和会话	使用 CLI
控制台	不写代码，在网页上配置资源、观察运行并检查产物	使用控制台
API	将托管智能体集成到自己的系统，或直接控制 API 请求	查看本页下方的 cURL 与 kha CLI 示例

运行第一个任务

以下用同一个 PPT 任务演示两种实现方式：cURL 调用 REST API，或使用 kha CLI。任选一种即可，不需要同时执行。先选择智能体并准备执行环境，再创建会话、发送消息，最后下载产物。

查看并选择智能体

列出当前可用的智能体：

curl -sS "https://api.moonshot.cn/v1/agents" \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta"

kha agents list

响应包含每个智能体的完整定义，内容较长。如果已安装 jq，可以只列出名称和 id，让输出更清爽：

curl -sS "https://api.moonshot.cn/v1/agents" \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta" \
  | jq -r '.items[] | "name: \(.name)\tid: \(.id)"'

kha agents list -o json | jq -r '.items[] | "name: \(.name)\tid: \(.id)"'

列表中包含平台官方智能体 PPT 助手，它已配置金融插件和 PPT 技能。保存它的 id：

export AGENT_ID="agent_..."

创建执行环境

创建一个用于制作 PPT 的执行环境。config 为必填字段，{"type": "cloud"} 表示创建一个云端执行环境，其余配置项全部使用默认值：

curl -sS -X POST "https://api.moonshot.cn/v1/environments" \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "name": "PPT 制作环境",
  "description": "用于生成和保存 PPT 文件",
  "config": {
    "type": "cloud"
  }
}
JSON

kha environments create --name "PPT 制作环境" --description "用于生成和保存 PPT 文件"

从响应中保存环境 ID（id 字段）：

export ENVIRONMENT_ID="env_..."

执行环境的云沙箱镜像在创建后需要一点时间异步构建，通常很快就能就绪。如果接下来创建会话时因环境尚未就绪而报错，说明镜像还没准备好，稍等片刻后重试即可。

创建会话

关联前面保存的智能体和执行环境，创建会话：

curl -sS -X POST "https://api.moonshot.cn/v1/sessions" \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta" \
  -H "Content-Type: application/json" \
  -d @- <<JSON
{
  "agent_id": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "title": "生成金融市场分析 PPT"
}
JSON

kha sessions create --agent "$AGENT_ID" --environment "$ENVIRONMENT_ID" --title "生成金融市场分析 PPT"

从响应中保存会话 ID（id 字段）：

export SESSION_ID="sesn_..."

订阅事件流

为了实时接收智能体的输出，在发送消息之前，先在另一个终端中订阅该会话的 SSE 事件流：

curl -sS -N "https://api.moonshot.cn/v1/sessions/$SESSION_ID/events/stream" \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta" \
  -H "Accept: text/event-stream"

kha sessions attach "$SESSION_ID"

流中的每个事件帧包含 id、event 和 data 三行：

id：恢复游标（不是事件 ID）。断线重连时把它作为 cursor 查询参数或 Last-Event-ID 请求头回传，即可从断点之后继续接收。
event：事件类型，与事件 JSON 中的 type 字段一致。
data：单行完整的事件 JSON，包含事件 ID（id 字段，sevt_ 前缀）、processed_at、type 和 data 负载。

发送消息后，你会在事件流中看到类似如下的事件帧：

id: 101
event: session.status
data: {"id":"sevt_01h455vb4pex5vsknk084sn02q","processed_at":"2026-09-01T08:00:01Z","type":"session.status","data":{"status":"running"}}

id: 102
event: agent.thinking
data: {"id":"sevt_01h455vb4pex5vsknk084sn02r","processed_at":"2026-09-01T08:00:03Z","type":"agent.thinking","data":{"content":[{"type":"thinking","thinking":"我需要先搜索近两天的金融行业行情数据……"}]}}

id: 103
event: agent.tool_use
data: {"id":"sevt_01h455vb4pex5vsknk084sn02s","processed_at":"2026-09-01T08:00:05Z","type":"agent.tool_use","data":{"tool_use":{"id":"call_1","name":"web_search","input":{"query":"近两天 金融行业 股票 行情"}},"evaluated_permission":"always_allow"}}

id: 104
event: agent.message
data: {"id":"sevt_01h455vb4pex5vsknk084sn02t","processed_at":"2026-09-01T08:00:20Z","type":"agent.message","data":{"content":[{"type":"text","text":"PPT 已生成，保存在 output/ 目录下。"}]}}

以上事件帧仅为示意，展示事件流的大致形态。完整事件类型说明见事件流。

发送消息

回到原来的终端，向会话发送消息，下达本次任务：

curl -sS -X POST "https://api.moonshot.cn/v1/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "events": [
    {
      "type": "user.message",
      "data": {
        "content": [
          {
            "type": "text",
            "text": "你是一个金融行业股票研究员，请汇总近两天的金融行业股票情况，生成一个用于晨会报告的 PPT。"
          }
        ]
      }
    }
  ]
}
JSON

kha sessions send "$SESSION_ID" "你是一个金融行业股票研究员，请汇总近两天的金融行业股票情况，生成一个用于晨会报告的 PPT。"

发送后，订阅事件流的终端会持续收到智能体的执行事件，说明智能体已经开始工作了。

等待执行完成并下载产物

当事件流中出现 session.status 事件、且事件 data 中的 status 为 "idle" 时，本轮执行完成。

事件流支持断线续读：连接断开后重新订阅时，在请求头中携带 Last-Event-ID（值为断开前收到的最后一帧的 id），即可从断点之后继续接收事件，不会漏掉中间的输出。断线重连与错误码处理详见事件流和常见问题。

智能体生成的 PPT 会通过内置的 save_artifact 工具登记为 产物（Artifact）。列出该会话的产物，找到 .pptx 文件并保存它的 id：

curl -sS "https://api.moonshot.cn/v1/artifacts?session_id=$SESSION_ID" \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta"

kha artifacts list --session "$SESSION_ID"

下载该产物：

export ARTIFACT_ID="arti_..."
curl -sS -o output.pptx "https://api.moonshot.cn/v1/artifacts/$ARTIFACT_ID/content" \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta"

export ARTIFACT_ID="arti_..."
kha artifacts download "$ARTIFACT_ID" --out output.pptx

下载完成后，在本地打开 output.pptx 查看生成的 PPT。

（可选）查看会话中的全部文件

产物只包含智能体明确交付的文件。如果需要中间文件，或产物列表为空，可以直接浏览会话文件系统。接口不会递归列出子目录，每次只返回一层的文件和目录。进入子目录时，用 prefix 指定相对于会话文件系统根目录的路径，例如 output 表示根目录下的 output/ 目录：

curl -sS "https://api.moonshot.cn/v1/sessions/$SESSION_ID/filesystem" \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta"
curl -sS "https://api.moonshot.cn/v1/sessions/$SESSION_ID/filesystem?prefix=output" \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta"

kha sessions fs list "$SESSION_ID"
kha sessions fs list "$SESSION_ID" --prefix output

用文件条目的 path 字段替换 <PATH>，下载该文件：

curl -sS -o <本地文件名> "https://api.moonshot.cn/v1/sessions/$SESSION_ID/filesystem/raw?path=<PATH>" \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta"

kha sessions fs download "$SESSION_ID" "<PATH>" --out <本地文件名>

注意事项

托管智能体是有状态的服务：会话历史、沙箱状态与产出文件持久化在服务端。你可以通过 API 删除已归档的会话（归档后状态为 terminated，需先调用归档接口），以及单独删除上传的文件。
托管智能体产品定价见托管智能体定价，常见错误与处理方式见常见问题。

下一步

使用 kha CLI 开始第一个任务

在 AI 编程助手中用自然语言创建和配置智能体、提交和继续任务，并获取产物。

使用控制台完成配置

在网页上配置资源、观察运行并检查产物。

创建并管理智能体

配置模型、system prompt、工具、MCP 服务器、技能与插件。

创建并管理会话

创建会话、绑定资源并发送首条消息。

查看并处理实时事件

订阅事件、断线续读与错误处理。

开始使用

定义智能体

配置执行环境

运行会话

上下文与记忆

高级编排

最佳实践

常见问题

准备工作

核心概念

选择使用方式

运行第一个任务

注意事项

下一步

使用 kha CLI 开始第一个任务

使用控制台完成配置

创建并管理智能体

创建并管理会话

查看并处理实时事件

​准备工作

​核心概念

​选择使用方式

​运行第一个任务

​注意事项

​下一步

使用 kha CLI 开始第一个任务

使用控制台完成配置

创建并管理智能体

创建并管理会话

查看并处理实时事件

准备工作

核心概念

选择使用方式

运行第一个任务

注意事项

下一步