openai-agents-python 智能体可视化指南用 Graphviz 绘制 Agent、工具与 MCP 服务器关系图【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python本文介绍 openai-agents-python 框架内置的智能体可视化能力。通过可选的viz依赖与draw_graph函数你可以用 Graphviz 把 Agent 及其 handoffs任务转移、工具tools和 MCP 服务器之间的连接关系自动渲染成结构化有向图用于快速理解多智能体应用的拓扑结构。读完本文你将掌握可视化功能的安装方式、draw_graph的完整用法、图中各节点与连线的图例含义以及底层 DOT 生成管线的实现原理。什么是智能体可视化在多智能体应用中一个入口 Agent 往往同时持有多个工具、挂载多个 MCP 服务器并通过 handoffs 将任务转交给下游子智能体。随着规模增长仅靠阅读代码很难直观把握谁连接了谁。openai-agents-python 在src/agents/extensions/visualization.py中提供了基于Graphviz的可视化扩展能够自动发现指定 Agent 的tools、mcp_servers与handoffs递归展开 handoff 目标 Agent 及其下游资源生成带起始/结束节点的有向图directed graph以不同形状与颜色区分节点类型以不同线型区分交互类型。该扩展属于agents包的可选能力核心入口是draw_graph函数。安装 viz 依赖可视化功能依赖graphviz库需要安装可选的viz依赖组pip install openai-agents[viz]从pyproject.toml的依赖声明可以看到该依赖组对应graphviz0.17viz [graphviz0.17]此外Graphviz 本身是独立于 Python 包的系统级工具。若需要将图形渲染/保存为文件请确保运行环境中已安装 Graphviz 的 dot 可执行程序通常由系统包管理器提供如apt install graphviz或brew install graphviz。生成智能体关系图使用draw_graph(agent)即可为指定的入口 Agent 生成可视化。该函数会创建一个有向图其中**智能体Agent**以黄色方框表示MCP 服务器以灰色方框表示**工具Tool**以绿色椭圆表示**Handoffs任务转移**以从一个智能体指向另一个智能体的有向边表示。完整示例下面的示例来自官方文档的经典用法构造一个分诊triage智能体它持有get_weather工具、挂载一个文件系统 MCP 服务器并通过handoff()注册了两个子智能体西班牙语、英语最后调用draw_graph输出整张关系图import os from agents import Agent, handoff from agents.decorators import tool from agents.mcp.server import MCPServerStdio from agents.extensions.visualization import draw_graph tool def get_weather(city: str) - str: return fThe weather in {city} is sunny. spanish_agent Agent( nameSpanish agent, instructionsYou only speak Spanish., ) english_agent Agent( nameEnglish agent, instructionsYou only speak English, ) current_dir os.path.dirname(os.path.abspath(__file__)) samples_dir os.path.join(current_dir, sample_files) mcp_server MCPServerStdio( nameFilesystem Server, via npx, params{ command: npx, args: [-y, modelcontextprotocol/server-filesystem, samples_dir], }, ) triage_agent Agent( nameTriage agent, instructionsHandoff to the appropriate agent based on the language of the request., handoffs[handoff(spanish_agent), handoff(english_agent)], tools[get_weather], mcp_servers[mcp_server], ) draw_graph(triage_agent)运行后会生成一张展示Triage agent结构及其与子智能体、工具和 MCP 服务器连接关系的图形。默认情况下图形在 Jupyter/Notebook 等支持内联渲染的环境中直接展示。递归展开规则draw_graph()会递归展开直接放在handoffs列表中的Agent对象以及通过handoff(agent)工厂函数注册的Handoff对象。无论哪种形式图中都会包含每个目标的工具、MCP 服务器和下游 handoffs。需要特别注意的是如果使用自定义Handoff且其内部没有可恢复的目标Agent引用则该 handoff 只会被渲染为一个具名目标节点使用agent_name作为标签无法展开该目标背后的资源。这一行为对应源码中的_handoff_target_agent函数——它通过Handoff._agent_ref弱引用见src/agents/handoffs/__init__.py尝试取回目标 Agent取不到时返回Nonedef _handoff_target_agent(handoff: Handoff) - Agent | None: Return the live Agent target for a handoff() object, if available. agent_ref handoff._agent_ref if agent_ref is None: return None target agent_ref() return target if isinstance(target, Agent) else None理解生成的可视化图draw_graph生成的图形包含以下要素与tests/test_visualization.py中断言的 DOT 输出一一对应要素形状颜色含义__start__节点椭圆ellipse浅蓝lightblue入口点执行起点Agent矩形box浅黄lightyellow智能体子智能体使用圆角矩形filled,roundedTool椭圆ellipse浅绿lightgreen工具MCP server矩形box浅灰lightgreyMCP 服务器__end__节点椭圆ellipse浅蓝lightblue执行终止点Handoff 边实线箭头—智能体之间的任务转移工具调用边点线dotted箭头—Agent 与工具之间的双向调用MCP 调用边虚线dashed箭头—Agent 与 MCP 服务器之间的双向调用连线规则在_get_all_edges中定义src/agents/extensions/visualization.py__start__指向入口 AgentAgent 与其每个工具之间生成双向点线边agent - tool与tool - agent线宽penwidth1.5Agent 与每个 MCP 服务器之间生成双向虚线边Agent 与其每个 handoff 目标之间生成实线边对于没有 handoffs 的 Agent会追加一条指向__end__的边表示执行在此终止。关于 MCP 服务器渲染的版本说明MCP 服务器节点是在较新版本的agents包中引入的官方文档在v0.2.8版本已验证该行为。如果你的可视化图中看不到 MCP 方框请将包升级到最新版本。仓库中的测试如_assert_mcp_nodes、_assert_mcp_edges明确验证了MCPServer1灰色矩形节点与 dashed 边的生成。自定义图形显示与保存在独立窗口中显示默认情况下draw_graph内联显示图形。若要在单独的窗口中打开请调用返回值的.view()方法draw_graph(triage_agent).view()这是因为draw_graph返回的是graphviz.Source对象见 draw_graph 源码可以直接调用 Graphviz 提供的.view()、.render()等标准方法。保存为 PNG 文件给draw_graph传入filename参数即可将图形保存为文件draw_graph(triage_agent, filenameagent_graph)这会在当前工作目录生成agent_graph.png。底层实现等价于graph.render(filename, formatpng, cleanupTrue)——cleanupTrue表示渲染完成后自动清理中间 DOT 文件只保留最终 PNG。深入源码DOT 生成管线了解底层实现有助于你在需要时扩展或调试可视化逻辑。可视化模块整体分为三层get_main_graph(agent)生成完整的 DOT 文本。它先声明全局图属性splinestrue平滑连线、节点字体 Arial、边宽penwidth1.5再拼接节点与边两段 DOT 代码最后闭合digraph G { ... }。get_all_nodes/get_all_edges分别递归生成节点声明与边声明。二者都接受可选的visited参数用于预先标记已访问的 Agent 名称跳过已展开过的子图。draw_graph调用get_main_graph构造graphviz.Source并根据filename决定是否渲染成 PNG。节点 ID 的冲突处理_GraphNodeIds类src/agents/extensions/visualization.py负责为每个节点分配稳定的 DOT 标识符。它用(类型, id(对象))作为内部键防止标签相同但类型不同的节点被混淆——例如一个名为shared的 Agent、一个名为shared的工具、一个名为shared的 MCP 服务器同时出现时每个节点都会获得唯一的 DOT ID自动生成形如__agents_graph_tool_0__的 ID。对应测试test_graph_keeps_different_node_types_with_the_same_name_distinct验证了 4 个同名节点拥有 4 个互不相同的 ID。标签转义_escape_label源码负责将 Agent/工具/MCP 名称安全地嵌入 Graphviz 双引号字符串先转义反斜杠再转义双引号最后把\r\n、\r、\n统一替换为\n避免名称中的特殊字符提前终止 DOT 字符串或产生畸形输出。test_names_with_quotes_and_backslashes_are_escaped与test_names_with_line_breaks_are_escaped等测试覆盖了引号、反斜杠和换行符场景。循环引用与去重_get_all_nodes与_get_all_edges内部通过visited_agents以对象id为键和visited_names双重去重既防止同一 Agent 对象被重复展开也避免同名 Agent 被误判为已访问。即使两个 Agent 相互 handoffA → B → A图也能正常生成不会死循环——test_cycle_detection验证了循环场景下每个节点只出现一次、两条边都保留。适用场景与延伸阅读智能体可视化适用于以下典型场景架构评审与调试快速确认 triage/路由 Agent 的 handoff 拓扑是否符合预期文档生成将关系图导出为 PNG 嵌入项目文档或汇报材料规模审计直观检查某个 Agent 是否意外携带了过多工具、MCP 服务器或下游子智能体。想进一步理解图中元素对应的框架概念可参考仓库中的相关文档智能体Agent基础Agent的tools、handoffs、mcp_servers等属性定义任务转移Handoffshandoff()工厂与Handoff对象的行为包括agent_name、_agent_ref弱引用的语义工具Toolstool装饰器与工具命名规则MCP 服务器MCPServerStdio的配置方式可视化模块参考draw_graph、get_main_graph、get_all_nodes、get_all_edges的完整 API 说明可视化测试用例覆盖节点类型、连线样式、转义、循环检测与同名去重等全部行为。掌握draw_graph后你可以在任何多智能体项目中一键生成清晰的拓扑图让 Agent、工具与 MCP 服务器的连接关系一目了然。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考