今日热点软件工程已经从编写一行行代码转变为编排 Agent。伴随着这一转变，通过分工协作将复杂项目拆解为能够并行行动、验证和运行任务的专业化 Agent，为我们带来了真正释放生产力的契机。
正因如此，我们在 Antigravity 2.0 和 Antigravity CLI 中为自定义 Agent（Custom Agents）提供了原生深度支持，Antigravity IDE 也将很快跟进支持。
本文将详细介绍什么是自定义 Agent、如何在几秒钟内完成设置，以及我们为自定义 Agent 赋予的 Antigravity 独有核心功能。
什么是自定义 Agent，为什么它们如此重要？
通用编程助手固然出色，但它们存在两个主要局限性：
-
缺乏专业化：通用型助手并不了解你特定项目的测试规范或依赖项管理规则，除非你在每次对话时都向它重新解释一遍。
-
上下文窗口膨胀：如果把包含所有编程规范、代码检查规则和测试准则的庞大提示词加载到每一次聊天中，将会造成灾难性的 Token 预算浪费。
自定义 Agent 解决了这一问题。它们是基于文件的专业化配置，用于定义具有专属指令范围、工具和约束条件的特定角色。这能让你的活动上下文保持干净整洁，最大限度减少 Token 开销，并为你提供处理特定任务时可预期的可靠搭档。
读到这里，你可能会想：这些问题难道不是已经通过技能（Skills）和动态子 Agent 解决了吗？在很大程度上，确实如此！自定义 Agent 并非用来取代技能和动态子 Agent，它们只是提供了更丰富的可定制性，从而实现更深一层的优化：
-
技能通过提供额外的上下文和领域指令，使自定义 Agent 更具专业性。通过渐进式发现机制，技能默认会在提示词中省略完整指令，直到真正需要时才加载，从而有效缓解上下文窗口膨胀问题。我们让 Agent 根据手头的工作自行判断是否需要读取完整技能。但是，如果你考虑一下自己在所有可能执行的任务中所需的全部技能集合，那仍然是一个非常庞大的列表，光是这些技能的描述本身就会占用大量上下文。通过自定义 Agent，你可以明确指定与当前专业角色真正相关的技能子集。同样的机制也适用于 MCP 服务器、钩子（Hooks）以及其他现有的自定义扩展点。在此基础之上，自定义 Agent 还支持定制系统指令、默认工具以及 Agent 循环中其他更“核心”的部分。
-
我们在几个月前推出了动态子 Agent，它们同样在这些维度上发挥着重要作用，允许主 Agent 将部分工作委派给子 Agent，从而避免污染主 Agent 的上下文。其中的“动态”体现在主 Agent 可以自行指定发送给子 Agent 的提示词。而借助自定义 Agent，我们更进一步：允许主 Agent 将任务委派给具有上述特定自定义配置的自定义 Agent，甚至还可以指定模型和权限等更多细节。
Antigravity 2.0 与 CLI 现已支持的功能
自定义 Agent 现已在可视化的 Antigravity 2.0 桌面应用和 Antigravity CLI 中实现全面集成。
与技能（Skills）类似，我们采用了包含 YAML 前置元数据（frontmatter）标头的 Markdown 文件格式，从而同样支持自定义 Agent 的渐进式发现。你可以将这些文件保存在本地工作区的 .agents/agents/ 目录下，或保存在用户全局的 ~/.gemini/config/agents/ 目录下。
将特定于项目的 Agent 提交到 .agents/agents/ 目录后，签出该代码库的每位团队成员都能自动使用它们——无需手动设置，即可让整个团队开箱即用地获得标准化、即时的工作流助手。
以下是一个简单 Agent 的 101 基础蓝图：
---
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.创建一个专业化 Agent 只需要单个 Markdown 文件。前置元数据（frontmatter）告诉产品如何运行该 Agent，而 Markdown 正文则会直接编译为它的系统提示词。请查看异步子 Agent 文档，了解前置元数据支持的所有字段。
是什么让 Antigravity 自定义 Agent 与众不同？
如果你使用过该领域的其他工具，一定会对这种 Markdown 加 YAML 前置元数据（frontmatter）的布局感到非常熟悉。我们特意对齐了文件规范，以便你尽可能轻松地迁移现有的自定义 Agent。
话虽如此，这些 Agent 在 Antigravity 底层运行的方式在架构上却截然不同。让我们以基础的 dependency-modernizer（依赖项现代化升级助手）为例并在此基础上展开，重点介绍 Antigravity 自定义 Agent 带来的一些独特可能性。
真正的对称性：主 Agent 与子 Agent
在同领域的其他工具中，自定义 Agent 仅限于作为子 Agent 运行。作为用户，你只能与默认的主 Agent 交互，由它在底层机制中根据前置元数据描述决定何时派生工作 Agent。你无法直接以自定义 Agent 的身份启动主会话。
Antigravity 通过简单的配置标志引入了“执行对称性”（execution symmetry）：
# Add these to the YAML frontmatter:
mainAgent: true
subagent: true启用这些配置标志后，你可以通过以下两种方式运行自定义 Agent：
- 作为主 Agent：你可以直接从 Antigravity 2.0 图形界面的下拉菜单中选择 dependency-modernizer，或者使用 CLI 运行它（agy --agent dependency-modernizer）。特定的核心指令会直接编译进系统提示词中，并且会自动应用前置元数据中定义的所有 Agent 执行参数，方便你直接与自己的自定义 Agent 对话。
在 Antigravity 2.0 中直接选择自定义 Agent 并将其作为主 Agent 运行
- 作为子 Agent：按照标准模式，同一个 Agent 也可以由协调器 Agent 作为工具动态调用。
由协调器 Agent 委派，将自定义 Agent 作为子 Agent 执行
限定作用域的安全策略（commandExecutionPolicy）
运行一个需要执行命令行操作（如安装依赖项或运行测试套件）的 Agent 有时会令人非常抓狂。如果安全策略过于宽松，你将面临运行未经验证代码的风险；如果安全策略过于严格，你又会陷入不断弹出审批提示的死循环中。
虽然 Antigravity 和其他工具都支持基础的“全有或全无”式权限级别（例如 acceptEdits 或 bypassPermissions），但我们增加了一个专门的执行过滤器：
# Add this to the YAML frontmatter:
permissionMode: acceptEdits
commandExecutionPolicy: auto将 commandExecutionPolicy 设置为 auto，可允许 Agent 在后台自主执行标准的测试和编译命令；而高风险命令（例如删除文件）则依然严格受控于人工审批。这使得现代化升级助手能够在后台快速执行试错循环，而不会频繁弹窗打断你请求批准。
精选技能与限定作用域的工具集（skills 与 tools）
当通用型助手同时配备数十种工具、MCP 服务器和全局工作区指南时，往往容易出现工具混淆和上下文膨胀的问题。
Antigravity 自定义 Agent 支持显式定义该 Agent 可用的确切工具子集与领域技能子集：
# Add these to the YAML frontmatter:
tools:
- view_file
- replace_file_content
- run_command
skills:
- skills/package-upgrade-rules自定义 Agent 不会用整个工作区注册的每一项技能和每一个 MCP 工具去污染上下文窗口，而是只接收与其专业角色相关的资源。在 dependency-modernizer 示例中，它可以直接访问文件编辑、命令执行以及团队特定的 package-upgrade-rules 技能，同时排除无关的工具（例如浏览器自动化或数据库查询工具）。这有助于让你的 Agent 始终专注于手头的确切任务。
展望未来
自定义 Agent 只是我们在整个产品栈中构建连贯定制化体系的下一步，旨在让 Antigravity 能够以更高效的方式协助完成更复杂的任务。
若要开始使用，请查看文档中的自定义 Agent 指南，并立即在你的工作区中尝试定义第一个自定义 Agent。
祝编程愉快！:)