数据截至 2026-08-17(上游 commit 0f23e3c9395c)

MCP Hub、Skills 与代理

本章讲三件把沙箱「接到 agent 生态」的事:MCP Hub(统一工具入口)、Skills(可复用的能力包)、代理(入站预览 + 出站)。

1. MCP Hub:把所有能力聚合成一组工具

agent 不想为「跑命令」「读文件」「开浏览器」各连一个服务。MCP Hub 的作用就是把这些聚合到一个 /mcp 端点,以标准 Model Context Protocol 暴露(website/docs/en/guide/basic/mcp.md:3-9):

The Model Context Protocol (MCP) Hub in AIO Sandbox provides a centralized interface for AI agents to access multiple services through a single endpoint.

预置的服务器(website/docs/en/guide/basic/mcp.md:13-35):

MCP 服务器	能力
Browser	网页浏览、页面交互、截图
File	文件系统操作、搜索、内容处理
Terminal	shell 命令执行、进程管理
Markitdown	文档转换、markdown 处理

协议形态: /mcp 走 streamable HTTP(website/docs/en/guide/basic/mcp.md:39-41),用标准 MCP 的 tools/call 调工具:

# 示意,基于 website/docs/en/guide/basic/mcp.md:48-66
resp = await client.post("http://localhost:8080/mcp", json={
  "method": "tools/call",
  "params": {"name": "browser_navigate", "arguments": {"url": "https://example.com"}}
})

MCP 子系统也有 REST 面。 SDK 的 mcp 子客户端(sdk/python/agent_sandbox/mcp/raw_client.py)暴露:GET v1/mcp/servers(列服务器)、GET v1/mcp/{server_name}/tools(列某服务器的工具)、POST v1/mcp/{server_name}/tools/{tool_name}(调具体工具)。这让你能在不走 MCP 协议握手的情况下,用普通 HTTP 直接枚举和调用 MCP 工具。

为什么这层重要: 同一套底层能力(browser/file/shell)既能用 /v1/... 细粒度 REST 调,也能通过 /mcp 当成「LLM 工具」调。前者给写集成代码的人,后者给 LLM 直接 function-calling。 沙箱把两种消费方式都备好了。

2. Skills:可注册的能力包

Skill 是一个自包含的「指令 + 脚本」目录,注册进沙箱后能被 agent 工作流发现并使用(website/docs/en/guide/basic/skills.md:3)。典型结构:

my-skill/
  SKILL.md          # 入口:frontmatter 元数据 + markdown 指令
  scripts/          # 重活放脚本里,别塞进 markdown
  templates/
  requirements.txt
  package.json

SKILL.md 的 frontmatter 用 name + description 描述「这技能是什么、何时用」(website/docs/en/guide/basic/skills.md:23-33)。注册、列举、读取、删除都有端点(sdk/python/agent_sandbox/skills/raw_client.py):

操作	端点
注册(已存在目录或上传 zip)	`POST v1/skills/register`
列出元数据	`GET v1/skills/metadatas`
读内容	`GET v1/skills/{name}/content`
删除	`DELETE v1/skills/{name}`

注册既可以指向沙箱内已存在的目录,也可以上传 zip 解压到目标目录(website/docs/en/guide/basic/skills.md:40-56)。最佳实践是 description 简短动作化、重代码放 scripts/ 而非 markdown、依赖显式、别在 skill 里埋密钥(website/docs/en/guide/basic/skills.md「Best Practices」)。

这是「能力即文件」的思路: 一个 skill 就是文件系统里的一个目录,沙箱把它索引成 agent 可发现的能力——和「共享文件系统」这条主线一脉相承。

3. 入站预览代理:让 agent 访问自己起的服务

这是 AIO 一个很实用的闭环:agent 在容器内起了一个 web 服务(比如 vite dev 跑在 :3000),怎么访问它?预览代理把容器内的 localhost:<port> 通过主 :8080 端口暴露出来(website/docs/en/guide/advanced/proxy-network.md「Inbound Preview Proxy」)。三种方式:

路径式:

http://localhost:8080/proxy/3000/      # 后端式服务
http://localhost:8080/absproxy/3000/   # 前端 app 需要绝对路径时用

/proxy/{port}/ 与 /absproxy/{port}/ 的区别:前端框架常假设资源在绝对路径(如 /assets/x.js),/proxy/ 的路径前缀会打乱它,这时改用 /absproxy/(website/docs/en/guide/advanced/proxy-network.md)。

请求头式:

curl -H 'x-aio-proxy-port: 3000' http://localhost:8080/

x-aio-proxy-port 用于「公共网关无法在子域里编码目标端口」的场景。文档点明一个安全细节:沙箱会把请求转发到 127.0.0.1:<port> 并在到达目标服务前剥掉这个控制头;且该头只应在可信代理层设置,不要信客户端传的值(website/docs/en/guide/advanced/proxy-network.md):

The sandbox forwards the request to 127.0.0.1:<port> and removes the control header before the request reaches the target service. Set or overwrite this header only at a trusted proxy layer; do not rely on a client-supplied value.

为什么这条闭环重要: 它让「coding agent 起一个 dev server → 用沙箱浏览器打开预览 → 截图/检查」整条链路在一个容器里跑通——又是「共享环境」的红利。

4. 出站代理:统一外发流量

反过来,容器内的浏览器 / 工具往外发请求,可以走上游 HTTP/HTTPS 代理。设 PROXY_SERVER 即可,并支持 allow/deny 列表(website/docs/en/guide/advanced/proxy-network.md「Outbound Proxy」):

docker run ... -e PROXY_SERVER=http://proxy.example.com:3128 \
  -e PROXY_EXCLUDE=localhost,127.0.0.1,.example.org \
  -e PROXY_INCLUDE=.example.com \
  ghcr.io/agent-infra/sandbox:latest

代理还能在运行时通过 REST 检查/更新(sdk/python/agent_sandbox/proxy/raw_client.py):GET v1/proxy/health、GET/PUT/DELETE v1/proxy/upstream、GET/POST v1/proxy/mappings + DELETE v1/proxy/mappings/{source}、GET v1/proxy/excludes、GET v1/proxy/diagnose。即「启动用环境变量定基线、运行时用 API 做临时映射」。

5. 边界与局限(全项目层面)

诚实说几条:

核心运行时闭源。 服务端进程编排、各子系统的内部实现不在本 repo,镜像里看不到;本系列的实现细节论断多锚在 SDK 契约与官方指南,涉及内部行为处已标注 (inferred)。
隔离边界偏粗。 所有能力共用一个容器、一个文件系统、一套权限——这是「all-in-one」的固有取舍。安全主要靠把入口锁 localhost + JWT/API-Key + 反向代理(见第 1 章),而非强进程级隔离。
「请求成功 ≠ 执行成功」。 多个子系统都强调要查返回里的 status/exit_code/执行状态,而不是只看 HTTP 码(website/docs/en/guide/basic/code.md「Error Handling」)。

6. 横向对比

在 ai-agent-reference 的 agent-runtime 区里,AIO 这套 /mcp 聚合 + Skills 包 + 预览代理 的组合,体现的是「把一台机器整体产品化给 agent」的路线:不是给单一能力做极致优化,而是把能力发现(MCP/Skills)、能力执行(shell/code/browser)、能力闭环(预览代理) 三件事在一个容器里凑齐。对照只做「代码沙箱」或只做「浏览器沙箱」的兄弟项目,AIO 用单容器共享 FS 换来跨能力的零搬运成本。

7. 代码地图

主题	文件路径	符号名
MCP REST 面	`sdk/python/agent_sandbox/mcp/raw_client.py`	`v1/mcp/servers`,`v1/mcp/{server}/tools`,`v1/mcp/{server}/tools/{tool}`
MCP Hub 概念与协议	`website/docs/en/guide/basic/mcp.md`	`/mcp`(streamable HTTP,`tools/call`)
Skills 注册/列举/读/删	`sdk/python/agent_sandbox/skills/raw_client.py`	`v1/skills/register`,`v1/skills/metadatas`,`v1/skills/{name}/content`
Skill 结构与 SKILL.md	`website/docs/en/guide/basic/skills.md`	`SKILL.md`(`name`/`description`)
入站预览代理	`website/docs/en/guide/advanced/proxy-network.md`	`/proxy/<port>/`,`/absproxy/<port>/`,`x-aio-proxy-port`
出站代理 + 运行时 API	`sdk/python/agent_sandbox/proxy/raw_client.py`	`PROXY_SERVER`,`v1/proxy/upstream`·`mappings`·`health`
markitdown 转换	`sdk/python/agent_sandbox/util/raw_client.py:23`	`convert_to_markdown`(`v1/util/convert_to_markdown`)

1. MCP Hub:把所有能力聚合成一组工具​

2. Skills:可注册的能力包​

3. 入站预览代理:让 agent 访问自己起的服务​

4. 出站代理:统一外发流量​

5. 边界与局限(全项目层面)​

6. 横向对比​

7. 代码地图​