概覽 - AI Coding Assistant Lingma

Qoder Cloud Agents CN 是全託管的 AI Agent 運行平台。你無需自建 agent loop、管理工具執行沙箱或處理長串連——只需通過 API 定義 Agent、啟動 Session，即可在雲端運行複雜任務並即時接收結果。

核心概念

概念	說明	類比
Agent	可複用的配置模板，定義模型、系統提示詞、工具集	"員工的崗位說明書"
Environment	Session 啟動並執行容器環境，包含網路、依賴包配置	"辦公桌和工具箱"
Session	一次具體的對話/任務執行執行個體	"一次具體的工作會話"
Event	Session 中產生的即時事件流	"工作進度即時播報"

工作流程

定義 Agent — 指定模型、system prompt、可用工具。
配置 Environment — 選擇容器類型、網路原則、預裝依賴。新帳號需先 POST /environments 建立環境（無預置預設環境）。
啟動 Session — 綁定 Agent + Environment，建立運行執行個體。
發訊息 + 收事件 — 向 Session 發送 user.message，然後通過 SSE 流（或輪詢）即時接收 Agent 思考、訊息、狀態變更等事件。

快速驗證連通性

# 驗證 PAT 是否有效，列出所有 Agent
curl -s https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT"

成功響應格式：

{
  "data": [ ],
  "first_id": null,
  "last_id": null,
  "has_more": false
}

適用情境

長時間非同步任務 — 代碼審查、大規模重構、自動化測試產生
API 整合 — 在後端服務中嵌入 Agent 能力，無需維護運行時
批量處理 — 並行啟動多個 Session 處理批量請求
定時任務 — 結合調度系統，周期性運行 Agent 完成巡檢/報告

認證方式

所有 API 請求需要攜帶以下 Header：

Header	值	說明
`Authorization`	`Bearer <PAT>`	個人存取權杖

PAT 在 Qoder 控制台「設定 → 個人存取權杖」中建立，請妥善保管，不要提交到代碼倉庫。

分頁機制

列表介面統一使用遊標分頁，響應結構：

{
  "data": [...],
  "first_id": "agent_019e451902fe7a2ca42c2dfc62d9320e",
  "last_id": "agent_019e45369b3379e18bfaf59b3aad2fc9",
  "has_more": true
}

使用 after_id / before_id 查詢參數翻頁。

常見問題

Q: Cloud Agents CN 和 Qoder CLI 可以同時使用嗎？

A: 完全可以。CLI 適合本地互動開發，Cloud Agents CN 適合自動化和整合情境，兩者互補。

Q: 一個 Agent 可以同時運行多少個 Session？

A: 沒有硬性限制，同一個 Agent 配置可以同時關聯多個活躍 Session。

Q: 資料安全如何保障？

A: 每個 Session 運行在隔離的容器沙箱中，Session 之間無法互相訪問。環境銷毀後資料清除。

下一步

快速開始 — 5 步跑通第一個 Cloud Agent
定義 Agent — 深入瞭解 Agent 配置
雲端環境— 配置運行環境
啟動 Session — 管理會話生命週期