AgentCanvas

AgentCanvas 是由 Vstorm 团队开源发布的一款专为 Pydantic AI 生态打造的可视化工具，于 2026 年 6 月 17 日正式亮相。它的核心能力是将已接入 Logfire 追踪的 AI Agent 运行日志，自动转化为一份可交互的 HTML 流程图报告，清晰展示每一次模型调用、工具执行、嵌套子智能体、Token 消耗及精确成本。输出产物为单个自包含的 HTML 文件，无需搭建任何服务器即可离线查看和分享，特别适合在向客户演示时”讲清楚 AI 到底做了什么”。该项目采用 MIT 开源协议，可自由集成到内部工具链或商业项目中，是目前 Pydantic AI 生态中唯一原生支持嵌套子 Agent 递归可视化的开源方案。 AgentCanvas

功能特点

块状流程图将 Agent 完整运行链路以 User → Agent → Model → Tools → Answer 的流式结构呈现，支持画布平移、缩放与拖拽。

嵌套子智能体递归展示是其最大亮点：当某个工具本身就是另一个 Agent 时，自动绘制嵌套框架，支持任意深度的递归展开，彻底解决”俄罗斯套娃”式黑盒问题。完整对话记录功能让每一轮对话独立成帧，侧边栏同步展示完整的 user → assistant → user 原始 transcript。

推理过程可视化会展示模型的”思考”摘要及 reasoning token 数量，附在每个模型调用节点和对话记录中。精确成本计算基于 genai-prices 库，按每次模型调用和整体运行分别计算实际美元成本。Token 用量统计逐层展示 Input / Output / Reasoning Token 数量并汇总总计。

深度详情面板支持点击穿透查看 Provider、Finish Reason、Response ID、可用工具列表及描述、输出模式、Thinking 配置等元数据。引导式演示模式支持自动播放和手动逐步（Space/点击/方向键，支持回退）两种模式，附带自然语言旁白，方便客户 Demo。最终产物为单个自包含 HTML 文件，无需构建、无需服务器、可离线运行、易于邮件发送。

优缺点

优点：零侵入可视化，无需修改现有 Agent 代码，直接读取 Logfire 已有的 OpenTelemetry GenAI spans 数据即可生成报告。生产级成本透明，基于真实 Token 数据计算精确费用，解决”AI 黑盒”和”成本不可控”两大痛点。客户沟通利器，将技术实现转化为业务语言，让非技术客户也能理解 Agent 的决策路径和工具调用逻辑。递归架构原生支持，区别于普通流程图工具，对 Pydantic AI 的嵌套子 Agent 模式有原生递归渲染能力。MIT 开源协议，可自由集成到内部工具链或商业项目中，无任何商业限制。

缺点：新生项目，社区仍在快速成长中，生态丰富度不及 OpenClaw（1000+ 预制 Skill）。学习闭环较弱，主要依赖预设规则压缩与归档，不具备 Hermes 那样的自主深度推理能力。当前主要验证集中在文本与工具调用场景，多模态（视觉/音频）能力仍在完善中。

主要应用场景

最核心的场景：在会议中直接展示 Agent 的完整决策链路、工具调用顺序和实时成本，建立客户信任。

生产环境调试：通过可视化快速定位 Agent 在哪一步调用了错误的工具或产生了异常高的 Token 消耗。

成本审计与优化：基于精确到每次模型调用的成本数据，识别高消耗环节并优化 Prompt 或模型选择。

Agent 架构文档化：将运行时的实际流程图作为技术文档或交付物，替代静态架构图。

多智能体系统监控：在复杂嵌套 Agent 系统中，递归可视化各层级调用关系，避免黑盒式运行。

如何使用

安装非常简单，执行 pip install agentcanvas 一键完成。

配置读取令牌：设置环境变量 LOGFIRE_READ_TOKEN（或写入 .env 文件），用于通过 Logfire Query API 读取 Agent 运行追踪数据；如需读取欧盟区数据，设置 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 字符串写入文件。