推出自訂代理

Antigravity 團隊

·2026年8月12日·閱讀時間 6 分鐘

軟體工程已從撰寫程式碼，轉變為編排代理。透過分工，將複雜專案拆解為能行動、驗證並平行執行任務的專門代理，這種轉變帶來了真正的生產力突破機會。

這就是我們引入 自訂代理 在 Antigravity 2.0 與 Antigravity CLI 中獲得一流支援，Antigravity IDE 將隨後跟進。

本文詳述自訂代理是什麼、如何在數秒內設定一個，以及我們賦予自訂代理、Antigravity 獨有的關鍵功能。

什麼是自訂代理？它們為何重要？

通用程式撰寫助理很棒，但有兩個主要限制：

缺乏專業化：通用型助理不會知道您特定專案的測試慣例或相依性管理規則，除非您每次都向它說明。
情境視窗膨脹：將包含所有程式設計指南、linter 與測試規則的龐大單體提示詞載入每次對話，會造成 Token 預算災難。

自訂代理解決了這個問題。它們是專門的檔案式設定，為特定角色定義其專屬的範圍限定指示、工具與限制。這讓您的作用中情境保持乾淨、將權杖開銷降至最低，並為特定任務提供可預測的夥伴。

現在，您可能看完會想：這些問題難道技能與動態子代理無法解決嗎？很大程度上可以！自訂代理並不取代技能與動態子代理；它們只是提供更多自訂能力，達到另一層最佳化：

技能透過提供額外的上下文與領域指示，來專門化自訂代理。透過漸進式探索，技能預設會省略提示詞中的完整指示，直到需要時才載入，從而解決上下文視窗膨脹的問題。相反地，我們讓代理根據手邊的工作決定是否需要讀取完整的技能。但如果您想想所有任務可能需要的技能全集，那仍然是個非常大的清單，而且描述本身就佔用了大量上下文。自訂代理讓您可以指定與當前專門化真正相關的技能子集。同樣的概念也延伸到 MCP 伺服器、掛鉤及其他現有的自訂點。此外，自訂代理還讓您可以自訂系統指示、預設工具，以及代理迴圈中其他更「核心」的部分。
幾個月前我們推出了動態子代理，它們也沿著這些面向提供協助，讓主代理將部分工作委派給子代理，以免污染主代理的內容。『動態』之處在於主代理可以指定傳送給子代理的提示詞。透過自訂代理，我們更進一步，讓主代理可以委派給自訂代理，使用其特定的自訂內容（如前所述），以及其他詳細資訊，例如模型與權限。

Antigravity 2.0 與 CLI 今日提供的功能

自訂代理現在已完全整合於視覺介面與 Antigravity 2.0 桌面應用程式 和 Antigravity CLI.

與技能類似，我們採用包含 YAML 前置資訊標頭的 Markdown 檔案格式，讓自訂代理也能逐步探索。您可將這些檔案儲存在本機工作區的下列位置 .agents/agents/ 或使用者全域，於下 ~/.gemini/config/agents/.

將專案專屬代理提交至 .agents/agents/ 讓它們自動提供給取出儲存庫的每位隊友——讓整個團隊開箱即用標準化、即時的工作流程助理，無需手動設定。

以下是一個基本 101 Blueprint 簡易代理的

---
name: dependency-modernizer
description: Helps upgrade local packages and verify that project tests pass.
model: flash
tools:
  - view_file
  - replace_file_content
  - manage_task
  - run_command
---

# Core Instructions
You are a dependency modernizer. Your job is to check configuration files,
update target dependencies, run test suites, and verify the build passes.

建立專門代理只需要單一 Markdown 檔案。frontmatter 告訴產品如何執行代理，而 Markdown 內文會直接編譯為其系統提示詞。查看非同步子代理前置資料中所有支援欄位的文件。

Antigravity 自訂代理有何特別之處？

若您曾使用此領域的其他工具，這種 Markdown 與 YAML frontmatter 版面配置看起來會很熟悉。我們刻意讓檔案慣例對齊，以便盡可能無痛地移植您現有的自訂代理。

話雖如此，這些代理在 Antigravity 底層的運作方式在結構上有所不同。讓我們以基本的 dependency-modernizer 範例並加以發揮，以突顯 Antigravity 中自訂代理的一些獨特可能性。

真正的對稱性：主代理與子代理

在此領域的其他工具中，自訂代理受限於 僅限子代理。作為使用者，您與主要的預設代理互動，它會使用 frontmatter 描述決定何時在幕後產生您的工作器。您無法直接啟動主要工作階段為你的自訂代理。

Antigravity 推出 執行對稱性 使用簡單的設定旗標：

# Add these to the YAML frontmatter:
mainAgent: true
subagent: true

啟用這些旗標後，您可以透過兩種方式執行自訂代理：

作為主代理：您可以選取 dependency-modernizer 直接從 Antigravity 2.0 GUI 的下拉式選單執行，或使用 CLI 執行（agy --agent dependency-modernizer）。特定的核心指令會直接編譯進系統提示詞，您也會採用 frontmatter 中的所有代理執行參數，讓您能直接與自訂代理對話。

在 Antigravity 2.0 中直接將自訂代理選取並執行為主代理

作為子代理：依標準做法，同一代理可由協調者代理動態作為工具叫用。

將自訂代理作為子代理執行，由協調代理委派

範圍化安全政策（`commandExecutionPolicy`)

執行會執行命令列操作（例如相依性安裝或測試套件）的代理可能令人非常沮喪。如果安全政策太寬鬆，您會冒著執行未驗證程式碼的風險。如果政策太嚴格，您會陷入不斷的核准提示循環。

雖然 Antigravity 與其他工具都支援基本的全有全無權限等級（例如 acceptEdits 或 bypassPermissions），我們新增專屬的執行篩選器：

# Add this to the YAML frontmatter:
permissionMode: acceptEdits
commandExecutionPolicy: auto

設定 commandExecutionPolicy: auto 讓代理在背景自主執行標準測試與編譯指令。高風險指令（例如刪除檔案）仍嚴格限制於手動核准之後。這讓現代化工具能在背景進行快速試錯循環，無需不斷提示您核准。

精選技能與範圍限定的工具集（`skills` 和 `tools`)

通用助理在同時配備數十個工具、MCP 伺服器與全域工作區指南時，常受工具混淆與內容膨脹所苦。

Antigravity 自訂代理讓您可以明確定義該代理可用的工具與領域技能的精確子集：

# Add these to the YAML frontmatter:
tools:
  - view_file
  - replace_file_content
  - run_command
skills:
  - skills/package-upgrade-rules

自訂代理不會收到與其專長無關的資產，而非將整個工作區註冊的每個技能與 MCP 工具都塞入情境視窗。在 dependency-modernizer 例如，它可直接存取檔案編輯、指令執行，以及團隊專屬的 package-upgrade-rules 技能，排除不相關的工具（例如瀏覽器自動化或資料庫查詢工具）。這有助於你的代理專注於手頭的確切任務。

展望未來

自訂代理是我們朝向產品堆疊每個環節一致自訂體驗的下一步，讓 Antigravity 能以更有效率的方式協助處理更複雜的任務。

若要開始使用，請參閱自訂代理指南於文件中深入了解，並在今天的工作區中試著定義您的第一個自訂代理。

Happy hacking! :)