Agy Bridge

User → Claude Code → agy-bridge (MCP) → agy CLI → Gemini / Claude / GPT-OSS
                   ←                  ←          ←

为什么选择它而不是 claude-to-agy？

	claude-to-agy	agy-bridge
工具范围	1 个通用的 delegate_to_agy	6 个专用工具——Claude 可可靠地自行路由
模型选择	无（仅使用 agy 默认模型）	通过所有 agy models 按工具路由，并检测可用性、提供备用模型
多轮对话	无状态	会话连续性——follow_up 可续接 agy 对话，无需重新发送上下文
输出安全性	无上限	可配置的截断上限可保护 Claude 的上下文
沙盒	否	可选的 --sandbox 模式
安装	uvx（Python）	npx（Node）——无需安装

要求

• Node.js 18+
• 已安装并完成身份验证的 Antigravity CLI（agy）
• Claude Code

安装

# 1. Register the MCP server (user scope = all projects).
#    add-json bakes in a generous client-side timeout so long analyze_files /
#    delegate calls don't trip Claude Code's tool-call deadline (see Timeouts).
claude mcp add-json -s user agy-bridge \
  '{"command":"npx","args":["-y","agy-bridge"],"timeout":600000}'

# 2. Add delegation rules to your project (or ~/.claude/CLAUDE.md for global)
curl -o CLAUDE.md https://raw.githubusercontent.com/sshahzaiib/agy-bridge/main/CLAUDE.md

"timeout": 600000（10 分钟，单位为毫秒）是客户端侧工具调用的截止时间——若不设置，冷启动的 analyze_files（约 40–50 秒）或较长的 delegate 可能会触发 Claude Code 的默认超时时间，并返回 timed out waiting for response，而 agy 仍在运行。如果你的客户端不支持按服务设置 timeout，请改为设置全局环境变量 MCP_TOOL_TIMEOUT=600000。 详情以及 agy 侧的时间预算请参阅超时与取消。

工具

工具	适用场景	模型路由（优先选择第一个可用模型）
analyze_files	超过 200 行的文件、一次处理超过 3 个文件、日志、转储文件、生成的代码	Gemini 3.5 Flash (High) → Gemini 3.1 Pro (Low)
deep_search	git log/diff/blame 分析、全仓库 grep 搜索	Gemini 3.5 Flash (Medium) → (High)
web_lookup	文档、API 参考、外部/最新知识	Gemini 3.5 Flash (Medium) → (High)
adversarial_review	计划评审、设计和代码评审	Gemini 3.1 Pro (High) → Claude Opus 4.6 (Thinking) → Flash (High)
follow_up	通过 session_id 延续之前的会话——无需重新发送上下文	继承会话
delegate	其他繁重任务	Gemini 3.5 Flash (High)

所有工具都接受可选的 cwd（项目根目录）和 model（来自 agy models 的 ID 或显示名称）；系统会验证模型，并在不匹配时列出可用模型。

每条响应都以页脚结尾：

---
[agy-bridge] model: Gemini 3.5 Flash (High) | session: 1f0c…-d4 (use follow_up to continue)

模型路由

首次使用时，桥接程序会运行 agy models（在进程生命周期内缓存），并根据工具的偏好链选择第一个可用模型。如果没有可用模型，则回退到 AGY_DEFAULT_MODEL，最后使用 agy 自身的默认模型。agy 会静默忽略未知的 --model 值，因此桥接程序会预先验证名称，而不是让请求落到错误的模型上。

配额感知故障转移

agy 在打印模式下不会报告配额耗尽——它会静默地针对 429 重试，直到打印超时，然后以空输出退出并返回 0，这曾让人误以为程序一直卡住。现在，桥接程序会监视每次运行的日志文件（通过 --log-file），并在遇到 RESOURCE_EXHAUSTED (code 429) 时：

1. 立即终止 agy 进程组（无需等待超时结束），
2. 将重置时间（“Resets in 4h24m”）解析到进程内冷却注册表中，
3. 使用工具链中的下一个模型重试相同提示词，
4. 在后续所有调用中跳过仍处于冷却期的模型，直到其配额重置。

故障转移信息会标注在响应页脚中（failover: <model>: quota exhausted (resets in 4h24m)）。只有在所有候选模型都耗尽时，调用才会失败——几秒内即可失败，并列出重置时间——而不会一直卡住。

超时与取消

每个工具都有根据其任务设定的默认超时时间：web_lookup 为 120s，deep_search 为 180s，analyze_files / adversarial_review / follow_up 为 300s，delegate 为 600s。显式设置 AGY_TIMEOUT 会一次性覆盖所有默认值。若要更改单个工具的超时时间，请改为设置 AGY_TIMEOUT_<TOOL_NAME>（例如，AGY_TIMEOUT_DEEP_SEARCH=300）；单工具覆盖值优先于全局 AGY_TIMEOUT 和该工具的默认值。所有单工具变量包括 AGY_TIMEOUT_ANALYZE_FILES、AGY_TIMEOUT_DEEP_SEARCH、AGY_TIMEOUT_WEB_LOOKUP、AGY_TIMEOUT_ADVERSARIAL_REVIEW、AGY_TIMEOUT_FOLLOW_UP 和 AGY_TIMEOUT_DELEGATE。终止流程会对整个进程组依次发送 SIGTERM → SIGKILL；即使 agy 的辅助进程仍保持输出管道打开，截止时间也会触发。从 MCP 客户端取消工具调用（例如，在 Claude Code 中按 Esc）也会终止 agy 运行，而不是让其成为孤儿进程。

两层超时——请保持一致。 上述超时是 _agy 侧_的预算。MCP 客户端（Claude Code）有自己独立的_工具调用_超时；如果它短于 agy 的预算，客户端就会先放弃——你会看到 Error: timed out waiting for response（注意：agy-bridge 自身的超时提示为 agy timed out after Ns）。工作不会丢失：agy 会话会保留，因此使用返回的 session_id 调用 follow_up 即可获取结果。不过，真正的解决办法是让客户端等待的时间至少与 agy 一样长：Install 命令已经为单个服务器设置了 600000ms 的 timeout（仅作用于 agy-bridge 条目）。如果注册服务器时没有设置该值，请重新运行 Install 中的 add-json 命令，或设置全局环境变量 MCP_TOOL_TIMEOUT=600000。经验法则：客户端 timeout ≥ agy 预算。

预期延迟。 感知到的“缓慢”大多来自冷启动：会话中的首次调用会启动 agy CLI 并预热模型。对 3 个文件执行简单的 analyze_files，冷启动耗时约为 40–50s（≈46s 的实测值），同一会话后续调用耗时会缩短。首次调用如果还遇到配额 429，桥接程序在进行故障转移期间会耗时更久。因此，即使是“简单”问题，低于 ~60s 的客户端超时也会间歇性地在冷启动时触发——请设置得宽裕一些。

配置

所有选项均为可选，通过环境变量设置：

变量	默认值	说明
AGY_PATH	agy	agy 二进制文件的路径
AGY_TIMEOUT	每个工具	秒；一次性覆盖所有单工具超时时间（见上文），作为 --print-timeout 传递，并采用 15s 的终止宽限时间强制执行
AGY_TIMEOUT_<TOOL>	每个工具	秒；仅覆盖单个工具的超时时间，例如 AGY_TIMEOUT_DEEP_SEARCH=300。优先于 AGY_TIMEOUT
AGY_MAX_OUTPUT_CHARS	50000	工具输出的截断上限
AGY_DEFAULT_MODEL	未设置	没有可用链条条目时使用的备用模型
AGY_SKIP_PERMISSIONS	true	向 agy 传递 --dangerously-skip-permissions
AGY_SANDBOX	false	使用 --sandbox 运行 agy
AGY_ON_FAILURE	fallback	strict 会在工具失败错误中追加一条指令，告知调用该工具的 Agent 不要自行接手完成该工作

失败行为

该桥接始终会明确报告失败：agy 错误会作为 MCP 工具错误显示，并附上 agy 的实际 stderr；模型路由降级情况则会在响应页脚中注明。默认情况下，调用方 Agent（Claude）通常会在失败后自行完成工作——这在对话记录中清晰可见，但在长时间会话中很容易被忽略。设置 AGY_ON_FAILURE=strict，即可在每条委派错误中附加一条明确指令：“请勿自行执行此工作——向用户报告失败”，让你能够掌控何时会悄然失去 Token 节省效果。

开发

npm install
npm test           # vitest unit tests (exec mocked — no agy needed)
npm run typecheck
npm run build      # tsup → dist/index.js

贡献者

欢迎贡献——请提交 issue 或 PR。

Star 历史

许可证

MIT