Subagents 與 Hooks
這一頁介紹兩種進階能力：子代理（subagent）讓大任務可以平行分工，掛鉤（hook）讓你在代理執行的關鍵時刻自動跑腳本。最後簡介外掛（plugin），可把前面提到的東西打包。
Subagents：平行分工
子代理是在背景非同步執行的獨立代理。主代理用 invoke_subagent 工具派出子代理，每個有自己的角色與獨立的上下文，所以你可以繼續和主代理互動，不必等長任務完成，也不會因為大量搜尋結果而汙染主對話。適合大範圍重構、多檔案產生、研究掃描。
自訂子代理
自訂子代理是一個 Markdown 檔，開頭有 YAML front matter：
| 範圍 | 位置 |
|---|---|
| 工作區 | .agents/agents/<名稱>.md |
| 全域 | ~/.gemini/config/agents/<名稱>.md |
---
name: test-writer
description: 為指定模組補寫單元測試。當使用者要求補測試時使用。
tools: [view_file, run_command]
model: flash
commandExecutionPolicy: sandbox
---
你是測試撰寫專家。先閱讀目標模組，再依專案既有的測試風格補寫測試，
最後執行測試並回報結果。
| 欄位 | 說明 |
|---|---|
name、description |
必填 |
tools |
允許使用的工具，例如 view_file、run_command |
model |
inherit（沿用主代理）、flash 或 pro |
commandExecutionPolicy |
指令執行方式：sandbox、auto、off |
skills、mcpServers |
讓子代理帶著特定的 Skills 與 MCP |
子代理的工作區可以沿用主代理的、建立獨立的 Git worktree，或共用目錄。它有三種狀態：執行中、閒置（收到訊息會自動喚醒）、已終止。巢狀最多 10 層，防止遞迴失控。
在 CLI 管理
輸入 /agents 開啟面板，查看執行中與已完成的子代理、目前的步驟。子代理需要核准時有兩種提示：進入詳細檢視逐一處理，或在輸入框上方出現快速通知；Ctrl+J 跳到下一個待核准項目，Ctrl+K 快速核准。
Hooks：在關鍵時刻自動跑腳本
Hooks 讓你在代理執行迴圈的特定時間點，執行自己的腳本或指令，用來強制規範、跑 linter、記錄診斷資訊。
五個事件
| 事件 | 時機 |
|---|---|
PreToolUse |
工具執行前 |
PostToolUse |
工具執行後 |
PreInvocation |
呼叫模型前 |
PostInvocation |
模型回應後 |
Stop |
執行結束時 |
設定檔
hooks.json 可放在工作區 .agents/hooks.json、全域 ~/.gemini/config/hooks.json，或外掛內（僅 CLI）。下面的例子是：每次代理執行完 run_command 之後，自動跑 lint 腳本。
{
"my-linter-hook": {
"PostToolUse": [
{
"matcher": "run_command",
"hooks": [
{
"type": "command",
"command": "./scripts/lint.sh",
"timeout": 10
}
]
}
]
}
}
Hook 透過標準輸入與輸出交換 JSON。輸入包含 conversationId、workspacePaths、transcriptPath、modelName 等欄位；每個事件各有自己的輸入與輸出格式，寫之前請查官方 Hooks 文件。
Plugins：打包分享
外掛（plugin）是具名稱空間的套件，可把 skills、agents、rules、MCP 伺服器與 hooks 包成單一可部署單元。CLI 的外掛放在 ~/.gemini/antigravity-cli/plugins/<外掛名>/，需要一個 plugin.json 標記檔，並可含 MCP 與 hooks 設定，以及 skills、agents、rules 目錄。舊 Gemini CLI 的擴充套件可用 agy plugin import gemini 轉換，見 從 Gemini CLI 遷移。