用 Agent 管理 Google Colab 云端 GPU（CLI + MCP）

用户想让你替他在 Google Colab 上开 GPU 或 TPU、跑代码、部署或微调开源模型、取回结果再释放机器，不用他打开网页手动操作。这个 Skill 把两条官方路线合在一起，按场景选：

路线	是什么	适合
Colab CLI	官方命令行工具 google-colab-cli（Apache-2.0），本机 Agent 调 colab 命令	复杂部署：传文件、SSH、挂载 Google Drive、一条命令跑完即释放
Colab 远程 MCP	Google 托管的 MCP 端点 https://colaboratory.googleapis.com/mcp（官方文档）	轻量管理：在聊天客户端里开机、执行代码、关机，不依赖本机

配套教程见 用 Agent 管 Colab 云端 GPU。

触发

用户说"用 Colab 跑""开个 GPU""在 Colab 上部署/微调这个模型""帮我租个 A100 跑一下""把这个脚本放到云端 GPU 上跑"，或者本机算力不够、需要临时 GPU/TPU。

硬性规则

1. 用完必须释放。 CLI 结束时 colab stop -s <名字>；MCP 结束时 delete_runtime。空转的机器会持续消耗计算单元。一次性任务优先用 colab run，它跑完会自动释放，脚本报错也会释放。
2. 开机前说清楚要用什么卡、大概跑多久。 计算单元是用户的钱，按卡型和时长扣。贵的卡（A100、H100）先问一句。
3. 不替用户付费。 colab pay 只打开订阅页，让用户自己决定；不要代为购买计算单元。
4. 不输出、不记录凭据。 认证令牌、Google Cloud 凭据只在本机配置里，不打印、不写进项目文件。
5. 不跑交互命令。 colab repl、colab console 不带管道输入、colab auth、colab drivemount 都需要人在终端前操作，Agent 直接跑会卡住。需要时告诉用户自己执行。
6. 卡不一定开得到。 GPU/TPU 按订阅等级和账号配额发放，开不到就降级到 T4 或 CPU，并告诉用户原因，不要反复重试。
7. 只跑用户有权使用的模型和数据。 注意开源模型的许可证和 Colab 的服务条款。

先查额度

• CLI：colab usage 显示计算单元余额和消耗速度。
• MCP：get_subscription 返回用户是免费、Pro 还是 Pro+；list_runtime_specs 列出他能申请的机型。
• 订阅了 Google AI 方案的用户，Colab 计算单元按方案每月发放（官方方案页：Plus 50、Pro 200、Ultra 1,000 或 2,000 个/月），会叠加到 Colab 余额里。能跑多少小时取决于卡型，越贵的卡每小时扣得越多。

路线一：Colab CLI

环境

• 只支持 Linux 和 macOS。Windows 原生不支持，需要在 WSL2 里用。
• CLI 跑在本机，Agent 所在的电脑必须开着。

先检查是否已安装：

colab version

没装就征得用户同意后安装：

uv tool install google-colab-cli   # 或 pip install google-colab-cli

认证（最常卡住的地方）

默认用 ADC（Application Default Credentials），适合 Agent 无人值守。需要用户在自己的终端里登录一次，四个权限范围缺一不可：

gcloud auth application-default login \
  --scopes=openid,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/colaboratory

验证：colab sessions（只读）。遇到 401/403，几乎都是凭据或权限范围不对，重新执行上面的登录即可。不要让用户跑 colab auth 来修 401：那是给 VM 内部注入 GCP 凭据的，和 CLI 本身的认证无关。

常用流程

开机要始终带 -s <名字>，否则会生成随机名，后面的命令容易对错机器。

colab new -s job --gpu L4              # 可选 T4 / L4 / G4 / H100 / A100；TPU 用 --tpu v5e1 / v6e1
colab install -s job torch transformers
colab exec -s job -f infer.py          # 读本地脚本发到远端执行，不用先上传
colab download -s job /content/out.txt ./out.txt
colab stop -s job

一次性任务（开机 → 执行 → 释放）：

colab run --gpu T4 infer.py --model Qwen/Qwen3-8B

要点：

• 同一个会话里内核状态保留，多次 colab exec 之间变量和导入都在，不用每次重装重导。
• 默认工作目录 /content，文件操作用绝对路径。
• 未识别的 --gpu 值会静默回退到 A100，写错卡名可能多花钱，先核对拼写。
• colab new 带加速器返回 400，说明账号没有这类卡的配额，改用 T4 或 CPU。
• 跑 notebook：colab exec -s job -f nb.ipynb，结果写到同目录的 nb_output.ipynb。
• 需要高内存：--high-mem（需要 Pro 或 Pro+）。
• 需要 SSH 或接 IDE：colab ssh -s job。
• 并行跑多个任务时，用 --config <路径> 隔离会话状态。
• 查问题：colab status -s job、colab log -s job -n 20。会话被回收后用 colab sessions 查看再重建。

路线二：Colab 远程 MCP

接入

端点：https://colaboratory.googleapis.com/mcp。使用前需要按 Google 官方文档在 Google Cloud 项目里启用 MCP 服务器并完成认证（启用说明、认证说明）。用自己的身份认证时，MCP 客户端拥有和用户相同的权限，操作记在用户名下。

把这个地址作为远程 MCP 服务器加进支持远程 MCP 的客户端。客户端怎么添加自定义连接器，以客户端自己的文档为准。

工具

工具	用途
get_subscription	查用户是免费、Pro 还是 Pro+
list_runtime_specs	列出可申请的机型（型号、加速器、规格）以及是否有资格
create_runtime	开一台运行时。有频率限制，优先复用 list_runtimes 里已有的
list_runtimes / get_runtime	查看已分配的运行时
create_session / list_sessions / delete_session	在同一台机器上开、查、关 Jupyter 会话，用来隔离状态
execute_code	执行 Python，返回 stdout、stderr、最后一个表达式的值和错误
delete_runtime	删除运行时并永久清掉状态

要点

• 要隔离状态，在已有运行时上 create_session，不要再开一台机器。
• execute_code 只返回文本，图片、图表不会返回；需要图就存成文件。输出过长会被截断。
• 单次流式输出上限 600 秒。长任务传一个固定的 executionId（UUID），超时后用同一个 ID 重新调用就能接回结果；不传 ID，超时后任务还在跑但接不回来。
• 收尾：小任务用 delete_session 关会话；整体结束或撞到 TOO_MANY_ACTIVE_RUNTIMES 再 delete_runtime。用户明确说不用了，就删运行时，别让它空转。

选哪条路

• 要传文件、挂 Drive、SSH、跑完整训练或部署脚本：CLI。
• 用户在手机或网页聊天里、本机没开、只想开机跑段代码再关掉：MCP。
• 两者可以混用：CLI 开的会话可以用 colab url -s <名字> 在浏览器里接管。

输出格式

1. 用了哪张卡、跑了多久、会话或运行时是否已释放。
2. 代码的关键输出，以及结果文件下载到了哪里。
3. 遇到降级（没开到想要的卡）或失败，写明原因。
4. 如果有机器没释放（用户要求保留），明确提醒它还在消耗计算单元。