AgentCanvas – Vstorm開源的 Pydantic AI 可視化工具

AgentCanvas是什麼

AgentCanvas 是 Vstorm開源的 Pydantic AI 可視化工具。能將已接入 Logfire 追蹤的 AI Agent 運行日誌，自動轉化爲一份可交互的 HTML 流程圖報告，清晰展示每一次模型調用、工具執行、嵌套子智能體、Token 消耗及精確成本。輸出爲單個自包含 HTML 文件，無需服務器即可離線查看，特別適合在向客戶演示時”講清楚 AI 到底做了什麼”。

AgentCanvas的主要功能

• 塊狀流程圖：將 Agent 完整運行鏈路以 User → Agent → Model → Tools → Answer 的流式結構呈現，支持畫布平移、縮放與拖拽。
• 嵌套子智能體遞歸展示：當某個工具本身就是另一個 Agent 時，自動繪製嵌套框架，支持任意深度的遞歸展開。
• 完整對話記錄：每一輪對話獨立成幀，側邊欄展示完整的 user → assistant → user → assistant 原始 transcript。
• 推理過程可視化：展示模型的”思考”摘要及 reasoning token 數量，附在每個模型調用節點和對話記錄中。
• 精確成本計算：基於 genai-prices 庫，按每次模型調用和整體運行分別計算實際美元成本。
• Token 用量統計：逐層展示 Input / Output / Reasoning Token 數量，並彙總總計。
• 深度詳情面板：點擊穿透查看 Provider、Finish Reason、Response ID、可用工具列表及描述、輸出模式、Thinking 配置等元數據。
• 引導式演示模式：支持自動播放和手動逐步（Space/點擊/方向鍵，支持回退）兩種模式，附帶自然語言旁白，方便客戶 Demo。
• 單文件自包含輸出：最終產物爲單個 HTML 文件，無需構建、無需服務器、可離線運行、易於郵件發送。

微信關注回覆 “開源”，加入AI開源項目交流羣

如何使用AgentCanvas

• 安裝工具：通過 pip 一鍵安裝 pip install agentcanvas。
• 配置讀取令牌：設置環境變量 LOGFIRE_READ_TOKEN（或寫入 .env 文件），用於通過 Logfire Query API 讀取 Agent 運行追蹤數據。
• （可選）配置區域地址：如需讀取歐盟區 Logfire 數據，設置 LOGFIRE_BASE_URL=https://logfire-eu.pydantic.dev。
• 生成最新運行報告：執行 agentcanvas 命令，自動讀取最新一次 Agent 運行記錄，輸出爲 agent_flow.html 並在瀏覽器中打開。
• 查看歷史運行列表：執行 agentcanvas --list 列出近期所有可用的運行記錄。
• 指定特定 Trace 可視化：執行 agentcanvas --trace-id <id> 對某一次特定運行生成流程圖。
• 自定義輸出文件名：執行 agentcanvas -o report.html --no-open 指定輸出文件名並禁止自動打開瀏覽器。
• （可選）運行示例 Agent：在倉庫目錄下執行 uv sync --all-extras --prerelease=allow 和 uv run --prerelease=allow python assets/scripts/main.py 生成示例追蹤數據，再執行 agentcanvas 可視化。
• 庫模式集成：在 Python 代碼中導入 LogfireClient、parse_run、render_html，程序化獲取 Trace 數據並渲染爲 HTML 字符串寫入文件。

AgentCanvas的項目地址

• Github倉庫：https://github.com/vstorm-co/agentcanvas

AgentCanvas的核心優勢

• 零侵入可視化：無需修改現有 Agent 代碼，直接讀取 Logfire 已有的 OpenTelemetry GenAI spans 數據
• 生產級成本透明：基於真實 Token 數據計算精確費用，解決”AI 黑盒”和”成本不可控”痛點
• 客戶溝通利器：將技術實現轉化爲業務語言，讓非技術客戶也能理解 Agent 的決策路徑和工具調用邏輯
• 遞歸架構原生支持：區別於普通流程圖工具，對 Pydantic AI 的嵌套子 Agent 模式有原生遞歸渲染能力
• MIT 開源協議：可自由集成到內部工具鏈或商業項目中

AgentCanvas的同類競品對比

AgentCanvas的應用場景

• 客戶 Demo 與彙報：在會議中直接展示 Agent 的完整決策鏈路、工具調用順序和實時成本，建立客戶信任。
• 生產環境調試：通過可視化快速定位 Agent 在哪一步調用了錯誤的工具或產生了異常高的 Token 消耗。
• 成本審計與優化：基於精確到每次模型調用的成本數據，識別高消耗環節並優化 Prompt 或模型選擇。
• Agent 架構文檔化：將運行時的實際流程圖作爲技術文檔或交付物，替代靜態架構圖。
• 多智能體系統監控：在複雜嵌套 Agent 系統中，遞歸可視化各層級調用關係，避免”俄羅斯套娃”式黑盒。