1. 从一次工具调用失败说起Workbench 与 MCP 到底解决什么问题如果你正在用 AutoGen AgentChat 做多智能体大概率遇到过这种场景Agent 需要同时调用本地函数、浏览器、数据库、文件系统每个工具都要单独注册、单独处理返回值代码里堆满了if tool_name xxx的分支。更麻烦的是当你想接入外部工具生态时每个工具的协议都不一样光是适配层就能写一整天。AutoGen AgentChat 第 14 讲要解决的正是这个问题。Workbench是 AutoGen 提供的一层工具抽象它把一组工具打包成一个统一接口Agent 只需要调用list_tools()拿到工具清单、调用call_tool()执行具体工具返回值统一封装成ToolResult。你不再关心工具内部是本地函数还是远程服务Agent 循环逻辑保持稳定。而MCPModel Context Protocol则是把这种统一接口标准化到跨进程、跨语言的程度。MCP 服务器托管一组工具并管理状态MCP 客户端在 AutoGen 里就是McpWorkbench负责与服务器通信把工具暴露给语言模型。两者结合后你可以用同一个WorkbenchAgent类今天接 Playwright 做网页浏览明天接文件系统做本地操作Agent 代码几乎不用改。这篇面向的是已经跑通 AutoGen 基础 Agent、想进一步做多智能体工具调用的开发者。我会给出可复制的 Workbench 与 MCP 配置骨架含settings.json/config.toml示例并逐步验证 AgentChat 与 MCP 服务的连接。模型调用这一层我用的是 TaoToken 的兼容接口后面会给出具体配置。2. TaoToken 前置把模型客户端配置成可切换的底座在写 Workbench 之前先把模型客户端这层理顺。AutoGen 的OpenAIChatCompletionClient支持自定义base_url和api_key这意味着你可以把请求指向 TaoToken 的兼容端点而不必改动 Agent 逻辑。TaoToken 在这里扮演的角色是模型访问层它提供 OpenAI 兼容的 API你拿到 API Key 后把base_url指向https://taotoken.net/api模型名按平台支持的填写即可。这样做的实际好处是Workbench 和 MCP 的代码完全不用关心底层是哪个模型供应商切换模型只改配置。你需要先准备两样东西一个可用的 API Key以及确认你要用的模型名。API Key 在控制台的 API Keys 页面创建地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。创建后复制保存后面写进环境变量。模型名这块建议先在模型对话页面确认一下当前可用的模型标识避免配置里写了一个不存在的名字导致 404。模型对话入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 你可以直接在里面发一条消息确认返回正常同时页面上会显示当前使用的模型名。注意API Key 不要硬编码进代码提交到仓库。用.env文件加python-dotenv加载或者用系统环境变量。下面所有示例都按环境变量方式写。配置好之后模型客户端这层就稳定了。接下来进入 Workbench 的配置骨架。3. 可复制配置Workbench 骨架与 MCP 服务接入3.1 环境变量与 settings.json 骨架先建一个.env文件把模型访问信息放进去# .env TAOTOKEN_API_KEYsk-你的key TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELgpt-4.1-mini然后在项目根目录建一个settings.json用来集中管理 MCP 服务器和 Workbench 相关参数。这个文件不是 AutoGen 强制要求的但把配置外置后切换 MCP 服务器不用改代码{ model: { base_url: https://taotoken.net/api, model: gpt-4.1-mini, api_key_env: TAOTOKEN_API_KEY }, mcp_servers: { playwright: { transport: sse, url: http://localhost:8931/sse, description: 浏览器自动化工具集 }, filesystem: { transport: stdio, command: npx, args: [-y, modelcontextprotocol/server-filesystem, ./workspace], description: 本地文件读写工具集 } }, workbench: { context_buffer_size: 10, tool_timeout_seconds: 30 } }这里有两个 MCP 服务器示例playwright走 SSE 传输filesystem走 stdio 传输。AutoGen 的McpWorkbench支持这两种传输方式SSE 对应SseServerParamsstdio 对应StdioServerParams。如果你更习惯 TOML 格式等价的config.toml如下[model] base_url https://taotoken.net/api model gpt-4.1-mini api_key_env TAOTOKEN_API_KEY [mcp_servers.playwright] transport sse url http://localhost:8931/sse description 浏览器自动化工具集 [mcp_servers.filesystem] transport stdio command npx args [-y, modelcontextprotocol/server-filesystem, ./workspace] description 本地文件读写工具集 [workbench] context_buffer_size 10 tool_timeout_seconds 30两种格式选一种即可读取时用json.load或tomllib都行。关键是让 MCP 服务器地址、传输方式、模型信息都从配置里来代码里只做读取和组装。3.2 WorkbenchAgent 与 McpWorkbench 组装下面这段代码把配置读进来组装模型客户端和 MCP Workbench然后注册 Agent。注意McpWorkbench用异步上下文管理器启动退出时自动关闭连接import asyncio import json import os from dotenv import load_dotenv from autogen_core import AgentId, SingleThreadedAgentRuntime from autogen_core.model_context import BufferedChatCompletionContext from autogen_ext.models.openai import OpenAIChatCompletionClient from autogen_ext.tools.mcp import McpWorkbench, SseServerParams, StdioServerParams load_dotenv() with open(settings.json, r, encodingutf-8) as f: cfg json.load(f) def build_model_client(): return OpenAIChatCompletionClient( modelcfg[model][model], base_urlcfg[model][base_url], api_keyos.environ[cfg[model][api_key_env]], ) def build_mcp_params(server_cfg): if server_cfg[transport] sse: return SseServerParams(urlserver_cfg[url]) if server_cfg[transport] stdio: return StdioServerParams( commandserver_cfg[command], argsserver_cfg[args], ) raise ValueError(f不支持的传输方式: {server_cfg[transport]}) async def main(): server_cfg cfg[mcp_servers][playwright] params build_mcp_params(server_cfg) async with McpWorkbench(params) as workbench: runtime SingleThreadedAgentRuntime() await WorkbenchAgent.register( runtimeruntime, typeWebAgent, factorylambda: WorkbenchAgent( model_clientbuild_model_client(), model_contextBufferedChatCompletionContext( buffer_sizecfg[workbench][context_buffer_size] ), workbenchworkbench, ), ) runtime.start() await runtime.send_message( Message(content用浏览器打开 https://taotoken.net 并告诉我页面标题), recipientAgentId(WebAgent, default), ) await runtime.stop() if __name__ __main__: asyncio.run(main())WorkbenchAgent类本身沿用 AutoGen 官方示例的结构handle_user_message里先调模型如果返回的是FunctionCall列表就通过workbench.call_tool()执行把结果塞回上下文再调一次模型直到模型返回字符串。这个循环是 Workbench 模式的核心MCP 只是把工具来源换成了远程服务器。3.3 启动 MCP 服务器以 Playwright MCP 为例先装浏览器依赖再启动服务npx playwright install chrome npx playwright/mcplatest --port 8931启动成功后终端会输出监听地址和客户端配置片段类似Listening on http://localhost:8931 Put this in your client config: { mcpServers: { playwright: { url: http://localhost:8931/sse } } }这个http://localhost:8931/sse就是settings.json里playwright.url要填的值。如果你的客户端支持 streamable HTTP也可以用/mcp端点但 AutoGen 的SseServerParams走的是 SSE所以填/sse。4. 验证请求从工具清单到最终回复配置写完后不要直接跑完整 Agent先分三步验证出问题好定位。第一步验证模型客户端能通。单独跑一段最小请求import asyncio, os from dotenv import load_dotenv from autogen_ext.models.openai import OpenAIChatCompletionClient load_dotenv() async def check(): client OpenAIChatCompletionClient( modelgpt-4.1-mini, base_urlhttps://taotoken.net/api, api_keyos.environ[TAOTOKEN_API_KEY], ) resp await client.create(messages[{role: user, content: 回复 OK}]) print(resp.content) asyncio.run(check())如果这里报 401说明 Key 或环境变量有问题报 404说明模型名不对。这一步过了再往下。第二步验证 MCP 连接和工具清单。不调模型只启动 Workbench 并列出工具import asyncio from autogen_ext.tools.mcp import McpWorkbench, SseServerParams async def list_tools(): params SseServerParams(urlhttp://localhost:8931/sse) async with McpWorkbench(params) as wb: tools await wb.list_tools() for t in tools: print(t.name, -, t.description) asyncio.run(list_tools())正常会打印出browser_navigate、browser_click、browser_snapshot等工具名。如果这里卡住或报连接错误先确认 MCP 服务进程还在跑端口没被占用。第三步跑完整 Agent。用 3.2 的代码发一条需要工具调用的消息比如「用浏览器打开 https://taotoken.net 并告诉我页面标题」。预期输出会依次出现用户消息、函数调用请求FunctionCall带browser_navigate、函数调用结果ToolResult带页面快照、最终模型回复。看到最终回复是字符串说明整条链路通了。实测下来最容易出问题的是第二步到第三步之间工具清单能列出但call_tool超时。这通常是 MCP 服务器启动慢或浏览器首次启动耗时把tool_timeout_seconds调大一点或者先手动跑一次npx playwright install chrome把依赖装全。5. 本篇常见错排查5.1 McpWorkbench 连接被拒报错类似ConnectionRefusedError或ClientConnectorError。先确认 MCP 服务是否在监听curl http://localhost:8931/sse应该返回事件流或至少不拒绝连接。如果服务没起回到 3.3 重新启动。如果端口被占用换一个端口同时改settings.json里的 URL。5.2 工具调用返回 is_errorTrueToolResult里is_error为 True 时先看result.to_text()的内容。常见原因是参数格式不对比如browser_navigate需要{url: ...}如果模型生成的 arguments 不是合法 JSONjson.loads会抛异常。可以在call_tool外面包一层 try把原始 arguments 打出来看。5.3 模型不调用工具直接编答案如果模型返回的是字符串而不是FunctionCall列表说明它没走工具。检查两点一是create()时有没有传toolsawait workbench.list_tools()二是系统提示里有没有明确告诉模型可以使用工具。有些模型对工具调用支持较弱换一个工具调用能力强的模型会明显改善。5.4 stdio 传输的 MCP 服务器启动失败stdio 模式下command和args必须能直接执行。如果报FileNotFoundError把command换成绝对路径比如which npx的结果。另外 stdio 服务器的日志会混在 stderr 里调试时把 stderr 重定向到文件方便看启动错误。5.5 上下文膨胀导致后续请求变慢BufferedChatCompletionContext的buffer_size控制保留多少条消息。工具调用会产生大量中间消息函数调用、函数结果如果 buffer 太大每轮请求的 token 数会快速上涨。建议从 10 开始观察实际对话轮数再调。如果做长期编码或 Agent 任务可以考虑用 TaoToken 的 Coding Plan 来降低高频调用的成本入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。6. 把配置沉淀下来下一步接更多 MCP 服务Workbench 和 MCP 的价值在于你把工具接入这件事从「每个工具写一套适配」变成了「配置里加一段」。上面这套骨架跑通后接新的 MCP 服务只需要在settings.json的mcp_servers里加一项然后在代码里按名字读取对应的 params。Agent 类本身不用动。如果你还没创建 API Key先去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 建一个把.env填好。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有 base_url 和鉴权头的完整说明。想先确认模型可用性用模型对话页面发一条消息最快。长期跑编码类 Agent 的话Coding Plan 页面有套餐说明。最后留一个实操建议把settings.json里的mcp_servers做成数组而不是对象这样同一个传输方式可以配多个服务器McpWorkbench也支持同时挂多个 params。等你接了三四个 MCP 服务之后会发现 Agent 的能力边界基本取决于你配了多少工具而不是改了多少代码。
