Skip to main content
子代理是專門處理專案範圍內任務的 AI 代理。主代理可以將工作委派給子代理，每個子代理擁有自己的工具與指令。

​
內建子代理

CTOR 包含兩個內建子代理： 內建子代理無法編輯或刪除。

​
檢視子代理的執行狀況

當主代理委派工作時，子代理的工具區塊會在對話中回報進度。執行期間，區塊標題會顯示目前的步驟——工具名稱與其對象，例如 Read File · src/App.tsx。展開區塊即可看到完整的任務提示，以及下方的即時活動紀錄：每一列對應子代理的一次工具呼叫，並標示執行中、完成或失敗。紀錄會保留最近 30 次呼叫。 子代理結束後，標題會將即時狀態換成工具呼叫總次數，活動紀錄則保留在展開的區塊中。

​
Ultra 協作

在實驗性的 Ultra 思考層級下，代理會主動分派工作：它不再依序處理冗長的任務，而是將工作拆分、平行執行多個子代理，最後彙整它們的發現。 以此方式衍生的子代理享有比一般分派更大的空間——它們繼承母對話的模型，可以各自指定思考層級，並能使用專案的 MCP 工具。單次執行超過 30 分鐘會被中止。 子代理執行期間，輸入列會顯示目前有多少個正在執行，以及各自的模型與思考層級。在 Main Chat 中，協作子代理會以獨立會話出現在側邊欄，名稱旁標有 ⤷。

​
並行數上限

Settings → System → Experimental features → Ultra 平行代理數可設定單一 Ultra 對話同時執行的子代理數量上限。預設為 3，範圍是 1–8。超出上限的工作會排入佇列，待有空位時才開始。

​
執行產物

每次 Ultra 子代理執行都會寫入專案中的 .bricks/build/agents/，因此即使母對話中斷，結果仍會保留： 對話中回報的是縮短後的結果並附上這些路徑；完整輸出只存在於磁碟上。在產生的專案中，.bricks/build/ 已被 git 忽略，因此這些產物不會出現在你的工作目錄狀態中。系統不會自動清除此目錄——檔案累積過多時請自行刪除舊的執行紀錄。 若結果無法交回進行中的回合——母對話的回合失敗，或應用程式重新啟動——CTOR 會以完成的報告重新提示母對話，而不會將其捨棄。

​
管理子代理

從側邊欄開啟外掛面板，並切換至子代理分頁。 外掛也可以安裝子代理，它們會與您自己的代理一同顯示在子代理分頁中。

​
範圍

子代理分為兩個範圍：
  • 全域 —適用於所有開啟的專案。儲存於 ~/.bricks-project-desktop/agents/。
  • 專案 —僅適用於特定專案。儲存於專案的 .bricks/agents/ 目錄中。
同名的專案範圍代理會覆蓋全域代理。同名的自訂全域代理會覆蓋內建代理。

​
建立子代理

  1. 開啟子代理分頁
  2. 選擇全域範圍
  3. 點擊新增代理
  4. 在編輯器中編輯代理的 frontmatter 與指令
  5. 點擊儲存

​
代理檔案格式

子代理為帶有 YAML frontmatter 的 markdown 檔案：
Frontmatter 欄位： 未指定 tools 清單（或設為 null）時，代理會獲得所有內建工具（spawn_agent 除外）。若要限制工具，只列出需要的項目： 常用工具： read_file、glob、grep

​
編輯子代理

點擊代理卡片上的編輯按鈕開啟編輯器。修改 frontmatter 或指令後，點擊儲存。

​
刪除子代理

點擊代理卡片上的移除按鈕，再次點擊確認。代理檔案將被永久刪除。
磁碟上代理檔案的變更會自動偵測。若您使用外部編輯器編輯代理檔案，面板會即時更新。

​
指令檔案

Skill 可以透過自己附帶的指令檔案來驅動子代理（通常是 general）。產生代理時，主代理可傳入選用的 instructions_file 路徑—一個 Markdown 檔案，其內容會附加到子代理的系統提示中，置於 Task-Specific Instructions 標題之下。

​
運作方式

  1. Skill 在 SKILL.md 旁附帶一個指令檔案（例如 agents/grader.md）
  2. 主代理產生子代理時，將 instructions_file 指向該檔案
  3. CTOR 會移除檔案的 frontmatter，並將內文原樣附加—不做樣板替換或變數替代
  4. 指令中參照的任何輸入值（例如檔案路徑、設定）由呼叫者在任務提示中傳入

​
路徑解析

  • 相對路徑以專案根目錄為基準解析
  • 絕對路徑必須位於以下允許的目錄之一：
    • 專案目錄
    • 專案或全域 skill 目錄
    • 專案或全域代理目錄
    • 內建 skill 目錄
超出這些目錄的路徑會基於安全性被拒絕。

​
範例

一個包含 agents/grader.md 指令檔案的 skill：
grader.md 使用標準的代理檔案格式：
主代理會使用此檔案產生 general 子代理，並在任務中傳入具體的值。

​
模型解析

子代理執行時，其模型按以下順序解析：
  1. 代理檔案的 model 欄位 —若代理檔案指定了模型，則使用該模型
  2. 設定預設值 —在設定中設定的預設子代理模型
  3. 服務商特定預設值 —目前服務商的低成本模型：Anthropic 使用 claude-haiku-4-5-20251001，OpenAI Codex 和 GitHub Copilot 使用 gpt-5.4-mini，Google 使用 gemini-3.5-flash，OpenCode Zen 使用 minimax-m2.5，OpenCode Go 使用 minimax-m2.7
  4. 工作階段模型 —目前工作階段所選的模型
這意味著子代理會自動為目前服務商使用低成本模型，無需逐一設定。

​
思考層級解析

子代理執行時，其思考層級按以下順序解析：
  1. 代理檔案的 thinking_level 欄位 —若代理檔案指定了思考層級，則使用該層級
  2. 設定預設值 —在設定中設定的預設子代理思考層級
  3. 模型特定後備 —對於 OpenAI Responses API 上的推理模型，預設為 low