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

​
內建子代理

CTOR 包含兩個內建子代理：
名稱說明工具
general通用代理，用於研究、多步驟編輯、指令執行與分析所有內建工具（spawn_agent 除外）
explore唯讀的程式碼庫搜尋與探索read_file、glob、grep
內建子代理無法編輯或刪除。

​
管理子代理

點擊側邊欄工具列中的子代理按鈕，開啟管理面板。

​
範圍

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

​
建立子代理

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

​
代理檔案格式

子代理為帶有 YAML frontmatter 的 markdown 檔案： 
---
name: my-agent
description: Describe when to use this agent
thinking_level: low
tools:
  - read_file
  - glob
  - grep
---

You are a specialized agent. Describe your purpose and instructions here.
Frontmatter 欄位：
欄位必填說明
name是代理的唯一識別碼
description否何時使用此代理（顯示於代理卡片中）
model否AI 模型覆蓋設定（例如 anthropic/claude-haiku-4-5-20251001）。請參閱模型解析
thinking_level否思考層級覆蓋（off、minimal、low、medium、high、xhigh）。請參閱思考層級解析
tools否代理可使用的工具清單
未指定 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： 
my-skill/
├── SKILL.md
├── agents/
│   └── grader.md       # 給 general 子代理的指令
└── rules/
    └── conventions.md
grader.md 使用標準的代理檔案格式： 
---
name: grader
---

Grade the outputs found in the directory specified in the task.
Compare each output against the expectations provided.
Write a summary report to the outputs directory.
主代理會使用此檔案產生 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