당신의 AI 에이전트가 어떻게 작동하는지 정확하게 확인하세요.

Logfire에 기록된 Pydantic AI 실행 로그를 전체 워크플로우(workflow)의 세련되고 애니메이션화된 다이어그램으로 변환합니다 — 모든 모델 호출(model call), 도구(tool), 중첩된 서브 에이전트(sub-agent), 토큰(token) 및 비용(dollar)까지 포함합니다.

기능 · 빠른 시작 · 작동 원리 · 아키텍처 · 기여하기

고객들은 "AI 에이전트"가 실제로 무엇을 하는지 이해하는 경우가 드뭅니다. 그들은 프롬프트(prompt)와 답변만을 볼 뿐 — 추론(reasoning), 도구 호출(tool calls), 서브 에이전트(sub-agents) 또는 비용을 보지 못합니다. agentcanvas는 에이전트가 이미 Logfire로 전송하는 트레이스(trace)를 읽어 회의 중에 화면에 띄울 수 있는 명확하고 인터랙티브한 블록 다이어그램으로 렌더링합니다: 이것이 질문이고, 여기 모델이 결정한 내용이며, 이것들이 실행된 도구들이고, 각 단계의 비용은 이렇고, 이것이 답변입니다.

🧩 블록 다이어그램 (Block diagram) |
전체 실행을 흐름으로 표시: 사용자(User) → 에이전트(Agent) → 모델 호출(model call) → 도구(tools) → 모델 호출(model call) → 답변(answer) 형태이며, 팬(pan) / 줌(zoom) / 드래그(drag)가 가능한 캔버스에서 제공됩니다. |
🪆 중첩된 에이전트 (Nested agents) |
도구 자체가 (자체 도구를 가진) 또 다른 에이전트인 경우, 재귀적으로 어떤 깊이까지든 중첩된 프레임으로 그려집니다. 다이어그램은 시스템과 함께 성장합니다. |
💬 전체 대화 (Full conversation) |
모든 턴(turn)은 각각의 프레임이며 순차적으로 연결됩니다. 사이드 패널에는 전체 사용자(user) → 어시스턴트(assistant) → 사용자(user) → 어시스턴트(assistant) 대화 기록이 표시됩니다. |
🧠 추론 (Reasoning) |
모델의 "생각(thinking)" 요약과 추론 토큰(reasoning-token) 수가 각 모델 호출 및 대화 기록에 표시됩니다. |
💰 정확한 비용 (Exact cost) |
genai-prices를 통해 토큰으로부터 계산된 모델 호출당 비용 및 전체 실행 비용을 제공합니다. |
🔢 토큰 사용량 (Token usage) |
단계별 및 합계 입력(input) / 출력(output) / 추론(reasoning) 토큰을 제공합니다. |
🔎 상세 정보 (Deep detail) |
제공자(Provider), 종료 사유(finish reason), 응답 ID(response id), 모델이 사용할 수 있는 도구(설명 포함), 출력 모드(output mode) 및 사고 설정(thinking config)을 클릭하여 확인할 수 있는 크기 조절 가능한 인스펙터(inspector)에서 제공합니다. |
🎬 가이드 투어 (Guided tour) |
자동 워크스루(walkthrough) 및 수동 단계 모드(Space / 클릭 / 화살표, 뒤로 가기 포함)를 제공하며, 각 모드는 고객 데모를 위해 평이한 언어로 된 내레이션이 포함됩니다. |
📦 독립형 (Self-contained) |
출력물은 단일 HTML 파일입니다 — 서버도, 빌드도 필요 없으며 오프라인에서 작동하고 전달하기 쉽습니다. |

pip install agentcanvas

LOGFIRE_READ_TOKEN을 설정하세요.

환경 변수(또는 .env 파일)에 설정한 다음, 최근 에이전트 실행(agent run)으로부터 보고서를 생성하세요:

agentcanvas # 최근 실행 결과 → agent_flow.html (브라우저에서 열림)
agentcanvas --list # 최근 실행 목록 나열
agentcanvas --trace-id <id> # 특정 실행 결과
...

또는 라이브러리로 사용할 수 있습니다:

from agentcanvas import LogfireClient, parse_run, render_html
client = LogfireClient() # LOGFIRE_READ_TOKEN을 읽어옴
trace_id = client.latest_trace_id()
...

변수	용도
LOGFIRE_READ_TOKEN	Logfire Query API를 통해 트레이스 (traces)를 읽는 데 사용 (필수)
LOGFIRE_BASE_URL	선택 사항인 리전 (region) 재설정 (기본값 US; EU: https://logfire-eu.pydantic.dev)
LOGFIRE_WRITE_TOKEN	Logfire로 텔레메트리 (telemetry)를 전송하는 예제 에이전트용
OPENROUTER_API_KEY	예제 에이전트용 (OpenRouter를 통한 모델)

이 저장소(repo)는 실행 가능한 예제(assets/scripts/main.py)를 제공합니다. 이는 5개의 도구(tools), 중첩된 서브 에이전트 (nested sub-agent), 그리고 멀티턴 대화 (multi-turn conversation)를 갖춘 사고하는 에이전트 (thinking agent)입니다. 체크아웃 후 다음을 실행하세요:

uv sync --all-extras --prerelease=allow # `demo` extra 설치
uv run --prerelease=allow python assets/scripts/main.py # Logfire에 샘플 트레이스 생성
agentcanvas # 시각화

Logfire (OpenTelemetry GenAI spans) ──query──► parser ──► payload ──render──► agent_flow.html

Pydantic AI의 인스트루멘테이션 (instrumentation)은 OpenTelemetry GenAI 스팬 (spans) (invoke_agent, chat, execute_tool)을 방출합니다. agentcanvas는 Logfire Query API (SQL + 읽기 토큰)를 통해 이를 읽고, 스팬 트리 (span tree)를 재귀적 워크플로 (turns → rounds → tools → nested agents)로 재구성하며, genai-prices를 통해 가격을 산정하고, 단일 독립형 HTML 보고서를 렌더링합니다.

모듈 (Module)	역할 (Role)
logfire_client.py	Logfire Query API 클라이언트 (SQL → 행 (rows))
parser.py	스팬 트리 (span tree) → 재귀적 페이로드 (turns, rounds, tools, nested agents)
pricing.py	genai-prices를 통한 토큰 기반의 정확한 비용 산정
render.py	페이로드 → 임베디드 HTML / CSS / JS 보고서
viz.py	CLI 진입점 (entry point)
assets/scripts/main.py	데모 에이전트 (demo agent): 사고 과정 (thinking), 5개의 도구 (tools), 중첩된 서브 에이전트 (nested sub-agent), 멀티 턴 대화 (multi-turn conversation)
assets/scripts/make_demo.py · make_screenshots.py	데모 비디오 녹화 / 문서 스크린샷 캡처

git clone https://github.com/vstorm-co/agentcanvas.git
cd agentcanvas
make install # uv sync (개발 도구 포함)
...

이 라이브러리는 완전한 타입 지정 (fully typed) 및 테스트가 완료되었습니다. PR (Pull Request)을 보내기 전에는 반드시 make all을 통과해야 합니다.

자세한 내용은 CONTRIBUTING.md를 참조하세요.

CHANGELOG.md를 참조하세요.

MIT — LICENSE를 참조하세요.