Agent 視覺化

Agent 視覺化功能可讓你使用 Graphviz 產生 agent 及其關係的結構化圖形表示。這有助於理解 agent、工具與交接（handoff）在應用程式中的互動方式。

安裝

請安裝可選的 viz 依賴套件組：

pip install "openai-agents[viz]"

產生圖形

你可以使用 draw_graph 函數來產生代理（agent）視覺化圖形。此函數會建立一個有向圖，其中：

• 代理（Agents） 以黃色方框表示。
• MCP 伺服器 以灰色方框表示。
• 工具（Tools） 以綠色橢圓表示。
• 交接（Handoffs） 以從一個代理指向另一個代理的有向邊表示。

範例用法

import os

from agents import Agent, function_tool
from agents.mcp.server import MCPServerStdio
from agents.extensions.visualization import draw_graph

@function_tool
def get_weather(city: str) -> str:
    return f"The weather in {city} is sunny."

spanish_agent = Agent(
    name="Spanish agent",
    instructions="You only speak Spanish.",
)

english_agent = Agent(
    name="English agent",
    instructions="You only speak English",
)

current_dir = os.path.dirname(os.path.abspath(__file__))
samples_dir = os.path.join(current_dir, "sample_files")
mcp_server = MCPServerStdio(
    name="Filesystem Server, via npx",
    params={
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir],
    },
)

triage_agent = Agent(
    name="Triage agent",
    instructions="Handoff to the appropriate agent based on the language of the request.",
    handoffs=[spanish_agent, english_agent],
    tools=[get_weather],
    mcp_servers=[mcp_server],
)

draw_graph(triage_agent)

這會產生一個圖形，直觀地呈現triage agent（分流代理）及其與子代理和工具的結構連結。

理解視覺化圖形

產生的圖形包含：

• 一個起始節點（__start__），表示進入點。
• 以黃色填色矩形表示的代理（agent）。
• 以綠色填色橢圓形表示的工具（tool）。
• 以灰色填色矩形表示的 MCP 伺服器。
• 指示互動關係的有向邊：
• 實線箭頭代表代理到代理（agent-to-agent）的交接。
• 虛線箭頭代表工具（tool）的調用。
• 破折線箭頭代表 MCP 伺服器的調用。
• 一個結束節點（__end__），表示執行終止的位置。

注意： MCP 伺服器會在新版的 agents 套件中顯示（已在 v0.2.8 驗證）。如果在你的視覺化圖中沒有看到 MCP 方塊，請升級到最新版本。

自訂圖形

顯示圖形

預設情況下，draw_graph 會將圖形內嵌顯示。若要在獨立視窗中顯示圖形，請寫下以下內容：

draw_graph(triage_agent).view()

儲存圖形

預設情況下，draw_graph 會將圖形以內嵌方式顯示。若要將其儲存為檔案，請指定檔案名稱：

draw_graph(triage_agent, filename="agent_graph")

這將會在工作目錄中產生 agent_graph.png。