重點摘要
Kimi Hosted Agents 透過持久會話、工具執行與雲端沙盒,運行多步驟的 AI 任務。本指南將帶你從 Kimi API 金鑰出發,使用 Bash、curl 與 jq,產出可下載的三頁投影片簡報。先以一段自給自足的提示完成一次任務,接著加入上傳文件、連接商務工具,並處理實際上線應用中重要的失敗情況。
關鍵要點
- Kimi Hosted Agents 連結代理定義、執行環境與會話。請在整個流程中妥善保存它們的 ID。
- 從小而可驗證的結果開始。第一個範例會產生含虛構數據且附帶可自行檢查計算的簡報。
- 使用事件串流追蹤執行情況,之後檢視交付的檔案。僅有成功的 HTTP 回應並不足以證明任務成功。
- 在可運作的範例上擴充檔案輸入、自訂工具或 MCP 服務。每種整合都各自有其執行與憑證需求。
- 為推理、沙盒執行時間與外掛使用一併預算,包括為產出可接受結果所需的重跑次數。
什麼是 Kimi Hosted Agents?
Moonshot AI 於 2026 年 11 月 5 日 宣布 Kimi Hosted Agents,將其定位為面向企業與開發者的長時執行代理服務。
該產品採用 Harness as a Service 的方式。Harness 是圍繞模型的軟體,用於管理工作進度:維持狀態、調用工具、管理執行,並從中斷中恢復。
以每週研究流程為例。生成文字只是其中一步。應用程式還可能需要擷取來源、處理檔案、建立圖表、儲存簡報,並保留足夠的狀態以便在連線中斷後繼續。
Hosted Agents 提供這一運營層。你的團隊仍需定義業務任務、選擇整合,並界定何者為可接受結果。
Kimi 的官方架構展示了由應用程式、平台服務與執行核心組成的託管執行時。
首次整合的核心能力
- 持久會話將任務的輸入、執行事件與輸出關聯在一起。
- 雲端沙盒提供處理檔案與產出交付物所需的工具。
- Skills 與外掛封裝可重用能力;自訂工具與 MCP 服務可連接你的自有系統。
你的第一個檢查點是能夠開啟並檢視的簡報。當你新增依賴或將既有流程移入沙盒時,詳細的執行時規格會變得重要;沙盒參考記載了可用的環境。
呼叫 Kimi Hosted Agents API 前需要準備什麼?
- 可存取 Hosted Agents 的 Kimi 平台帳號與 API 金鑰。
- 在 macOS、Linux 或具 WSL 的 Windows 上安裝 Bash、curl 與 jq。
- 兩個終端機:終端機 A 用於送出請求;終端機 B 用於監看執行事件。
- 一個可開啟產生之 PPTX 的簡報檢視器。
在主控台的 API 管理區建立 Kimi 平台帳號與 API 金鑰。使用一個名為「終端機 A」的 Bash 終端機進行設定與任務指令,並保持開啟以便後續步驟重用變數。請先安裝 curl 與 jq。以下範例使用 beta API 版本 2026-09-01-beta。
command -v curl &&
command -v jq &&
read -rsp "Kimi API key: " KIMI_API_KEY &&
printf '\n' &&
test -n "$KIMI_API_KEY" &&
export KIMI_API_KEY &&
export KIMI_BASE="https://api.moonshot.cn/v1" &&
export KIMI_VERSION="2026-09-01-beta"
如何執行你的第一個 Kimi Hosted Agents 任務
此工作流程遵循 Kimi 的REST API 快速上手。你將使用官方 PPT 助手,將一段虛構的商務簡報轉換成簡報檔。所有輸入資料都包含在請求中,因此首次執行無需上傳檔案或連接私有資料。
請依序執行每個區塊,並在繼續前檢查輸出。以 && 連接的指令在請求或驗證失敗時會停止該區塊。請先解決錯誤再進入下一步;重試既有設定時請維持相同的環境與會話 ID。
步驟 1:選擇官方 PPT 助手
取得可用的代理並檢視它們的名稱與定義。當出現提示時,貼上已配置 PPT 技能的官方 PPT 助手的 ID。最後一條指令會檢查你的選擇是否存在於回傳清單中,並列印其定義。
curl --fail-with-body -sS "$KIMI_BASE/agents" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-o agents.json &&
jq -r '.items[] | [.id, .name] | @tsv' agents.json &&
read -rp "PPT assistant ID: " AGENT_ID &&
jq -e --arg id "$AGENT_ID" \
'.items[] | select(.id == $id)' agents.json &&
export AGENT_ID
最後一條指令應列印所選助手的定義。若該助手在你的專案中不可用,請使用官方 PPT 代理配置準備等效代理再繼續。
步驟 2:建立雲端環境
Environment 是可重用的執行設定,包含已安裝套件、網路存取與啟動指令。重用它可讓後續會話擁有相同設定;每個雲端會話仍會獲得各自的沙盒與工作區。更多設定選項請見環境指南。
環境建立一次即可,並保留其 ID。雲端映像會非同步建置,請等其建置狀態為 ready 後再建立會話。若 API 回報尚未就緒,請等待並以相同的 ENVIRONMENT_ID 重試。建立另一個環境並不會讓第一個建置完成。
curl --fail-with-body -sS "$KIMI_BASE/environments" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-H "Content-Type: application/json" \
-d '{"name":"First presentation environment","config":{"type":"cloud"}}' \
-o environment.json &&
ENVIRONMENT_ID="$(jq -er '.id | strings | select(length > 0)' environment.json)" &&
export ENVIRONMENT_ID &&
printf '環境:%s\n' "$ENVIRONMENT_ID"
步驟 3:建立會話
Session 會在建立時固定 Agent 版本與一個可用的 Environment 版本。下方請求提供它們的 ID;平台會選擇並凍結版本。你也可以設定 agent_version 以選擇精確的 Agent 版本。後續更新 Agent 或 Environment 並不會更新既有會話,而且會話無法切換其 environment_id。如需使用調整後的設定,請建立新會話。相關規則詳見會話建立。
請保留回傳的會話 ID,用於事件串流與任務請求。新會話起始於 idle;送出 user.message 後會開始任務。
test -n "$AGENT_ID" &&
test -n "$ENVIRONMENT_ID" &&
jq -n --arg agent "$AGENT_ID" --arg env "$ENVIRONMENT_ID" \
'{agent_id:$agent,environment_id:$env,title:"First product update presentation"}' \
> session-request.json &&
curl --fail-with-body -sS "$KIMI_BASE/sessions" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-H "Content-Type: application/json" \
--data-binary @session-request.json \
-o session.json &&
SESSION_ID="$(jq -er '.id | strings | select(length > 0)' session.json)" &&
export SESSION_ID &&
printf '會話:%s\n' "$SESSION_ID"
步驟 4:在第二個終端機觀察執行
開啟終端機 B。輸入相同的 API 金鑰,然後貼上在終端機 A 列印的會話 ID。伺服器傳送事件(SSE)串流會在終端機 A 提交任務的同時展示執行進度。請保持此終端機連線,直到你檢視結果為止。
read -rsp "Kimi API key: " KIMI_API_KEY &&
printf '\n' &&
test -n "$KIMI_API_KEY" &&
read -rp "Session ID from Terminal A: " SESSION_ID &&
test -n "$SESSION_ID" &&
curl --fail-with-body -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"
步驟 5:送出自給自足的任務
回到終端機 A,送出一個 user.message 事件。此範例使用虛構數字並要求產出特定交付物。代理應使用提供的事實,而非搜尋商務資料。
cat > task.json <<'JSON' &&
{
"events": [{
"type": "user.message",
"data": {"content": [{
"type": "text",
"text": "為名為 Northstar 的虛構產品建立一個三頁的 PPTX。僅使用以下提供的事實:試點共有 120 位使用者;本週有 90 位為活躍;團隊計畫下週訪談 10 位使用者。投影片 1:試點概覽。投影片 2:本週活躍情況,包含活躍使用者百分比。投影片 3:下一步。請將商務與數據標記為虛構。不要瀏覽網路。儲存簡報並使用 save_artifact 將 PPTX 註冊為可下載的 artifact。"
}]}
}]
}
JSON
curl --fail-with-body -sS "$KIMI_BASE/sessions/$SESSION_ID/events" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-H "Content-Type: application/json" \
--data-binary @task.json
步驟 6:下載並檢視簡報
在終端機 B 監看 session.status 事件。當會話回到 idle 時,檢視其停止原因:end_turn 表示該輪已結束;requires_action 則表示你的用戶端必須提供工具結果或處理確認。也請檢查 session.error 事件。當該輪在沒有未解決錯誤的情況下結束後,列出 artifacts 並選擇生成的 PPTX。
curl --fail-with-body -sS "$KIMI_BASE/artifacts?session_id=$SESSION_ID" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-o artifacts.json &&
jq . artifacts.json &&
read -rp "PPTX artifact ID: " ARTIFACT_ID &&
test -n "$ARTIFACT_ID" &&
curl --fail-with-body -sS "$KIMI_BASE/artifacts/$ARTIFACT_ID/content" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-o northstar.pptx &&
printf '已下載 northstar.pptx\n'
開啟 northstar.pptx。成功的結果應包含三頁投影片、標示數據為虛構,並將每週活躍度計算為 90 ÷ 120 = 75%。在連接真實商務數據之前,這能讓你具體檢查檔案交付與內容正確性。
如何上傳並附加檔案到 Kimi Hosted Agents 會話?
在首份簡報成功後,將一份範例 report.pdf 放至終端機 A 的工作目錄。檔案 API 將上傳檔案與將其附加到會話視為兩個步驟。在首個任務完成後,使用既有會話 ID 執行此區塊。
使用 purpose=file-extract 自 PDF 萃取文字。檔案 API 每個檔案上限 100 MiB,組織預設儲存配額為 10 GiB。已上傳檔案無法就地更新;請上傳修訂後檔案並綁定其新的 ID。當需要釋放空間時,移除未使用的檔案。
在 kimi-api-version: 2026-09-01-beta 下,請檢查上傳回應中的 extract_status。此範例僅在其為 ready 時繼續。若為 error,請檢查 PDF 格式與內容後上傳修正檔。API 也可將失敗的萃取作為原始檔案附加,但不會提供本教學所需的文字萃取。若缺少或出現非預期狀態,也會停止此區塊;請先檢視 upload.json 再繼續。
test -f report.pdf &&
test -n "$SESSION_ID" &&
curl --fail-with-body -sS "$KIMI_BASE/files" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-F "file=@report.pdf" \
-F "purpose=file-extract" \
-o upload.json &&
FILE_ID="$(jq -er '.id | strings | select(length > 0)' upload.json)" &&
{
EXTRACT_STATUS="$(jq -r '.extract_status // "missing"' upload.json)" &&
case "$EXTRACT_STATUS" in
ready) true ;;
error)
printf '%s\n' 'PDF 萃取失敗。請檢查 PDF 並上傳修正後的檔案。' >&2
false ;;
*)
printf '出現非預期的 extract_status:%s。請在繼續前檢視 upload.json。\n' "$EXTRACT_STATUS" >&2
false ;;
esac
} &&
jq -n --arg file "$FILE_ID" \
'{type:"file",file_id:$file}' > resource-request.json &&
curl --fail-with-body -sS "$KIMI_BASE/sessions/$SESSION_ID/resources" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-H "Content-Type: application/json" \
--data-binary @resource-request.json
附加檔案並不會送出新任務。保持終端機 B 連線,並提交一個後續請求,說明文件名稱與期望輸出。
jq -n --arg prompt \
"使用附加的 report.pdf 建立一份新的三頁 PPTX。取代先前的虛構簡報。請摘要該報告、其證據與下一步。不要臆測缺失數字,也不要瀏覽網路。完成後使用 save_artifact 註冊 PPTX。" \
'{events:[{type:"user.message",data:{content:[{type:"text",text:$prompt}]}}]}' \
> followup.json &&
curl --fail-with-body -sS "$KIMI_BASE/sessions/$SESSION_ID/events" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-H "Content-Type: application/json" \
--data-binary @followup.json
當此任務結束後,重複列出 artifacts 的步驟並選取新的 PPTX。將其聲明與 PDF 比對,特別是數字、日期與建議行動。
如何在 Kimi Hosted Agents 中連接工具?
由你的應用程式執行的自訂工具
對於例如查詢專案交付狀態等商務動作,請使用由你的應用程式實作的自訂工具。宣告該工具可讓代理可用;實際操作仍由你的程式執行。
- 在代理的
tools陣列中宣告一個custom條目,包含名稱、描述,以及物件結構的input_schema。 - 在事件串流中處理
agent.custom_tool_use,並在執行你的函式前驗證提供的參數。 - 向會話張貼
user.custom_tool_result事件,並使用呼叫事件的 JSONid作為data.event_id。
從唯讀查詢開始。當整合可以修改商務紀錄時,請在應用程式中保留授權與重複動作防護。
MCP 服務與更大型工作流程
對於遠端的 MCP 服務,在 mcp_servers 中宣告其連線。將存取憑證儲存在 vault 並在建立會話時綁定。平台會探索並呼叫該服務的工具;伺服器定義應包含連線細節而非密鑰本身。
可選的多代理協調
平台支援協調者到子執行緒的委派。協調者可將有界任務分派給子執行緒,並彙整其結果。
其委派設定可接受 1–20 個代理項目。這是設定限制,並不代表 20 個同時工作者或 20 倍的速度提升。子執行緒無法再建立下一層子執行緒。
一個實用的設計可拆分為來源收集、量化分析與編輯審閱。對於簡短的摘要任務,通常由單一代理更合適。
如何部署 Kimi Hosted Agents 整合?
將 Kimi API 呼叫置於你的應用程式後端之後。瀏覽器可透過你的端點提交任務與顯示進度,而後端保管 API 金鑰,並將每位使用者繫結到其可存取的會話。將會話 ID 與商務請求一併儲存,以便重新載入頁面時能重新開啟相同任務。
託管與自託管的執行模式
對本指南的 PPT 工作流程,請使用雲端環境:它支援 save_artifact 與會話檔案工作流程。當沙盒執行必須在你的組織管理的主機上運行時,選擇自託管環境。Kimi 仍會負責模型推理、協作與會話管理;工具的輸入與結果會通過其平台。這是一種混合式執行模型。
- 自託管環境需要企業實名驗證。你負責操作 Worker 主機、安裝其相依項,並管理隔離與憑證。Worker 需要對平台的 HTTPS 對外連線。
- 自託管模式目前不支援
save_artifact、IPython 與影像搜尋工具。上傳的檔案、skills 與記憶不會掛載到 Worker 上,且其輸出檔案不會出現在會話檔案清單中。在將本教學移轉到該模式前,請先規劃好如何提供輸入與取回輸出。
首次整合請先在雲端進行。當對執行主機的掌控需求足以抵銷額外設定與檔案交付方式變更時,再考慮自託管。
運行時由誰負責營運
當你希望由平台管理會話執行時,請使用 Hosted Agents。若你的團隊需要自行打造與營運代理循環,CometAPI 提供統一的模型 API 存取,以支援自訂堆疊。本指南中的 Hosted Agents 範例使用 Kimi 自家的端點與憑證。
Kimi Hosted Agents 定價與成本優化
Kimi Hosted Agents 會就模型 tokens、雲端沙盒執行時間與付費外掛呼叫計費。下表展示這些費用如何影響簡報工作流程。價格以人民幣(CNY)計,於 2026 年 11 月 10 日查核自Hosted Agents 定價與模型推理定價。一百萬 tokens 等於 1 MTok。
| 成本組成 | 計費單位 | 費率與對你的任務的意涵 |
|---|---|---|
| 模型推理 | 每 1 MTok | 對於 kimi-k3.1-pro:基礎輸入 ¥13、輸出 ¥68、快取命中 ¥1.30、5 分鐘快取寫入 ¥13、1 小時快取寫入 ¥26。將各類使用量分別套用至所有模型呼叫。 |
| 雲端沙盒 | 執行時間;按秒計費 | 1 CPU 核、1 GB 記憶體的沙盒為 ¥0.072/小時。10 分鐘約 ¥0.012。 |
| 外掛 | 每次可計費呼叫 | 例:網頁搜尋 ¥0.03/次;影像搜尋 ¥0.045/次。其他外掛各有其費率。將各外掛的呼叫次數乘以其標示價格。 |
| 任務總成本 | 每個完成的任務 | 將模型、沙盒與外掛費用相加。下方的 PPT 範例在無付費外掛呼叫時合計 ¥0.544;若在同樣的模型用量與執行時間下包含 3 次網頁搜尋與 2 次影像搜尋,則為 ¥0.724。 |
上述模型費率以 kimi-k3.1-pro 作為預算估算範例,並非宣稱每個官方 PPT 代理都使用此模型。請在套用費率前檢查已選代理的模型設定。其他模型與高速變體的費率不同。
如何計算輸入與輸出 tokens
代理在產生一份簡報時,可能多次呼叫模型。請加總所有呼叫的可計費使用量,包含後續對話輪與修訂。輸入可能包括提示、PDF 萃取文字、工具結果與對話脈絡;輸出使用量並不限於投影片上可見的文字。
針對 K3 快取,請將未快取的輸入、快取寫入與快取命中分開計算。這些是不同的輸入類別:不要對同一批 tokens 同時以基礎輸入費率計費並再加上快取費用。請套用 5 分鐘或 1 小時適用的寫入費率。快取計費指南解釋了如何將這些類別與回報的使用量對齊。
實算範例:三頁投影片簡報
假設你的代理使用 kimi-k3.1-pro,完成一份三頁 PPT 的整個流程共消耗 20,000 個輸入 tokens、4,000 個可計費輸出 tokens,以及 10 分鐘的可計費雲端執行時間。假設無快取命中、無 1 小時快取寫入,且無付費外掛呼叫。所有輸入要嘛未快取、要嘛寫入預設的 5 分鐘快取,兩者都以 ¥13/MTok 計價。這些是用於規劃的估算量,並非 Northstar 教學的實測值。
| 費項 | 計算 | 估算成本 |
|---|---|---|
| 模型輸入 | 20,000 ÷ 1,000,000 × ¥13 | ¥0.260 |
| 模型輸出 | 4,000 ÷ 1,000,000 × ¥68 | ¥0.272 |
| 雲端沙盒 | 10 ÷ 60 × ¥0.072 | ¥0.012 |
| 付費外掛 | 0 次可計費呼叫 | ¥0.000 |
| 總計 | ¥0.260 + ¥0.272 + ¥0.012 | ¥0.544(約 ¥0.54) |
供給事實的教學要求代理不要瀏覽網路。若之後擴充為研究型簡報,包含 3 次網頁搜尋與 2 次影像搜尋,外掛費用為 3 × ¥0.03 + 2 × ¥0.045 = ¥0.180。在其他用量不變的前提下,總計為 ¥0.544 + ¥0.180 = ¥0.724。研究也可能增加模型 tokens 與執行時間,請以實測用量作為最終計費依據。
使用多個代理時會有什麼變化?
委派可能增加模型呼叫、重複脈絡、工具呼叫與修訂工作。Kimi 的多代理工作流程會將協調者與子執行緒置於同一個會話中。子執行緒數量本身不是沙盒費用的倍數因子。請彙總各執行緒的模型與外掛使用量,並使用會話實際可計費的執行時間。較長的執行或額外獨立的雲端會話都可能增加沙盒成本。常見問答說明了當所有執行緒完成且會話變為 idle 時,沙盒時間就會停止累計。
降低每份可用簡報的成本
從單一代理與小型交付物開始。提供相關來源段落、限制投影片張數,並僅在任務需要時啟用付費搜尋。遇到事件串流中斷時,請重新連線而非重送相同任務。對重複性工作流程,檢視快取命中並保持可重用脈絡穩定。比較所有嘗試的總成本與實際可接受的簡報數量;便宜的初稿若需多次重跑,整體可能更貴。
常見 API 錯誤疑難排解
- 驗證失敗:確認送出請求的終端機已設定 API 金鑰,且屬於預期帳號。在重試前檢視 HTTP 錯誤內容。
- curl 拒絕某個選項或缺少 jq:請檢查已安裝的工具。本範例需要支援
--fail-with-body的 curl 版本,且相同 Bash 環境中有可用的 jq 執行檔。 - jq 無法擷取 ID:請開啟儲存的回應 JSON。它可能包含 API 錯誤而非成功的資源物件。請先修正請求,再將空的 ID 傳遞給下一個端點。
- 自訂工具工作流程無法繼續:請檢視待處理工具事件。
requires_action的停止原因表示用戶端需要回傳工具結果或處理確認,受影響的執行緒才會繼續。 - 下載的投影片包含不被支持的主張:請將其與提供的簡報或報告比對。針對具體出入修訂任務,並在使用前檢視下一版交付物。
在診斷失敗時,請記錄端點、HTTP 狀態、會話 ID 與相關事件。請勿將 API 金鑰寫入診斷日誌。
結語
先完成一條完整的 Kimi Hosted Agents 工作流程:選擇代理、準備環境、建立會話、提交任務並檢視交付檔。當這條路順暢後,再加入來源文件與你的應用程式所需的商務工具。保持進度可見,並以輸出的實用性評估每次執行,而不僅僅是請求是否成功。
常見問題(FAQ)
斷線後需要重新送出 Kimi Hosted Agents 任務嗎?
不需要。事件串流中斷不必重送任務。請使用最後一個 SSE frame 的 id: 值,透過 Last-Event-ID header 重新連線以恢復閱讀。此值是串流游標,而非事件物件的 JSON ID。重新連線可避免不小心重送相同工作。
如果 Kimi Hosted Agents 的輸出沒有出現在 artifacts 中怎麼辦?
沙盒中的檔案可能存在但未註冊為 artifact。請檢查代理是否完成簡報並呼叫了 save_artifact。若缺少註冊,使用會話檔案 API 檢視輸出目錄:GET /v1/sessions/{session_id}/filesystem?prefix=output。該清單一次僅涵蓋一個目錄;更新 prefix 以檢視子目錄。使用 GET /v1/sessions/{session_id}/filesystem/raw?path=output/northstar.pptx 下載所選檔案,並以回傳清單中的精確路徑取代範例。若路徑包含空白或保留字元,請對查詢值進行 URL 編碼。與教學相同地附上授權與 API 版本標頭。
更新 Kimi Hosted Agents 設定會影響使用中的會話嗎?
不會。會話會使用在建立時固定的 Agent 版本。更新代理會為後續會話建立新版本,而既有會話維持原始設定。若要測試修訂的指示或工具,請建立新會話,並將其輸出與先前執行結果比較。

