openai-agents-python 智能体可视化指南用 draw_graph 与 Graphviz 绘制多智能体架构关系图【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-pythonopenai-agents-python 提供了基于Graphviz的官方可视化扩展agents.extensions.visualization可通过draw_graph()一键生成智能体Agent、工具Tool、MCP 服务器与握手Handoff之间的结构化有向图帮助开发者直观理解多智能体应用的交互拓扑。本文围绕 docs/visualization.md及韩文版 docs/ko/visualization.md展开结合源码 src/agents/extensions/visualization.py 与测试 tests/test_visualization.py完整讲解安装、图形生成、图例解读、自定义显示与保存以及底层实现原理让你读完即可为自己的多智能体应用生成可读、可保存的架构图。上图即文档示例代码的输出从__start__进入 Triage Agent实线箭头指向 Spanish/English 两个子智能体点线箭头连接get_weather工具虚线箭头连接 Filesystem MCP 服务器最终流向__end__。安装 viz 可选依赖可视化功能属于可选依赖组需要额外安装graphviz库。在项目根目录 pyproject.toml 中声明为viz [graphviz0.17]因此安装方式为pip install openai-agents[viz]如果你使用uv管理环境也可以等价地执行uv add openai-agents[viz]。安装完成后即可从agents.extensions.visualization导入绘图函数from agents.extensions.visualization import draw_graph生成关系图draw_graph 基本用法draw_graph(agent)以任意一个Agent对象为入口递归展开其tools、mcp_servers与handoffs生成一张有向图directed 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智能体它依据请求语言将任务握手给 Spanish agent 或 English agent自身挂载get_weather工具与一个基于 npx 的 Filesystem MCP 服务器。draw_graph(triage_agent)生成的可视化图即为本文开头展示的架构图。递归展开规则handoffs 的两种注册方式文档明确指出draw_graph()的展开逻辑直接传入Agent对象handoffs[spanish_agent, english_agent]通过handoff(agent)包装注册handoffs[handoff(spanish_agent), handoff(english_agent)]。两种形式都会被递归展开每个目标智能体的工具、MCP 服务器及其下游握手都会进入图中。这一点在源码_get_all_nodes/_get_all_edges中体现遍历agent.handoffs时若元素是Agent实例则直接递归若元素是Handoff实例则通过_handoff_target_agent()取出其内部保存的_agent_ref弱引用并解析出真实目标见 src/agents/extensions/visualization.py。特殊情形自定义的Handoff未持有可用目标Agent无法解析出目标对象此时图中只会渲染一个以handoff.agent_name命名的命名目的地节点无法继续展开该目的地背后的资源——因为代码层面根本没有可引用的Agent可供遍历。理解生成的可视化节点、边与图例生成的图中包含以下要素对照源码与测试断言可逐一验证要素形状填充色含义__start__椭圆浅蓝lightblue入口节点根 Agent矩形box浅黄lightyellow传入draw_graph的入口智能体子 Agent / 握手目标圆角矩形filled,rounded浅黄lightyellow被握手递归展开的智能体Tool椭圆浅绿lightgreen工具节点MCP 服务器矩形box浅灰lightgreyMCP 服务器节点__end__椭圆浅蓝lightblue执行终止节点边的类型与含义实线箭头智能体到智能体的握手handoff点线箭头dotted工具调用且为双向agent - tool与tool - agent两条边见_get_all_edges中styledotted, penwidth1.5的成对输出虚线箭头dashedMCP 服务器调用同样为双向边。另外没有配置任何 handoffs 的智能体会被一条实线边直接连接到__end__源码_get_all_edges末尾的if not agent.handoffs: ... - __end__表示该分支的执行终点而__start__只连接根智能体。关于 MCP 节点渲染的版本说明文档特别提醒MCP 服务器节点在较新的agents包版本中才会渲染官方在v0.2.8中验证过该行为。如果升级包后可视化中仍不出现 MCP 灰色方框请先确认mcp_servers参数已正确传入Agent再检查是否为最新版本。测试文件 tests/test_visualization.py 中的_assert_mcp_nodes/_assert_mcp_edges即专门断言 MCP 节点fillcolorlightgrey与虚线双向边的输出格式。自定义图形的显示与保存draw_graph()默认在 Notebook 等环境中内联显示图形返回值为graphviz.Source对象。基于该返回值可以进一步控制展示方式。在独立窗口中显示draw_graph(triage_agent).view().view()会调用 Graphviz 的默认查看器在系统独立窗口中打开渲染结果适合在脚本/CLI 场景下快速查看。保存为 PNG 文件draw_graph(triage_agent, filenameagent_graph)传入filename后会在当前工作目录下生成agent_graph.png。这一行为来自draw_graph的签名def draw_graph(agent: Agent, filename: str | None None) - graphviz.Source见 src/agents/extensions/visualization.py其内部执行graph.render(filename, formatpng, cleanupTrue)——cleanupTrue表示渲染完成后自动删除中间的 DOT 临时文件只保留最终 PNG。测试 tests/test_visualization.py 通过 mockrender验证了调用参数正是(agent_graph, png, True)。深入底层DOT 代码如何生成draw_graph并不是唯一入口agents.extensions.visualization还公开了三个可独立调用的辅助函数方便你拿到原始 DOT 文本做二次加工get_main_graph(agent) - str生成完整的 DOT 有向图源码即draw_graph的内部数据源get_all_nodes(agent, parentNone, visitedNone) - str递归生成全部节点的 DOT 声明get_all_edges(agent, parentNone, visitedNone) - str递归生成全部边的 DOT 声明。get_main_graph生成的 DOT 头部包含graph [splinestrue];、node [fontnameArial];与edge [penwidth1.5];等全局样式这些字符串在测试中被逐字断言见 tests/test_visualization.py。拿到 DOT 源码后你可以自行用 Graphviz 命令行工具渲染为 SVG、PDF 等其他格式或嵌入自己的文档流水线。节点 ID 的稳定性同名不合并多智能体应用中常出现同名智能体、工具与握手目标。如果直接用名称作为 DOT 节点 ID同名节点会被 Graphviz 合并图形就会失真。为此源码实现了_GraphNodeIds类src/agents/extensions/visualization.py每个节点以(类型前缀, id(对象))作为唯一键类型前缀包括agent、tool、mcp、handoff对于名称唯一的节点直接使用名称作为 DOT ID可读性好对于名称重复或与保留 ID__start__、__end__冲突的节点自动生成__agents_graph_类型_序号__形式的稳定 ID。对应的测试用例覆盖了同名不同类型节点必须保持 4 个独立节点tests/test_visualization.py与名称经转义后相同仍保持独立tests/test_visualization.py等边界情况。另外_escape_label()会对名称中的反斜杠、双引号与换行符进行转义避免破坏 DOT 语法。循环与去重保护若 A 握手指向 B、B 又握手指向 A直接递归会无限循环。源码通过两重机制避免visited_agents: set[int]记录已访问对象的id()同一对象只展开一次_get_all_nodes/_get_all_edges入口处的if id(agent) in visited_agents ...: return 外部可传入visited: set[str]按名称预标记get_all_nodes(agent, visited...)等函数会跳过已访问名称的子图。测试 tests/test_visualization.py 的test_cycle_detection明确验证了循环握手场景下每个节点只出现一次、双向边均保留且不会死循环。常见问题与排查建议导入draw_graph失败确认已执行pip install openai-agents[viz]graphviz是可选依赖未安装时无法导入agents.extensions.visualization。图中缺少 MCP 灰色方框先升级agents包到最新版本v0.2.8 起已验证并确认mcp_servers[mcp_server]已正确传入根智能体或任一被展开的智能体。自定义 Handoff 只显示名称、无内部结构这是设计行为——没有可用目标Agent时无法递归展开如确需展开请改用handoff(agent)或直接传入Agent。同名节点消失或连线错乱当前实现已通过稳定 ID 机制规避若你基于旧版本观察到此现象升级即可需要查看原始 DOT 时可调用get_main_graph(agent)检查节点 ID 分配。保存 PNG 失败filename只支持不带扩展名的文件名渲染格式固定为pngcleanupTrue并注意 PNG 生成在当前工作目录。小结agents.extensions.visualization为 openai-agents-python 的多智能体调试与文档化提供了零成本的架构可视化手段一条draw_graph(agent)即可呈现智能体、工具、MCP 服务器与握手之间的完整拓扑.view()与filename满足交互查看与文件保存两种场景。深入源码可以看到其在节点 ID 稳定性、循环防护、标签转义与 MCP 渲染等细节上的工程化处理相关行为均有 tests/test_visualization.py 中的测试用例背书可放心用于实际项目。更多关于 Agent 定义、握手与 MCP 的基础知识可参阅 docs/agents.md、docs/handoffs.md 与 docs/mcp.md。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
openai-agents-python 智能体可视化指南：用 draw_graph 与 Graphviz 绘制多智能体架构关系图
openai-agents-python 智能体可视化指南用 draw_graph 与 Graphviz 绘制多智能体架构关系图【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-pythonopenai-agents-python 提供了基于Graphviz的官方可视化扩展agents.extensions.visualization可通过draw_graph()一键生成智能体Agent、工具Tool、MCP 服务器与握手Handoff之间的结构化有向图帮助开发者直观理解多智能体应用的交互拓扑。本文围绕 docs/visualization.md及韩文版 docs/ko/visualization.md展开结合源码 src/agents/extensions/visualization.py 与测试 tests/test_visualization.py完整讲解安装、图形生成、图例解读、自定义显示与保存以及底层实现原理让你读完即可为自己的多智能体应用生成可读、可保存的架构图。上图即文档示例代码的输出从__start__进入 Triage Agent实线箭头指向 Spanish/English 两个子智能体点线箭头连接get_weather工具虚线箭头连接 Filesystem MCP 服务器最终流向__end__。安装 viz 可选依赖可视化功能属于可选依赖组需要额外安装graphviz库。在项目根目录 pyproject.toml 中声明为viz [graphviz0.17]因此安装方式为pip install openai-agents[viz]如果你使用uv管理环境也可以等价地执行uv add openai-agents[viz]。安装完成后即可从agents.extensions.visualization导入绘图函数from agents.extensions.visualization import draw_graph生成关系图draw_graph 基本用法draw_graph(agent)以任意一个Agent对象为入口递归展开其tools、mcp_servers与handoffs生成一张有向图directed 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智能体它依据请求语言将任务握手给 Spanish agent 或 English agent自身挂载get_weather工具与一个基于 npx 的 Filesystem MCP 服务器。draw_graph(triage_agent)生成的可视化图即为本文开头展示的架构图。递归展开规则handoffs 的两种注册方式文档明确指出draw_graph()的展开逻辑直接传入Agent对象handoffs[spanish_agent, english_agent]通过handoff(agent)包装注册handoffs[handoff(spanish_agent), handoff(english_agent)]。两种形式都会被递归展开每个目标智能体的工具、MCP 服务器及其下游握手都会进入图中。这一点在源码_get_all_nodes/_get_all_edges中体现遍历agent.handoffs时若元素是Agent实例则直接递归若元素是Handoff实例则通过_handoff_target_agent()取出其内部保存的_agent_ref弱引用并解析出真实目标见 src/agents/extensions/visualization.py。特殊情形自定义的Handoff未持有可用目标Agent无法解析出目标对象此时图中只会渲染一个以handoff.agent_name命名的命名目的地节点无法继续展开该目的地背后的资源——因为代码层面根本没有可引用的Agent可供遍历。理解生成的可视化节点、边与图例生成的图中包含以下要素对照源码与测试断言可逐一验证要素形状填充色含义__start__椭圆浅蓝lightblue入口节点根 Agent矩形box浅黄lightyellow传入draw_graph的入口智能体子 Agent / 握手目标圆角矩形filled,rounded浅黄lightyellow被握手递归展开的智能体Tool椭圆浅绿lightgreen工具节点MCP 服务器矩形box浅灰lightgreyMCP 服务器节点__end__椭圆浅蓝lightblue执行终止节点边的类型与含义实线箭头智能体到智能体的握手handoff点线箭头dotted工具调用且为双向agent - tool与tool - agent两条边见_get_all_edges中styledotted, penwidth1.5的成对输出虚线箭头dashedMCP 服务器调用同样为双向边。另外没有配置任何 handoffs 的智能体会被一条实线边直接连接到__end__源码_get_all_edges末尾的if not agent.handoffs: ... - __end__表示该分支的执行终点而__start__只连接根智能体。关于 MCP 节点渲染的版本说明文档特别提醒MCP 服务器节点在较新的agents包版本中才会渲染官方在v0.2.8中验证过该行为。如果升级包后可视化中仍不出现 MCP 灰色方框请先确认mcp_servers参数已正确传入Agent再检查是否为最新版本。测试文件 tests/test_visualization.py 中的_assert_mcp_nodes/_assert_mcp_edges即专门断言 MCP 节点fillcolorlightgrey与虚线双向边的输出格式。自定义图形的显示与保存draw_graph()默认在 Notebook 等环境中内联显示图形返回值为graphviz.Source对象。基于该返回值可以进一步控制展示方式。在独立窗口中显示draw_graph(triage_agent).view().view()会调用 Graphviz 的默认查看器在系统独立窗口中打开渲染结果适合在脚本/CLI 场景下快速查看。保存为 PNG 文件draw_graph(triage_agent, filenameagent_graph)传入filename后会在当前工作目录下生成agent_graph.png。这一行为来自draw_graph的签名def draw_graph(agent: Agent, filename: str | None None) - graphviz.Source见 src/agents/extensions/visualization.py其内部执行graph.render(filename, formatpng, cleanupTrue)——cleanupTrue表示渲染完成后自动删除中间的 DOT 临时文件只保留最终 PNG。测试 tests/test_visualization.py 通过 mockrender验证了调用参数正是(agent_graph, png, True)。深入底层DOT 代码如何生成draw_graph并不是唯一入口agents.extensions.visualization还公开了三个可独立调用的辅助函数方便你拿到原始 DOT 文本做二次加工get_main_graph(agent) - str生成完整的 DOT 有向图源码即draw_graph的内部数据源get_all_nodes(agent, parentNone, visitedNone) - str递归生成全部节点的 DOT 声明get_all_edges(agent, parentNone, visitedNone) - str递归生成全部边的 DOT 声明。get_main_graph生成的 DOT 头部包含graph [splinestrue];、node [fontnameArial];与edge [penwidth1.5];等全局样式这些字符串在测试中被逐字断言见 tests/test_visualization.py。拿到 DOT 源码后你可以自行用 Graphviz 命令行工具渲染为 SVG、PDF 等其他格式或嵌入自己的文档流水线。节点 ID 的稳定性同名不合并多智能体应用中常出现同名智能体、工具与握手目标。如果直接用名称作为 DOT 节点 ID同名节点会被 Graphviz 合并图形就会失真。为此源码实现了_GraphNodeIds类src/agents/extensions/visualization.py每个节点以(类型前缀, id(对象))作为唯一键类型前缀包括agent、tool、mcp、handoff对于名称唯一的节点直接使用名称作为 DOT ID可读性好对于名称重复或与保留 ID__start__、__end__冲突的节点自动生成__agents_graph_类型_序号__形式的稳定 ID。对应的测试用例覆盖了同名不同类型节点必须保持 4 个独立节点tests/test_visualization.py与名称经转义后相同仍保持独立tests/test_visualization.py等边界情况。另外_escape_label()会对名称中的反斜杠、双引号与换行符进行转义避免破坏 DOT 语法。循环与去重保护若 A 握手指向 B、B 又握手指向 A直接递归会无限循环。源码通过两重机制避免visited_agents: set[int]记录已访问对象的id()同一对象只展开一次_get_all_nodes/_get_all_edges入口处的if id(agent) in visited_agents ...: return 外部可传入visited: set[str]按名称预标记get_all_nodes(agent, visited...)等函数会跳过已访问名称的子图。测试 tests/test_visualization.py 的test_cycle_detection明确验证了循环握手场景下每个节点只出现一次、双向边均保留且不会死循环。常见问题与排查建议导入draw_graph失败确认已执行pip install openai-agents[viz]graphviz是可选依赖未安装时无法导入agents.extensions.visualization。图中缺少 MCP 灰色方框先升级agents包到最新版本v0.2.8 起已验证并确认mcp_servers[mcp_server]已正确传入根智能体或任一被展开的智能体。自定义 Handoff 只显示名称、无内部结构这是设计行为——没有可用目标Agent时无法递归展开如确需展开请改用handoff(agent)或直接传入Agent。同名节点消失或连线错乱当前实现已通过稳定 ID 机制规避若你基于旧版本观察到此现象升级即可需要查看原始 DOT 时可调用get_main_graph(agent)检查节点 ID 分配。保存 PNG 失败filename只支持不带扩展名的文件名渲染格式固定为pngcleanupTrue并注意 PNG 生成在当前工作目录。小结agents.extensions.visualization为 openai-agents-python 的多智能体调试与文档化提供了零成本的架构可视化手段一条draw_graph(agent)即可呈现智能体、工具、MCP 服务器与握手之间的完整拓扑.view()与filename满足交互查看与文件保存两种场景。深入源码可以看到其在节点 ID 稳定性、循环防护、标签转义与 MCP 渲染等细节上的工程化处理相关行为均有 tests/test_visualization.py 中的测试用例背书可放心用于实际项目。更多关于 Agent 定义、握手与 MCP 的基础知识可参阅 docs/agents.md、docs/handoffs.md 与 docs/mcp.md。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
