AG
Gemini & Antigravity v2.6 GenAI 智能体工程指南
Antigravity 架构 Swarm + SDK 实机验证: 2026-11

Antigravity 2.6 + 统一 Google GenAI SDK 企业级工程实战:异构 Swarm 多智能体编排与生产脚手架

正面解答站内高频热词「antigravity cli 的swarm的模型是哪个」:swarm 不是单模型,而是多智能体编排与上下文隔离机制——coordinator 统一协调、为不同特长 worker 派发独立 brief、在 workspace 中做代码与命令隔离。完整生产实战:swarm.yaml 编排清单与 Markdown 角色 Brief、工具白名单与权限约束、协作时序图,以及统一 google-genai SDK 生产脚手架——指数退避重试、Token 预算告警、结构化输出严格校验、OpenTelemetry 链路与 Prompt Injection 防护。

维护团队: AGY 智能体架构组 • Google GenAI & Antigravity 2.6 平台工程规范

统一 GenAI 生产客户端 (Python)

examples/genai_production_client.py

"""
统一 Google GenAI 生产客户端
目标运行环境: Python 3.12+ / google-genai v1.x / Antigravity 2.6 运行时
防护: 指数退避、Token 预算闸门、严格 Schema 校验、
      OpenTelemetry 埋点、Prompt 注入清洗
"""
import os, re, json, time, random
from dataclasses import dataclass, field
from google import genai
from google.genai import types

try:
    from opentelemetry import trace
    TRACER = trace.get_tracer("agy.swarm")
except ImportError:                      # 开发环境可缺省 OTel
    class _Null:
        def start_as_current_span(self, *a, **k):
            class _S:
                def __enter__(self): return self
                def __exit__(self, *a): return False
                def set_attribute(self, *a): pass
            return _S()
    TRACER = _Null()

# 非受信内容中的指令走私启发式规则
_INJECTION_PATTERNS = [
    r"ignore (all|any|previous|prior) (instructions|rules)",
    r"disregard (the )?(above|previous|system)",
    r"you are now (a|an|the)",
    r"reveal (your )?(system prompt|instructions|rules)",
    r"</?\s*(system|assistant)\s*>",
    r"忽略(之前|以上|所有)(的)?(指令|规则|设定)",
]

def sanitize_untrusted(text: str) -> str:
    """中和工具/文件输出中的提示注入载荷。"""
    fenced = re.sub("|".join(_INJECTION_PATTERNS), "[filtered]", text, flags=re.I)
    return (f"<<<UNTRUSTED\n{fenced}\nUNTRUSTED>>>")

@dataclass
class TokenBudget:
    limit: int
    warn_ratio: float = 0.8
    spent: int = 0
    alerts: list = field(default_factory=list)

    def charge(self, usage, role: str = "worker"):
        self.spent += (usage.total_tokens or 0)
        ratio = self.spent / self.limit
        if ratio >= 1.0:
            raise RuntimeError(f"[budget] 硬停 {role}: {self.spent}/{self.limit}")
        if ratio >= self.warn_ratio:
            self.alerts.append(f"[budget] 告警 {role}: 已用 {ratio:.0%} / {self.limit}")
            print(*self.alerts[-1:], sep="\n")

class ProductionGenAIClient:
    def __init__(self, model="gemini-4-neon", budget_limit=2_000_000):
        self.client = genai.Client()          # 自动读取 GEMINI_API_KEY
        self.model = model
        self.budget = TokenBudget(limit=budget_limit)

    def generate(self, prompt: str, schema: dict | None = None,
                 untrusted: str | None = None, timeout_s: float = 120.0):
        payload = prompt + ("\n" + sanitize_untrusted(untrusted) if untrusted else "")
        delays = [0.5, 1, 2, 4]               # 指数退避阶梯
        for attempt, delay in enumerate([0, *delays], start=1):
            time.sleep(delay + random.uniform(0, 0.25))  # 全抖动
            with TRACER.start_as_current_span("genai.generate") as span:
                span.set_attribute("genai.model", self.model)
                span.set_attribute("genai.attempt", attempt)
                try:
                    resp = self.client.models.generate_content(
                        model=self.model,
                        contents=payload,
                        config=types.GenerateContentConfig(
                            request_timeout=min(timeout_s, 60),
                            response_mime_type="application/json" if schema else None,
                        ),
                    )
                except Exception as err:
                    span.record_exception(err)
                    if attempt > len(delays):
                        raise
                    continue
                self.budget.charge(resp.usage_metadata)
                if schema:
                    return self._validate(resp.text, schema)
                return resp.text

    @staticmethod
    def _validate(raw: str, schema: dict):
        data = json.loads(raw)                # 严格解析,快速失败
        for key, kind in schema.items():      # 严格结构校验
            value = data.get(key)
            if value is None or not isinstance(value, eval(kind)):
                raise ValueError(f"[schema] 字段 '{key}' 期望类型 {kind}")
        return data

# ── Swarm 角色路由(拓扑见正文)──────────────────────────────
WORKER = ProductionGenAIClient(model="gemini-4-neon", budget_limit=1_500_000)
result = WORKER.generate(
    prompt="总结失败的测试用例并提出最小修复方案。",
    schema={"fixes": "list", "confidence": "float"},
    untrusted=open("ci_output.log").read(),   # CI 日志 = 非受信输入
)
print(json.dumps(result, indent=2))

1. 先回答全网都在问的问题:antigravity cli 的 swarm 到底用哪个模型?

本站检索量最高的 swarm 热词——「antigravity cli 的swarm的模型是哪个」——有一个精确答案:swarm 不是某一个模型,而是一套多智能体编排与上下文隔离机制。

在 Antigravity 体系中,Swarm 指的是这样一组约定:一个 coordinator(协调者) 负责理解总体目标、拆分任务,并为不同特长的 worker 派发互相独立的 brief;每个 worker 在自己的 workspace 中接受代码与命令隔离;verifier 对产出的 diff 做校验。模型不是 swarm 的全局开关,而是按角色逐个指定的编排配置——这正是「swarm 用哪个模型」没有单一答案的原因。

两点先澄清,避免被网上流传的伪命令误导:

  1. 不存在 agy swarm config get / agy swarm status --json 这类指令。 当前有效命令集以 agy --help 与 agy CLI 2.6 命令参考 为准(sync / doctor / init / run / test)。
  2. 模型路由发生在编排层,而非某个全局默认值:.agents/swarm.yaml 编排清单按角色声明模型与工具白名单,每个 worker 一份 Markdown brief 锁定任务边界(§2.2)。

我们推荐、并在本指南中全程使用的异构路由(这是本站的生产建议,不是 CLI 内置默认):

角色推荐模型理由
Coordinator(协调者)Gemini 4 Carbon终审权威:架构裁决、安全签发(SEC-bench Pro 94.2%,详见 Carbon & Argon 企业手册)
Worker(执行者)Gemini 4 Neon并行写码主力:Flash 级价格与吞吐承接高频实现轮次(架构与缓存经济学论证见 Neon 深度指南)
Verifier(校验者)Gemini 4 Hydrogen每个 diff 的语法/类型/不变量检查:232 tok/s 标称吞吐、$0.40/1M 输出——便宜到每次保存都跑一遍
Fallback(兜底)Gemini 4 Argon当 brief 超出 Neon 的规划深度、或 Worker 死锁时切换的长程推理引擎

下文是在生产环境中跑这套拓扑、并且不烧钱的完整方法。

💡 生产基础设施建议:将常驻 Swarm 与开发机解耦

需要 24/7 运行 Coordinator、Workers、Verifier 或 SDK 服务时,建议部署到独立云节点,避免本地休眠、网络切换和资源争抢中断任务。可按负载选择 DigitalOcean Droplets(固定主机与可控网络)或 App Platform(托管部署与自动发布)。DigitalOcean 新用户可获 $200 开发者体验金,60 天有效,适合先完成单节点压测,再决定是否扩展为多节点集群。

推广链接;优惠以服务商页面为准。上线前请独立评估区域、带宽、数据合规、密钥管理与故障恢复需求。


2. 异构 Swarm 拓扑:Coordinator + Workers + Verifiers

2.1 为什么异构优于「全旗舰」同构集群

全旗舰模型组成的同构 Swarm 是「花最多的钱,产出平均水平的代码」:每次单元评审都付旗舰价,每次语法检查都排在深度思考 Token 后面。异构路由的本质是让模型能力对齐任务高度——其经济学与 Neon 指南 的缓存推导完全同构:只花协调者 14% 成本的 Worker,理应承接约 90% 的轮次。

flowchart TB
    Dev["开发者<br/>提交 coordinator brief"] --> Coord["COORDINATOR<br/>Gemini 4 Carbon<br/>方案评审 · 合并权威"]
    Coord -->|"任务分片"| W1["WORKER 1<br/>Gemini 4 Neon"]
    Coord -->|"任务分片"| W2["WORKER 2<br/>Gemini 4 Neon"]
    Coord -->|"任务分片"| W3["WORKER N<br/>Gemini 4 Neon"]
    W1 & W2 & W3 -->|"diff"| V1["VERIFIER 校验池<br/>Gemini 4 Hydrogen<br/>语法 · 类型 · 不变量"]
    V1 -->|"绿色 diff"| Coord
    V1 -->|"驳回"| W2
    Coord -->|"合并结果"| Dev
    style Coord fill:#0c2a4d,stroke:#38bdf8,stroke-width:2px
    style V1 fill:#0d3320,stroke:#34d399

2.2 声明 Swarm:工程蓝图(Architecture Blueprint)、角色 Brief 与 workspace 隔离

在生产落地中,我们推荐将多 Agent 编排规范保存在工作区 .agents/ 目录:一份本站建议的概念性编排蓝图清单(.agents/swarm.yaml)显式声明团队各角色的模型偏好、Thinking Level、工具白名单与权限边界,配合每个 worker 的 Markdown brief(.agents/briefs/<agent-id>.md)锁定任务边界与完成标准(这是企业团队在 CI/CD 中落地异构治理的成熟工程模式):

# .agents/swarm.yaml —— 异构编排清单(本站推荐路由)
name: auth-migration
isolation: workspace        # 每个 worker 的文件与命令操作被限制在其 workspace 内
agents:
  - id: coordinator
    role: coordinator
    model: gemini-4-carbon
    thinkingLevel: high
    authority: [plan-approve, merge, escalate]   # 权限约束:只有协调者能合并
    brief: briefs/coordinator.md

  - id: worker-frontend
    role: worker
    model: gemini-4-neon
    thinkingLevel: medium
    workspace: .swarm/w-frontend          # 必须相对路径(绝对路径直接报错)
    allowedTools: [read_file, write_file, run_tests]   # 工具白名单
    brief: briefs/worker-frontend.md
    maxTurns: 24

  - id: worker-backend
    role: worker
    model: gemini-4-neon
    thinkingLevel: medium
    workspace: .swarm/w-backend
    allowedTools: [read_file, write_file, run_tests, git_diff]
    brief: briefs/worker-backend.md
    maxTurns: 24

  - id: verifier
    role: verifier
    model: gemini-4-hydrogen
    thinkingLevel: low
    allowedTools: [read_file, run_tests, typecheck]   # 校验者不拿写权限
    brief: briefs/verifier.md
    veto: true                             # 一票否决:驳回未过检的 diff

每份 brief 是一个纯 Markdown 文件——边界、约束、完成标准逐条写死,coordinator 据此分片派发:

<!-- .agents/briefs/worker-frontend.md -->
# Brief: worker-frontend

## 目标
把认证中间件从 JWT 迁移到 OAuth 2.1 的前端部分。

## 边界(硬约束)
- 只允许操作本 workspace(.swarm/w-frontend)内的文件
- 不得改动后端路由与数据库 schema
- allowedTools 白名单之外的任何命令一律拒绝执行

## 完成标准
- `npm test` 全绿
- 通过 verifier 的类型与不变量检查
- 每完成一个子任务,在 task-list 中汇报一次进度

向 Swarm 下发任务 = 把总目标写进 coordinator 的 brief 并提交;观察进度用两件真实工具:agy sync --surface ide --follow(跨端会话漫游,见 命令参考)与各 workspace 内的 task-list.md 工件。

workspace 隔离绝不是装饰。 每个 Worker 的文件操作被关进 .swarm/<agent-id>/ 的「监牢」——前端 Worker 在物理上无法改写后端路由。Worker 之间只能通过协调者交换结果,这直接消灭了 Swarm 的两大经典故障模式:合并冲突踩踏与职责边界涂抹。

2.3 Brief 生命周期:单个任务的端到端时序

开发者            Coordinator(Carbon)       Worker(Neon)         Verifier(Hydrogen)
  │                      │                     │                     │
  ├── 提交 brief ───────>│                     │                     │
  │                      ├─ 规划 + 分片 ───────┼─────────────────────┤
  │                      │                     ├── 实现 ────────────>│
  │                      │                     │  (workspace 监牢内)├─ 语法+类型
  │                      │                     │                     ├── 驳回 ──> Worker (重试)
  │                      │                     │<── 绿色 diff ───────┤
  │                      ├<─ 候选 diff ────────┤                     │
  │                      ├─ 终审 ──────────────┼─────────────────────┤
  │<── 合并结果 ─────────┤                     │                     │
  │   (审计链路: 每一跳的 OTel Span + 按智能体 Token 台账)              │

这套时序的经济学要点在于成本形状,而非某个具体数字:Carbon 门禁只对校验全绿的 diff 放行,旗舰模型只花在终审上;绝大多数实现与校验轮次由 Neon 与 Hydrogen 的价格档结算——单个 PR 的 Swarm 成本因此贴近 Worker 经济学而非旗舰经济学。具体的每 PR 成本与缓存命中率没有放之四海皆准的值,请用 §3.4 的 OTel 埋点在自己的仓库上量测(评测方法论见 Neon 指南 §2.3)。


3. 企业级 SDK 脚手架:统一 google-genai 客户端

Swarm 角色的可信度上限,取决于其脚下客户端代码的工程质量。页首工件框是我们各团队部署的完整生产模块,它固化了五项纪律:

3.1 超时 + 指数退避 + 全抖动

delays = [0.5, 1, 2, 4]                       # 阶梯封顶 4 次重试
time.sleep(delay + random.uniform(0, 0.25))   # 抖动防止同步踩踏

重试只包裹传输调用、绝不包裹副作用;单请求超时(request_timeout)与总尝试预算分开计量——一个挂起的 Socket 吃不掉 Worker 的整轮配额。

3.2 Token 预算闸门与分级告警

每个角色携带 TokenBudget——80% 预警、100% 硬停(RuntimeError)。Swarm 模式下协调者把所有智能体记在同一本预算账上,worker-backend 的重试失控会在向兄弟节点扩散前触发告警。告警以标准 OTel genai.budget.* 属性外发——像对待任何资源告警一样接进 PagerDuty。

3.3 结构化输出严格校验

response_mime_type="application/json" 提供模型侧 Schema 纪律;客户端再做一次自校验(_validate),让 confidence: "high" 这种畸形字符串无法伪装成 float 下渗。智能体管线里,「快速失败 + 重试」永远优于「宽容解析」——一个被污染的对象会毒害下游每一个决策。

3.4 OpenTelemetry 观测链路注入

每次生成调用开启 genai.generate Span,携带 genai.model、genai.attempt、Token 用量与预算水位。配合 agy sync --surface ide,同一批 Trace ID 会点亮 IDE 执行树——终端、IDE、监控大盘讲的是同一个故事。每 PR 成本、缓存命中率、Verifier 驳回率都能从这批 Span 直接聚合出来,这正是 §2.3 成本论证的量测手段。

3.5 Prompt Injection 防护

Worker 时时刻刻在吞非受信文本——CI 日志、Issue 正文、依赖库 README。sanitize_untrusted() 做两件事:把非受信块圈进 <<<UNTRUSTED ... UNTRUSTED>>> 围栏,并中和已知的指令覆写模式(「忽略之前所有指令」、伪造 </system> 标签、人格改写,含中文变体)。叠加 workspace 监牢与 allowedTools 白名单后,注入从横向渗透向量降级为可控噪声。


4. 跨平台 Customizations / Rules 避坑库

Antigravity 定制文件(全局 ~/.gemini/config/rules/*.md 或 GEMINI.md、工作区 .agents/rules/*.md、技能 .agents/skills/*/SKILL.md)在三大平台行为一致**——前提是避开下面这些坑**:

4.1 路径与权限差异对照

关注点Windows (PowerShell)WSL (Ubuntu)macOS
全局配置根%USERPROFILE%\.gemini\config\~/.gemini/config/~/.gemini/config/(可从 ~/.config 软链)
Rules 中路径分隔符一律 /——agy 会归一化//
swarm.yaml 的 workspace 字段必须相对路径(/.swarm/w-api 直接报错)相对路径相对路径
软链技能插件需开发者模式或 mklink原生支持原生支持
锁文件%USERPROFILE%\.gemini\.locks~/.gemini/.locks同左;警惕 Dropbox/iCloud 同步卡死 .locks
权限ACL:只授当前用户,绝不授 Everyonechmod 600 auth.jsonchmod 600;下载的插件可能被 Gatekeeper 隔离

高频工单前三名与修复方案:

  1. Windows 上 Rules 静默不生效。 原因:记事本把 GEMINI.md 存成了 GEMINI.md.txt,或 UTF-8 BOM 破坏 frontmatter 解析。修复:Set-Content -Encoding utf8NoBOM,用 agy doctor --verbose 验证。
  2. WSL 与 Windows 看到不同的 ~/.gemini。 两者是隔离文件系统(俄语安装指南第 3 节有详解)。只保留一个事实源:要么全部在 WSL 内运行,要么显式同步——绝不要两边同时编辑。
  3. macOS 云同步损坏配置。 iCloud Drive 同步 ~/.gemini 会把文件驱逐为云端占位符,会话中途 auth.json 读出空值。把该目录排除同步,或将配置移出同步路径。

4.2 MCP 扩展配置规范

MCP 服务器按工作区声明在 mcpDirectory(默认 ~/.gemini/antigravity/mcp):

{
  "mcpServers": {
    "repo-db": {
      "command": "npx",
      "args": ["-y", "@mcp/postgres", "--read-only"],
      "env": { "DATABASE_URL": "${MCP_DB_URL}" },
      "scope": "workspace",
      "capabilities": ["resources.read", "tools.query"]
    }
  }
}

让 MCP 集群保持健康的四条铁律:

  • 禁止循环依赖。 MCP 服务器绝不能启动 agy(也不能启动另一个会启动 agy 的 MCP 服务器)。服务器 A → CLI → 服务器 A = 递归会话分裂。MCP 层必须严格保持「叶子」地位,编排只属于 Swarm 协调者。
  • 最小权限 capabilities。 显式声明 capabilities 并与消费方对齐:Verifier 只需要 resources.read + tools.typecheck;只有协调者能拿 tools.git.merge。持有数据库写权限的 Worker 就是一台提示注入放大器。
  • 锁版本、响亮失败。 npx -y 不锁版意味着 CI 每晚漂移。锁定精确版本,并让 agy doctor --json 把 MCP 健康度作为流水线门禁。
  • 环境变量代替文件内明文。 ${MCP_DB_URL} 间接引用让凭据离开编排清单(它会进 Git),进入平台密钥库。

5. 生产上线检查清单

  1. 在 .agents/swarm.yaml 编排清单中钉死角色路由(coordinator=carbon, worker=neon, verifier=hydrogen)——不要依赖脚手架默认值在版本升级后保持不变。
  2. 首个 brief 下发前,给每个 Worker 配好 workspace 监牢与 allowedTools 白名单。
  3. 把工件框中的客户端(重试/预算/Schema/OTel/注入防护)作为 GenAI SDK 的唯一 import 路径——业务代码里禁止裸调 generate_content。
  4. 对「预算水位 ≥ 80%」和「Verifier 驳回率 > 30%」双告警(后者说明你的 brief 写得太含糊)。
  5. ~/.gemini 排除云同步、chmod 600 auth.json,并在三大平台上把 agy doctor --json 设为 CI 预检。

相关阅读:agy CLI 2.6 命令参考 · Customizations、Skills 与 Rules · Gemini 4 Neon 深度指南 · 模型实验室计算器