连接卡住时agno MCP 通信层从单点到多节点的调优实战【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agnoAgent 调用外部工具卡住几十秒时该先排查的往往不是模型而是通信层。本文解决一个具体问题agno 的MCPTools如何在三种 MCP 传输方式里做选择、接多个服务器时怎么保证一个挂掉不拖垮全部以及哪些超时参数值得动手调。示例取自仓库 cookbook可直接运行。 连接卡住时先定位是哪一层的问题MCPModel Context Protocol让 Agent 调用外部工具和资源的标准协议的交互模型不复杂客户端向服务器要一份工具清单之后按名字发起调用。agno 用MCPTools把一次 MCP 服务器连接封装成 Toolkit直接挂进 Agent 的tools列表即可。出问题时分层能帮你缩小排查范围。从源码看MCPTools内部大致是三层工具包层决定哪些工具暴露给模型会话层管理连接生命周期和按 Agent 运行run维度的会话缓存传输层才真正负责字节怎么传。卡住时先分清是工具没注册上工具包层、会话没建起来会话层还是数据在传输层停住了。MCP 传输方式选型stdio、sse 与 streamable-http源码里transport只接受三个值行为差异如下传输方式连接方式典型场景在 agno 中的现状stdio拉起本地子进程走标准输入输出本地工具服务器、开发调试只给command时的默认值sse长连接 HTTP服务端单向推流对接旧版服务器已标记弃用连接时会打印弃用警告streamable-httpHTTP 可流式推送新服务器的默认选择只给url时自动选它一个容易踩的细节url和transportstdio同时传MCPTools会告警并强制改写为streamable-http不会报错退出。新接入基本锁定 streamable-http 就够了。 第一步把一条连接跑通下面这段在本地起一个 stdio 子进程服务器Agent 直接调用它的文件工具参考 stdio 示例import asyncio from agno.agent import Agent from agno.tools.mcp import MCPTools async def main(): # stdioagno 负责拉起子进程并管理其生命周期 mcp_tools MCPTools( commandnpx -y modelcontextprotocol/server-filesystem /path/to/dir, ) await mcp_tools.connect() agent Agent(tools[mcp_tools]) await agent.aprint_response(列出目录下的文件, streamTrue) await mcp_tools.close() asyncio.run(main())关键参数是command它会被拆成可执行文件和参数来拉起子进程读超时走timeout_seconds默认 10 秒。streamable-http 连接与超时服务器跑在别处时换成url接入对应 streamable-http 示例from agno.tools.mcp import MCPTools mcp_tools MCPTools( transportstreamable-http, urlhttp://localhost:8000/mcp, timeout_seconds30, refresh_connectionTrue, # 每次 Agent 运行都刷新连接和工具清单 ) await mcp_tools.connect()timeout_seconds是客户端读超时而 streamable-http 的 HTTP 请求超时默认 30 秒实际生效值取两者中较小者。流式响应的超时另说streamable-http 的服务端推送内部基于 SSE 实现一次长流式输出的真正超时旋钮是sse_read_timeout默认 300 秒定义在 传输参数 里。流数据按事件逐条送达Agent 侧用streamTrue即可边收边显示不需要额外的分片参数。 第二步多服务器接入一个挂掉不拖垮全部每个服务器一个 MCPTools 实例多服务器容错在 agno 里没有做成一个聚合类而是刻意摊开一台服务器一个MCPTools实例全部传给同一个 Agent参考 多服务器示例# 两个服务器一个走 stdio一个走 streamable-http混用没问题 http_tools MCPTools( transportstreamable-http, urlhttp://localhost:8000/mcp, timeout_seconds30, ) search_tools MCPTools( commandnpx -y modelcontextprotocol/server-brave-search, env{BRAVE_API_KEY: os.getenv(BRAVE_API_KEY)}, timeout_seconds30, include_tools[brave_web_search], # 只暴露这一个工具 ) await http_tools.connect() await search_tools.connect() agent Agent(tools[http_tools, search_tools], markdownTrue)每个实例持有独立连接、独立超时、独立会话状态。某个服务器断线时失败只发生在它自己的工具调用上其余工具照常可用——这就是部分故障可容忍的落地方式不需要专门的开关。refresh_connection、动态头与会话回收两个参数直接影响多服务器场景的稳定性refresh_connectionTrue每次运行重建连接并重取工具清单服务器重启后新增的工具能被发现代价是多一次握手开销。header_provider传入一个函数按每次 Agent 运行动态生成 HTTP 认证头仅 sse / streamable-http 有效。此时MCPTools会为每个 run 建独立会话缓存 TTL 固定 300 秒过期自动回收防止多用户并发时会话串号或泄漏。顺带说明部分资料提到的stream_chunk_size、compression_level、max_connections、allow_partial_failure这类参数当前版本的MCPTools签名里没有暴露以最新源码为准。流式推送由协议层承担、连接复用靠按 run 的会话缓存、容错靠独立实例这三件事覆盖了它们对应的意图。⚙️ 第三步调参把抖动降下来把前面出现的旋钮汇总成一张表调优时对照排查参数默认值管什么timeout_seconds10 秒客户端读超时与传输层自身超时取小者生效StreamableHTTPClientParams.timeout30 秒streamable-http 的 HTTP 请求超时sse_read_timeout300 秒推送流读超时长流式响应的真正超时refresh_connectionFalse每次运行是否刷新连接与工具清单include_tools/exclude_toolsNone工具过滤直接减少进入 prompt 的工具数tool_name_prefixNone给工具名加前缀多服务器重名时防冲突header_providerNone按运行生成动态认证头会话缓存 TTL 300 秒判断顺序建议反过来排先确认是慢还是断。整体慢先看timeout_seconds10的默认值是否偏紧以及include_tools是否过滤过少导致工具清单过长偶发失败看refresh_connection是否该打开长输出中途被掐检查sse_read_timeout而不是主超时。多服务器混用时再给每个实例加tool_name_prefix避免重名工具互相覆盖。通信层调到位后剩余的性能问题基本就回到模型与业务逻辑本身了。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考