1. 先搞清楚循环外包的边界：Antigravity 托管 Agent 到底替你干了什么

Antigravity 是 Google 在 2025 年 11 月发布的 agent 优先开发平台，它把「派活、盯进度」从 IDE 里拆出来，单独做了一个 Manager 界面。到了 2026 年 5 月，Managed Agents 正式进入 Gemini API，一次 API 调用就能拿到一个带沙箱、带工具、能自己跑完任务的 Agent。这两个东西叠在一起，才引出「循环外包」这个说法——你不再自己写 while 循环去驱动模型，而是把整个任务委托出去，等结果。

但「外包」不是免费的。托管 Agent 收走了循环调度、沙箱供给、包安装、文件管理、联网检索这些脏活，代价是你在五个维度上让渡了控制权：循环控制、上下文管理、工具注册、计费透明度、安全边界。这篇文章只走一条主线——这五样交出去之后，官方给你留了什么刹车，以及什么任务根本不该外包。

适合谁看：已经在用 Gemini API 做单次生成、想升级到托管 Agent 的开发者；正在评估 Antigravity 与 Managed Agents 协作边界的团队；以及被自建循环的上下文裁剪、沙箱维护折磨过、想看看托管方案能不能接手的工程师。下面从接入配置讲到端到端验证，每一步都能直接复制。

2. TaoToken 统一 Key 接入 Gemini API 的前置准备

托管 Agent 的调用链里，第一跳是拿到一个能用的 API Key 和 Base URL。TaoToken 在这里的角色是统一入口——你不用为每个模型、每个 Agent 单独维护一套凭据，一个 Key 走通 Gemini API 的调用通道。

先明确三件套，这是后面所有配置的基础：

拿 Key 的路径很直接：打开 https://taotoken.net/api-keys ，登录后在控制台创建新的 API Key，复制保存。注意这个 Key 只在创建时完整显示一次，关掉页面就看不到了，建议直接写进环境变量而不是硬编码在代码里。

# Linux / macOS export TAOTOKEN_API_KEY="sk-你的key" export TAOTOKEN_BASE_URL="https://taotoken.net/api" # Windows PowerShell $env:TAOTOKEN_API_KEY="sk-你的key" $env:TAOTOKEN_BASE_URL="https://taotoken.net/api"

如果你用的是 Python 的google-genaiSDK，它默认读GEMINI_API_KEY环境变量。为了不改动官方示例代码，最省事的做法是把 TaoToken 的 Key 映射过去：

export GEMINI_API_KEY="$TAOTOKEN_API_KEY"

然后在客户端初始化时显式指定 base_url，让请求走 TaoToken 的通道：

from google import genai client = genai.Client( api_key="sk-你的key", # 或从环境变量读 http_options={"base_url": "https://taotoken.net/api"}, )

这一步做完，你的调用链第一跳就通了。接下来才是托管 Agent 本身的配置。需要提醒的是，托管 Agent 目前是 preview 状态，schema 可能有破坏性变更，生产负载要预留迁移路径，接口层最好做一层防腐封装，别让业务代码直接依赖 preview 的字段结构。

3. 可复制的托管 Agent 配置片段：从 inline 到注册固化

托管 Agent 的接入分两级：临时 inline 定制和注册成可按 ID 调用的托管 Agent。先看 inline，零注册，随用随传。

from google import genai client = genai.Client( api_key="sk-你的key", http_options={"base_url": "https://taotoken.net/api"}, ) interaction = client.interactions.create( agent="antigravity-preview-05-2026", # 注意：传 agent，不传 model input="审计 https://web.dev 的性能和 SEO，输出按优先级排序的修复建议", environment="remote", # 向 Google 申请远端沙箱 system_instruction="你是一名性能审计师，输出必须包含可执行的修复步骤", ) print(interaction.output_text)

三个注入点各有分工：system_instruction适合每次调用都想微调的内容，它与AGENTS.md是叠加生效而非覆盖；AGENTS.md挂到.agents/AGENTS.md，Agent 启动时自动加载为系统指令，适合长篇人设和需要进版本控制的规范；SKILL.md放在.agents/skills/<技能名>/SKILL.md，harness 自动发现并注册为技能。

配置迭代稳定后，用client.agents.create()固化。下面这个 JSON 片段对应的是注册时的base_environment结构，路径与官方原文一致：

{ "type": "remote", "sources": [ { "type": "inline", "target": ".agents/AGENTS.md", "content": "图表一律用 matplotlib。每份报告必须带汇总表" }, { "type": "repository", "source": "https://github.com/my-org/analysis-templates", "target": "/workspace/templates" } ], "network": { "allowlist": [ { "domain": "api.github.com", "transform": { "Authorization": "Basic YOUR_BASE64_TOKEN" } }, { "domain": "pypi.org" } ] } }

对应的 Python 注册调用：

agent = client.agents.create( id="data-analyst", base_agent="antigravity-preview-05-2026", agent_config={"type": "antigravity", "model": "gemini-3.7-flash"}, system_instruction="你是一名数据分析师。始终包含可视化图表，结果导出为 PDF", base_environment={ "type": "remote", "sources": [ {"type": "inline", "target": ".agents/AGENTS.md", "content": "图表一律用 matplotlib。每份报告必须带汇总表"}, {"type": "repository", "source": "https://github.com/my-org/analysis-templates", "target": "/workspace/templates"}, ], "network": { "allowlist": [ {"domain": "api.github.com", "transform": {"Authorization": "Basic YOUR_BASE64_TOKEN"}}, {"domain": "pypi.org"}, ] }, }, ) print(f"Created agent: {agent.id}")

注册后按 ID 调用，语义是每次调用 fork 一份 base environment，每个任务从干净状态起步：

result = client.interactions.create( agent="data-analyst", input="分析 /workspace/templates/sample.csv 的 Q1 营收并生成幻灯片", environment="remote", )

几个硬约束必须记住：id在项目内唯一，且不得以antigravity-、gemini-、google-、veo-等保留前缀开头，创建即失败；agent_config里模型在创建时锁定，调用时不可覆盖，官方解释是为了工具调用行为可预测、调试一致、安全边界稳定；每个项目最多 1000 个托管 Agent；agents.delete只删配置，已产生的环境和 interaction 不受影响。

运行时覆盖是另一个实用能力。凭据轮换时，你可以在下次调用传入新的 network 配置，新规则立即整体替换旧规则，而沙箱里的文件系统、已装包、已克隆仓库全部保留：

result = client.interactions.create( agent="issue-resolver", input="修复 issue #42 并开一个 PR", environment={ "type": "remote", "network": { "allowlist": [ {"domain": "api.github.com", "transform": {"Authorization": "Bearer ghp_REFRESHED_TOKEN"}}, {"domain": "pypi.org"}, ] }, }, )

4. 端到端验证：确认托管 Agent 调用链按预期收敛

配置写完不算完，得跑一次真实请求确认调用链收敛。验证的目标有三个：请求确实走了 TaoToken 的 Base URL；托管 Agent 在远端沙箱里完成了多轮循环；最终结果写回了 interaction。

先做一个最小验证，用后台执行模式，避免长任务挂着 HTTP 连接干等：

import time from google import genai client = genai.Client( api_key="sk-你的key", http_options={"base_url": "https://taotoken.net/api"}, ) interaction = client.interactions.create( agent="antigravity-preview-05-2026", input="克隆 https://github.com/my-org/backend，统计所有未完成的注释标记，" "按模块和优先级归类输出 markdown 报告", environment="remote", background=True, # 立即返回，服务端异步执行 ) result = interaction while result.status == "in_progress": time.sleep(5) result = client.interactions.get(interaction.id) if result.status == "completed": print(result.output_text) else: print(f"任务终态: {result.status}")

跑通之后，你会看到几个关键信号。第一，interaction.id正常返回，说明请求已经进入托管循环。第二，轮询过程中status从in_progress变为completed，说明沙箱内的多轮推理循环正常收敛。第三，output_text里有实际产出，说明工具调用（代码执行、联网检索、文件操作）都按预期执行了。

如果你想观察中间过程，可以改用流式模式，或者检查steps字段里的function_call记录。对于自定义函数，interaction 会进入requires_action状态，把控制权交回客户端执行，再把function_result回传完成第二轮。判别哪些调用需要你执行的官方模式是 pending diff：已执行的function_result里的call_id构成集合，function_call里不在集合中的就是待执行项。

# pending diff 判别示例 executed_ids = { step.function_result.call_id for step in result.steps if step.function_result } pending = [ step.function_call for step in result.steps if step.function_call and step.function_call.call_id not in executed_ids ]

验证通过的标准很简单：一次完整请求从发出到拿到completed终态，中间没有 401、没有连接超时、没有requires_action卡死。如果这三样都干净，说明你的 TaoToken 通道和托管 Agent 调用链已经按预期收敛。

5. 本篇常见报错排查：401、local proxy failed、reading choices、OAuth

接入过程中最容易撞上的几类报错，按踩中概率排序，逐个对照排查。

401 Unauthorized。最常见的原因是 Key 没传对或环境变量没生效。先确认GEMINI_API_KEY或api_key参数里的值确实是 TaoToken 控制台生成的 Key，没有多余空格。再确认base_url指向的是https://taotoken.net/api，而不是别的地址。如果用了.env文件，检查有没有被 shell 里的旧变量覆盖。

local proxy failed / connection refused。这类报错通常出现在客户端初始化阶段，说明请求根本没发出去。检查你的网络环境是否能正常访问taotoken.net，以及有没有本地代理配置干扰了 SDK 的 HTTP 客户端。google-genaiSDK 走的是标准 HTTPS，不需要额外代理设置。

reading choices 相关报错。如果你在解析响应时遇到reading 'choices'或类似字段缺失的错误，多半是把 OpenAI 风格的响应结构套到了 Gemini 的返回上。Gemini API 的响应字段是output_text、steps、status，不是choices。检查你的解析代码有没有混用两套 SDK 的字段名。

OAuth / 凭据过期。托管 Agent 的 access token 会过期，表现为调用时返回鉴权失败。这时候用运行时覆盖传入刷新后的 token，环境状态不动：

result = client.interactions.create( agent="issue-resolver", input="修复 issue #42 并开一个 PR", environment={ "type": "remote", "network": { "allowlist": [ {"domain": "api.github.com", "transform": {"Authorization": "Bearer ghp_REFRESHED_TOKEN"}}, {"domain": "pypi.org"}, ] }, }, )

MCP 服务器名大写直接 400。mcp_server的服务器名称必须匹配小写正则^[a-z0-9_-]+$，用了大写只会收到一个不含细节的通用 400，报错信息不指明原因。命名规范要写进团队约定。

采样参数传入直接 400。temperature、top_p、top_k、stop_sequences、max_output_tokens在托管 Agent 里全禁，不要从旧代码搬运采样配置。

后台执行强制 store=True。不落库就不能后台跑，二者互斥。落库意味着数据留存——付费层 55 天、免费层 1 天，合规敏感的数据先想清楚再开background。

环境 7 天不活跃永久删除。沙箱不是持久资产，VM 会休眠，再用时冷启动有延迟。跨周的长任务要么保活、要么把关键产物及时取出。

6. 循环外包的边界判定与统一 Key 的长期价值

回到主线问题：循环外包的边界在哪。五个维度上逐项让渡，每一样官方都留了对应的刹车。循环控制交出去了，但 Hooks 可以在远端沙箱内部同步拦截和校验code_execution与文件系统工具的执行，max_total_tokens从源头限住一次任务最多烧多少 token，Triggers 的失败熔断与超时挡住失控循环。上下文管理交出去了，但AGENTS.md能把「永远生效的规范」钉进启动指令，previous_interaction_id做多轮续接。工具注册交出去了，但调用时可用tools参数整体覆盖默认工具集。计费透明度交出去了，但max_total_tokens是预算闸，触顶时任务以incomplete状态停止。安全边界交出去了，但allowlist收紧出网、egress proxy 注入凭据、运行时轮换凭据。

判断依据收拢成三问：要不要中途介入，要就自建循环；产出是不是调研报告，是就 Deep Research；任务是否需要真实执行环境，是就托管 Agent。混用管线是官方 Best practices 背书的模式——重活脏活给 Agent，拿到 interaction ID 后用previous_interaction_id接一个普通模型调用做总结、改写、格式化，把循环外包给贵的按循环计费的部分，精细排版留给按次计费的便宜模型。

TaoToken 统一 Key 在这里的价值是长期的：一个 Key 走通 Gemini API 的调用通道，不用为每个模型、每个 Agent 单独维护凭据。托管 Agent 的调用链第一跳稳定了，后面的循环外包才有意义。想验证模型效果可以直接用模型对话，长期编码和 Agent 任务可以看 Coding Plan，接入文档和 API Keys 在控制台和文档页都能找到。

上线前最后一遍检查：allowlist已配置且只含任务必需域名；凭据为短时效 token、经 transform 注入、有轮换计划；max_total_tokens已按官方区间上限乘以安全系数设置，incomplete终态有业务处理分支；Triggers 的失败熔断与超时按任务实际时长复核；涉及代码执行的任务挂了 Hooks 做同步校验；关键产物有从环境取出的例行机制；成本预算按 2027 年牌价复核过；Human oversight 流程明确，谁在什么节点核验什么输出。