Agent visualization

Agent visualization (에이전트 시각화)

에이전트 시각화를 쓰면 Graphviz로 에이전트와 다른 에이전트·도구·MCP 서버 사이의 연결을 구조화된 그래픽 표현으로 만들 수 있어요. 애플리케이션 안에서 에이전트·도구·handoff가 어떻게 상호작용하는지 이해하는 데 유용하죠.

출처: 문서

본문

설치

선택적 viz 의존성 그룹을 설치하세요.

pip install "openai-agents[viz]"

그래프 생성하기

draw_graph 함수로 에이전트 시각화를 생성할 수 있어요. 이 함수는 방향성 그래프(directed graph)를 만드는데, 여기서는:

  • 에이전트는 노란 상자로 표시돼요.
  • MCP 서버는 회색 상자로 표시돼요.
  • 도구는 초록 타원으로 표시돼요.
  • handoff는 한 에이전트에서 다른 에이전트로 가는 방향성 간선이에요.

예제 사용

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 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=[handoff(spanish_agent), handoff(english_agent)],
    tools=[get_weather],
    mcp_servers=[mcp_server],
)

draw_graph(triage_agent)

이렇게 하면 triage 에이전트의 구조와 서브에이전트·도구로의 연결을 시각적으로 표현한 그래프가 생성돼요.

draw_graph()는 handoff에 직접 제공됐거나 handoff(agent)로 등록된 대상 에이전트를 재귀적으로 확장해요. 두 형태 모두 각 대상의 도구·MCP 서버·하위 handoff를 그래프에 포함해요. 사용 가능한 대상 Agent가 없는 커스텀 Handoff는 이름 붙은 목적지만 렌더링되므로, 그 목적지 뒤의 리소스를 확장할 수는 없어요.

그래프 노드는 표시 이름이 아니라 기본 객체(에이전트·도구·MCP 서버·커스텀 handoff)로 식별돼요. 같은 이름을 공유하는 서로 다른 객체는 같은 보이는 라벨을 가진 별도의 노드로 남고, 각 간선은 해당 객체로 연결돼요.

시각화 이해하기

생성된 그래프는 다음을 포함해요.

  • 진입점을 나타내는 시작 노드(__start__)
  • 노란 채움의 사각형으로 표시된 에이전트
  • 초록 채움의 타원으로 표시된 도구
  • 회색 채움의 사각형으로 표시된 MCP 서버
  • 상호작용을 나타내는 방향성 간선:
    • 에이전트 간 handoff를 나타내는 실선 화살표
    • 도구 호출을 나타내는 점선 화살표
    • MCP 서버 호출을 나타내는 파선(대시) 화살표
  • 실행이 종료되는 지점을 나타내는 끝 노드(__end__)

Note: MCP 서버는 v0.2.8을 포함한 최근 agents 패키지 버전에서 렌더링되는데, 이 동작이 검증된 버전이에요. 시각화에서 MCP 상자가 보이지 않으면 최신 릴리스로 업그레이드하세요.

그래프 커스터마이즈

그래프 보여주기

기본적으로 draw_graph는 그래프를 인라인으로 표시해요. 별도 창에서 보려면 이렇게 쓰세요.

draw_graph(triage_agent).view()

그래프 저장하기

기본적으로 draw_graph는 그래프를 인라인으로 표시해요. 파일로 저장하려면 파일명을 지정하세요.

draw_graph(triage_agent, filename="agent_graph")

그러면 작업 디렉터리에 agent_graph.png가 생성돼요.

더 알아보기 (Learn more)