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 系统中，递归可视化各层级调用关系，避免”俄罗斯套娃”式黑盒。