本文由云软件体验技术团队李锦浩原创。

在 NextSDK 介绍文章里，我们聊了怎么用 @opentiny/next-sdk 给前端页面快速接入智能化能力------几行代码嵌进去，用户扫个二维码，手机上就能弹出一个 Remoter 对话窗口，直接用自然语言远程操控网页上的功能。效果是挺酷的，但不知道你有没有好奇过：这个对话窗口，到底是怎么跨设备、跨网络，把 AI 的指令传到网页上去执行的？

答案就是 WebAgent 。你手机上弹出的 Remoter 对话窗口和网页之间，其实并没有直连------中间隔着企业网络、防火墙，直连根本不现实。WebAgent 就是站在中间的那个"MCP 转发中枢"：网页端通过 @opentiny/next-sdk 把自己的业务能力封装成 MCP 工具，注册到 WebAgent 上；Remoter 端连上 WebAgent 后，就能拿到这些工具的列表，再结合大模型做意图理解和决策。大模型决定调用哪个工具后，调用指令通过 MCP（Model Context Protocol） 协议发给 WebAgent，WebAgent 把它原样转发到对应的网页端去执行，再把结果送回来。简单说，WebAgent 就在 Remoter 和网页之间可靠地转发 MCP 消息。

WebAgent 是什么

简单说，WebAgent 是一个 MCP 协议的代理中转服务 ，现已在 GitHub 正式开源（opentiny/web-agent）。

还记得上一篇提到的场景吗？网页端用 @opentiny/next-sdk 把业务能力注册成 MCP 工具，手机上的 Remoter 对话窗口连上大模型来调用这些工具。但问题是------网页藏在企业内网里，手机在外网，两边根本连不上。WebAgent 做的事情，就是站在中间帮它们传话。

具体点说，WebAgent 的代理中转机制（核心实现在 @opentiny/agent 的 useProxyHandles()）维护了两个连接池------一边管着所有的 Client（被控端） ，一边管着所有的 Remoter（遥控端） 。整个过程是这样的：

1. Client 连上来，注册工具 ：网页端（或任何业务系统）通过 @opentiny/next-sdk 的 WebMcpClient 建立 MCP 连接，WebAgent 负责接收并保管它暴露的所有 MCP 工具。
2. Remoter 连上来，拿到工具列表：遥控端（比如 Remoter 对话窗口、Cursor、Dify 这样的 AI 应用）通过 MCP 协议连接到 WebAgent，指定要操控哪个 Client。WebAgent 会启动一个"代理 MCP Server"，把目标 Client 的工具列表原样透传给 Remoter。
3. 调用指令双向转发：当 Remoter 端的大模型决定调用某个工具时，指令不会直接发到网页------而是先发给 WebAgent, WebAgent 再把调用请求转发给对应 Client，Client 执行完再把结果沿原路返回。

换句话说，WebAgent 就像一个 MCP 协议层面的双向快递站：Client 往这儿发工具清单，Remoter 往这儿发调用指令，WebAgent 负责认准地址、原样投递，两边全程不需要知道对方在哪。

先看一下架构图，有个全局印象：

对照架构图，核心角色的分工非常清晰：

• 左侧 --- 受控端（Client） ：网页应用、桌面应用、移动应用，通过 OpenTiny NEXT SDKs 连接到 WebAgent，把自己的业务能力注册为 MCP 工具。
• 中间 --- Web Agent Server（代理中枢） ：负责维护两端的会话连接，做 MCP 消息的双向转发------工具列表、调用请求、执行结果，全部经它中转。
• 右侧 --- 遥控端（Remoter） ：Agent Workflow（如 n8n、Dify）、IDE Copilot（如 Cursor、VSCode）、聊天对话框等 AI 应用，作为 MCP Client 连入 WebAgent，获取并调用远端业务工具。
• 上方 --- 用户：通过自然语言与 AI 应用交互，AI 理解意图后自动转化为 MCP 工具调用。

深度阅读 ：如需了解更完整的生态与逆向设计思考，推荐阅读《一场 MCP 生态的变革------详解 OpenTiny NEXT 逆向思维的技术创新》。

核心亮点

1. 三端分离：【遥控-被控】代理架构

前面提到 WebAgent 维护了两个连接池------一边是所有的 Client（被控端），一边是所有的 Remoter（遥控端）。当 Remoter 连上来时，WebAgent 会自动帮它和指定的 Client 之间搭一条消息通道：Remoter 想调什么工具，WebAgent 原样转给 Client 去执行；执行完了，结果再原样送回来。

这套设计的好处很直接：Remoter 和 Client 之间完全不需要知道对方在哪。Client 在企业内网？Remoter 在手机上？没关系，只要它们各自能连上 WebAgent 就行。大模型负责想，Client 负责干，WebAgent 负责在中间递纸条------三个角色各管各的，互不耦合。

2. 标准 MCP 协议，开箱即用

WebAgent 没有另起炉灶造私有协议------它从头到尾走的都是 MCP 标准，完整覆盖了工具调用、资源读取、提示词管理等所有 MCP 规范定义的能力。

这意味着：你不需要为了接入 WebAgent 学任何新东西。Cursor、Dify、n8n、MCP Inspector......任何支持 MCP 协议的工具，直接连上来就能用。业务端也一样，用 SDK 把自己的功能注册成 MCP 工具就行，协议握手、会话管理这些事 WebAgent 全包了。

3. 两种传输方式，不挑网络环境

实际部署中网络环境千差万别，WebAgent 因此同时支持了两种传输方式：

• Streamable HTTP：标准的 HTTP 请求响应，适合防火墙严格、不允许长连接的环境。
• SSE 长连接：服务端主动推送消息，适合需要实时响应的场景。

两种方式对上层完全透明------不管用哪种接入，中间的转发逻辑都是同一套。部署到 Nginx 后面？加一行配置就能穿透。Serverless 环境？用 Streamable HTTP 模式就行。甚至可以直接拿 MCP Inspector 连上来联调，不需要任何额外配置。

5 分钟快速上手

将 WebAgent 运行在本地只需几条命令即可启动服务。唯一的前提要求是你的本地运行环境包含 Node.js >=22 及其配套工具链：

# 1. 获取项目代码
git clone https://github.com/opentiny/web-agent.git
cd web-agent

# 2. 安装项目依赖（请使用 pnpm 管理器）
pnpm install

# 3. 启动开发模式（支持热重载）
pnpm dev

生产部署用 pnpm build && pnpm start，也可以挂 PM2 跑守护进程。

服务跑起来之后，我们用一个最典型的场景把整个流程走一遍：假设你有一个网页应用，你想让 AI 能远程调用它上面的功能。整个过程分三步------接入、确认、调用。

第一步：把你的网页应用接入 WebAgent

在你的前端项目里，用 SDK 几行代码就能把业务功能注册到 WebAgent 上：

// 业务前端/微服务作为 Client 接入，NextSDK 将自动处理底层的双向连接
import { WebMcpClient } from '@opentiny/next-sdk';

// 创建连接，把你的应用挂到 WebAgent 上
const client = new WebMcpClient({ name: 'my-app-client', version: '1.0.0' });
const { sessionId } = await client.connect({
  agent: true,
  url: 'http://localhost:3000/api/v1/webmcp/mcp',
  sessionId: 'my-client-001', // 给你的应用起个名字
});
console.log('🔗 Client 已挂载到WebAgent，Session ID:', sessionId);

第二步：确认被控端已上线

应用接入之后，可以用 curl 看一眼------你的应用是不是已经在线了：

# 看看当前有哪些被控端（Client）连着
curl http://localhost:3000/api/v1/webmcp/list

如果返回结果里能看到 my-client-001，说明你的应用已经成功挂载到 WebAgent 上了。

第三步：用 AI 远程调用你的应用

确认连接没问题后，就可以从另一端（遥控端）接入大模型，让 AI 来调你的应用了：

import { AgentModelProvider } from '@opentiny/next-sdk';

const webAgent = new AgentModelProvider({
  llmConfig: {
    apiKey: 'your-llm-api-key',
    baseURL: 'https://api.deepseek.com/v1', // 换成你的大模型地址
    providerType: 'deepseek',
  },
  mcpServers: {
    // 指向第一步接入的那个应用
    'my-mcp-server': {
      type: 'streamableHttp',
      url: 'http://localhost:3000/api/v1/webmcp/mcp?sessionId=my-client-001',
    },
  },
});

// 大模型现在能看到 my-client-001 暴露的所有工具，直接用自然语言调用
const result = await webAgent.chat({
  model: 'deepseek-ai/DeepSeek-V3',
  messages: [
    { role: 'system', content: '你是一个智能助手，可以通过工具操作业务系统。' },
    { role: 'user', content: '帮我查一下 ID 为 1001 的业务数据' },
  ],
});
console.log('🤖 执行结果:', result.text);

遥控端连接成功后，你也可以用 curl 确认它已经在线：

# 看看有哪些遥控端（Remoter）在线
curl http://localhost:3000/api/v1/webmcp/remoter

典型落地场景

上面跑通的是最基础的链路。实际业务里，WebAgent + @opentiny/next-sdk 能玩出不少花样，这里举三个比较典型的方向：

1. 跨系统自动办事------拿出差申请举个例子

出过差的人都知道这个流程有多烦：先登 OA 看差旅政策，再开携程或同程查航班酒店，然后切到报销系统估费用，最后把截图和数据搬回申请表单------光是在几个系统之间来回切就得小半天。

接入 WebAgent 之后，员工只需要在工作台的对话框里说一句："我要去深圳出差，下周二去周五回，帮我订符合标准的最早航班和离高新园最近的酒店，并提交出差申请"。剩下的事情 WebAgent 替你跑：

• 去 OA 系统查差旅政策和报销额度
• 去商旅平台挑符合标准的航班和酒店
• 把信息汇总填进审批表单，直接发起审批

原来要在好几个系统间来回跳的活儿，变成了一句话的事。（点击观看出差申请场景演示视频（官网首页视频））

2. 老系统低成本加上 AI 能力

很多企业的 ERP、工单系统里沉淀了几十上百张表单，全部重写不现实。但用 SDK 把关键操作包一层注册到 WebAgent 上，改动量其实很小。改完之后，操作员对着对话框说一句"审批流程转到第三级并抄送采购部主管"，AI 理解意图，WebAgent 把指令转给对应系统去执行------不用培训员工记菜单在哪、按钮点哪个，说句话就能办。

3. 微前端集群的统一调度入口

如果你的业务拆成了很多微前端子应用，每个子应用作为 Client 挂到 WebAgent 上之后，大模型就能一次请求同时操作多个子应用------比如一边从销售看板拉数据，一边往通知服务发消息。以前跨子应用的联动要写一堆胶水代码，现在 WebAgent 当中间人，子应用之间不需要互相知道对方的存在，通过 WebAgent 转发就能协作。

未来展望与共建邀请

目前开源出来的 WebAgent，核心的 MCP 代理转发能力已经跑通了。但说实话，这只是我们想做的事情的一小部分------既然 WebAgent 已经站在了 AI 和业务系统之间，很多事情顺着这个位置自然就能往下延伸：

• LLM 代理中转：现在遥控端要自己配大模型的 API Key 和地址，如果团队里十几个应用都要接，每个都单独管一套密钥和配额，运维起来很头疼。我们在考虑让 WebAgent 直接内置大模型的代理能力------业务端只管发请求，模型选择、密钥管理、限流熔断这些事情统一在 WebAgent 这一层搞定。
• MCP 工具的统一管理：当接入的 Client 越来越多、注册的工具越来越杂，"谁能调什么"就变成了一个实际问题。我们计划加上工具的权限控制、版本管理和可视化的管理后台，让管理员能清楚地看到当前有哪些工具在线、谁在用、调用情况怎么样。
• Agent 托管：再往后想一步------如果 WebAgent 不只是转发消息，而是能直接托管一个完整的 Agent 运行时呢？业务方定义好 Agent 的 Prompt、工具集和工作流，往 WebAgent 上一扔，它就能自己跑起来。这样业务团队连 Agent 的运行环境都不用操心了。

我们将继续打磨和探索 WebAgent 的更多可能性。

如果你正站在业务智能改造的关键节点，或被各路模型杂乱不齐的长链接交互卡住了业务节奏，我们非常诚挚地邀请你试用并打磨：

🚀 立即访问体验 WebAgent：

👉 GitHub 仓库 ：https://github.com/opentiny/web-agent （在此邀请试用并提交 Issue 反馈，也极其感谢能为这群满怀赤诚的开源工程师点上一颗 🌟 Star）

👉 WebAgent 文档 ：https://docs.opentiny.design/web-agent/guide/getting-started.html

👉 OpenTiny 官网体验 ：请移步 OpenTiny 访问关于 NEXT 智能化解决方案的完整技术蓝图。

👉 关于我们 ：https://opentiny.design/opentiny-design/about