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 防护。
统一 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 用哪个模型」没有单一答案的原因。
两点先澄清,避免被网上流传的伪命令误导:
- 不存在
agy swarm config get/agy swarm status --json这类指令。 当前有效命令集以agy --help与 agy CLI 2.6 命令参考 为准(sync/doctor/init/run/test)。 - 模型路由发生在编排层,而非某个全局默认值:
.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:只授当前用户,绝不授 Everyone | chmod 600 auth.json | chmod 600;下载的插件可能被 Gatekeeper 隔离 |
高频工单前三名与修复方案:
- Windows 上 Rules 静默不生效。 原因:记事本把
GEMINI.md存成了GEMINI.md.txt,或 UTF-8 BOM 破坏 frontmatter 解析。修复:Set-Content -Encoding utf8NoBOM,用agy doctor --verbose验证。 - WSL 与 Windows 看到不同的
~/.gemini。 两者是隔离文件系统(俄语安装指南第 3 节有详解)。只保留一个事实源:要么全部在 WSL 内运行,要么显式同步——绝不要两边同时编辑。 - 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. 生产上线检查清单
- 在
.agents/swarm.yaml编排清单中钉死角色路由(coordinator=carbon, worker=neon, verifier=hydrogen)——不要依赖脚手架默认值在版本升级后保持不变。 - 首个 brief 下发前,给每个 Worker 配好
workspace监牢与allowedTools白名单。 - 把工件框中的客户端(重试/预算/Schema/OTel/注入防护)作为 GenAI SDK 的唯一 import 路径——业务代码里禁止裸调
generate_content。 - 对「预算水位 ≥ 80%」和「Verifier 驳回率 > 30%」双告警(后者说明你的 brief 写得太含糊)。
~/.gemini排除云同步、chmod 600 auth.json,并在三大平台上把agy doctor --json设为 CI 预检。
相关阅读:agy CLI 2.6 命令参考 · Customizations、Skills 与 Rules · Gemini 4 Neon 深度指南 · 模型实验室计算器