AgentCanvas – Vstorm开源的 Pydantic AI 可视化工具

1. AgentCanvas是什么

AgentCanvas 是由 Vstorm 团队开发的一款开源 Pydantic AI 可视化工具。它能将已接入 Logfire 追踪的 AI Agent 运行日志，自动转化为一份可交互的 HTML 流程图报告，清晰展示每一次模型调用、工具执行、嵌套子智能体、Token 消耗及精确成本。输出为单个自包含 HTML 文件，无需服务器即可离线查看，特别适合在向客户演示时“讲清楚 AI 到底做了什么”。

技术定位与领域： AgentCanvas 属于 AI 可观测性（AI Observability）与 LLM 应用可视化工具领域。它专注于 Pydantic AI 框架生态，通过解析 OpenTelemetry GenAI spans 数据，将抽象的 Agent 运行日志转化为直观的交互式流程图。其独特定位在于“零侵入”和“面向演示”，并非通用调试平台，而是专注于生成可离线传播的 HTML 报告。

研发背景： Vstorm 团队长期深耕于 AI Agent 开发与可观测性领域。AgentCanvas 的诞生源于开发者在调试 Pydantic AI 嵌套 Agent 时面临的“黑盒”痛点——传统日志工具难以直观展示多层级调用关系，而通用可观测平台（如 LangSmith）又过于复杂且依赖云端。团队选择基于 Logfire 的开放追踪标准，以极简的 CLI 工具形式解决这一具体问题，体现了“小而美”的开源设计理念。

核心价值： 在 AI Agent 开发与交付过程中，开发者面临两大核心痛点：一是调试时难以快速定位工具调用链中的异常环节；二是向非技术客户演示时，无法直观展示 Agent 的“思考”过程和成本明细。AgentCanvas 通过将运行日志转化为可视化流程图，同时解决了这两个问题。它让技术团队拥有“调试的显微镜”，让商务团队拥有“演示的投影仪”，显著降低了 AI Agent 项目的沟通成本和调试时间。

技术特点： AgentCanvas 的核心技术优势在于对 Pydantic AI 嵌套子 Agent 的原生递归渲染能力，以及基于真实 Token 数据的精确成本计算。它无需修改现有 Agent 代码，仅通过读取 Logfire 已有的追踪数据即可工作，实现了真正的“零侵入”集成。输出为单文件 HTML 的设计，使其在离线环境、邮件分发、客户演示等场景中具有独特优势。

2. 主要功能

• 块状流程图： 将 Agent 完整运行链路以 User → Agent → Model → Tools → Answer 的流式结构呈现，支持画布平移、缩放与拖拽。这种流式结构直观反映了 Agent 的决策路径，让开发者一眼就能看出模型调用了哪些工具、工具返回了什么、以及最终如何生成回答。

• 嵌套子智能体递归展示： 当某个工具本身就是另一个 Agent 时，自动绘制嵌套框架，支持任意深度的递归展开。这是 AgentCanvas 区别于普通流程图工具的核心能力，它能够清晰展示复杂多智能体系统中“Agent 调用 Agent”的层级关系，避免“俄罗斯套娃”式的黑盒问题。

• 完整对话记录： 每一轮对话独立成帧，侧边栏展示完整的 user → assistant → user → assistant 原始 transcript。这对于调试多轮对话场景至关重要，开发者可以逐轮检查模型的输入输出，定位哪一轮对话出现了幻觉或错误推理。

• 推理过程可视化： 展示模型的“思考”摘要及 reasoning token 数量，附在每个模型调用节点和对话记录中。对于支持推理链的模型（如 OpenAI o1、DeepSeek-R1），这部分信息尤为宝贵，可以帮助开发者判断模型是否采用了合理的思考路径。

• 精确成本计算： 基于 genai-prices 库，按每次模型调用和整体运行分别计算实际美元成本。与仅统计 Token 数量的工具不同，AgentCanvas 直接给出精确到美分的费用，这对于控制生产环境成本和向客户报价具有直接的商业价值。

• Token 用量统计： 逐层展示 Input / Output / Reasoning Token 数量，并汇总总计。细粒度的 Token 统计有助于开发者识别哪些环节消耗了过多 Token，从而针对性地优化 Prompt 或选择更经济的模型。

• 深度详情面板： 点击穿透查看 Provider、Finish Reason、Response ID、可用工具列表及描述、输出模式、Thinking 配置等元数据。这个面板相当于 Agent 运行的“黑匣子记录仪”，为深入调试提供了丰富的信息支撑。

• 引导式演示模式： 支持自动播放和手动逐步（Space/点击/方向键，支持回退）两种模式，附带自然语言旁白，方便客户 Demo。这一功能将技术报告转化为叙事性演示，让非技术观众也能跟随 Agent 的决策路径，理解每一步操作的含义。

• 单文件自包含输出： 最终产物为单个 HTML 文件，无需构建、无需服务器、可离线运行、易于邮件发送。这种极简的输出形式彻底消除了部署和分享的障碍，一个文件即可承载完整的 Agent 运行记录。

3. 如何使用

1. 安装工具： 通过 pip 一键安装 pip install agentcanvas。要求 Python 3.10 或更高版本，建议在虚拟环境中安装以避免依赖冲突。

2. 配置读取令牌： 设置环境变量 LOGFIRE_READ_TOKEN（或写入 .env 文件），用于通过 Logfire Query API 读取 Agent 运行追踪数据。该令牌可在 Logfire 控制台的 Project Settings 中生成，需确保具有读取权限。

3. （可选）配置区域地址： 如需读取欧盟区 Logfire 数据，设置 `LOGFIRE_BASE_URL=（链接待官方发布后更新） Logfire 项目所在区域进行配置。

4. 生成最新运行报告： 执行 agentcanvas 命令，自动读取最新一次 Agent 运行记录，输出为 agent_flow.html 并在浏览器中打开。这是最常用的命令，适合快速查看最近一次调试结果。

5. 查看历史运行列表： 执行 agentcanvas --list 列出近期所有可用的运行记录。列表会显示 Trace ID、时间戳和概要信息，方便你选择特定的运行记录进行可视化。

6. 指定特定 Trace 可视化： 执行 agentcanvas --trace-id <id> 对某一次特定运行生成流程图。当需要回溯某个历史问题或对比不同版本 Agent 的行为时，这个命令非常有用。

7. 自定义输出文件名： 执行 agentcanvas -o report.html --no-open 指定输出文件名并禁止自动打开浏览器。这在自动化批量生成报告的场景中非常实用，可以将报告输出到指定目录。

8. （可选）运行示例 Agent： 在仓库目录下执行 uv sync --all-extras --prerelease=allow 和 uv run --prerelease=allow python assets/scripts/main.py 生成示例追踪数据，再执行 agentcanvas 可视化。这是快速上手的最佳方式，无需自己编写 Agent 代码即可体验完整功能。

9. 库模式集成： 在 Python 代码中导入 LogfireClient、parse_run、render_html，程序化获取 Trace 数据并渲染为 HTML 字符串写入文件。这种方式适合将 AgentCanvas 集成到 CI/CD 流程或自动化测试框架中。

4. 优缺点分析

5. 同类工具对比

选型建议： 如果你的项目基于 Pydantic AI 框架，且主要需求是生成面向客户的可视化报告和进行成本审计，AgentCanvas 是性价比最高的选择——零侵入、单文件输出、MIT 协议，功能精准匹配。特别是需要向非技术客户演示 Agent 决策链路的场景，其引导式演示模式是其他工具不具备的差异化能力。

如果你的团队使用 LangChain 生态，且需要在线调试、Prompt 管理、A/B 测试等全链路工具，LangSmith 是更全面的选择。虽然其可视化部分需要登录云端，但提供了更丰富的交互式调试能力。对于追求数据隐私、需要完全本地化部署的企业，Phoenix (Arize) 的 Apache 2.0 开源协议和自托管能力是更好的选择，但其可视化形式不如 AgentCanvas 直观且缺乏演示模式。

6. 编辑点评

AgentCanvas 在 AI 可观测性领域找到了一个精准且未被充分满足的细分市场——Pydantic AI 生态的“可视化+演示”需求。从技术创新角度看，其对嵌套子 Agent 的原生递归渲染能力，以及基于真实 Token 数据的精确成本计算，都是行业内少有的深度功能。特别是将技术报告转化为可交互的叙事性演示，这一设计思路跳出了传统调试工具的思维框架，直接面向了“让非技术人员也能理解 AI”这一更大的命题。

从实用价值来看，AgentCanvas 解决了 AI Agent 开发中两个最实际的痛点：调试时的“黑盒”问题和交付时的“沟通”问题。在商业项目中，向客户解释为什么某个 Agent 调用了三次 API、消耗了多少成本、做出了哪些决策，往往比技术实现本身更关键。AgentCanvas 恰好提供了这种“翻译”能力。其单文件 HTML 输出形式，更是将分享成本降到了零。

适用人群方面，AgentCanvas 最适合以下三类用户：一是 Pydantic AI 框架的深度使用者，尤其是构建嵌套 Agent 系统的开发者；二是需要向客户或管理层演示 AI Agent 能力的商务和技术人员；三是关注 AI 项目成本控制的运维和财务人员。对于使用其他框架（如 LangChain、CrewAI）的团队，AgentCanvas 的价值会大打折扣，因为其核心能力与 Pydantic AI 深度绑定。

未来发展潜力方面，AgentCanvas 有明确的扩展方向：支持更多追踪后端（如 OpenTelemetry 原生接口）、增加对比分析功能（对比两次运行的成本和路径差异）、提供 API 接口用于集成到内部平台等。作为 MIT 开源项目，其社区生态的成长速度将决定它能走多远。目前来看，Vstorm 团队对 Pydantic AI 生态的理解深度，为 AgentCanvas 奠定了坚实的技术基础。

7. 应用场景

• 客户 Demo 与汇报： 在会议中直接展示 Agent 的完整决策链路、工具调用顺序和实时成本，建立客户信任。通过引导式演示模式，可以逐步讲解每一步操作的含义，让非技术客户也能清晰地理解 Agent 的工作逻辑，显著提升方案通过率。

• 生产环境调试： 通过可视化快速定位 Agent 在哪一步调用了错误的工具或产生了异常高的 Token 消耗。当线上 Agent 出现异常行为时，开发者可以拉取对应的运行日志生成流程图，直观地看到问题环节，而无需逐行分析冗长的日志文件。

• 成本审计与优化： 基于精确到每次模型调用的成本数据，识别高消耗环节并优化 Prompt 或模型选择。例如，如果发现某个工具调用消耗了大量 Output Token，可以考虑调整该工具的返回格式或使用更经济的模型。AgentCanvas 的成本明细为这种优化提供了数据支撑。

• Agent 架构文档化： 将运行时的实际流程图作为技术文档或交付物，替代静态架构图。传统的架构图往往是“理想状态”的抽象表示，而 AgentCanvas 生成的流程图是“实际运行”的真实记录，作为交付物更具说服力和参考价值。

• 多智能体系统监控： 在复杂嵌套 Agent 系统中，递归可视化各层级调用关系，避免“俄罗斯套娃”式黑盒。当主 Agent 调用子 Agent，子 Agent 又调用孙 Agent 时，AgentCanvas 的嵌套框架可以清晰展示每一层级的调用细节，让开发者对整个系统的行为有全局把握。

8. 常见问题FAQ

Q：AgentCanvas 是否支持非 Pydantic AI 框架的 Agent？
A：不支持。AgentCanvas 深度依赖 Logfire 的 OpenTelemetry GenAI spans 数据格式，该格式与 Pydantic AI 的追踪实现紧密耦合。如果使用 LangChain、CrewAI 等其他框架，即使接入了 Logfire，AgentCanvas 也无法正确解析其追踪数据。建议这类用户考虑 Phoenix (Arize) 或 LangSmith。

Q：生成的 HTML 文件可以在哪些浏览器中打开？
A：AgentCanvas 生成的 HTML 文件基于标准 Web 技术（HTML5、CSS3、JavaScript），兼容主流现代浏览器，包括 Chrome、Firefox、Safari、Edge 的最新版本。但不支持 Internet Explorer。由于是自包含文件，无需网络连接即可正常查看所有交互功能。

Q：如何确保成本计算的准确性？
A：AgentCanvas 基于 genai-prices 库进行成本计算，该库维护了主流模型（如 GPT-4、Claude 3、Gemini 等）的官方定价。计算时使用 Agent 运行日志中记录的实际 Token 数量（包括 Input、Output、Reasoning Token），按照模型对应的单价进行计算。需要注意的是，如果使用了自定义模型或非公开定价的模型，需要手动更新 genai-prices 库的定价数据。

Q：AgentCanvas 能否处理长时间运行的 Agent 或大量 Token 消耗的场景？
A：可以。AgentCanvas 对单次运行的日志长度没有硬性限制，但生成的 HTML 文件大小会随着运行日志的复杂程度线性增长。对于包含数百次工具调用和大量 Token 消耗的复杂运行，生成的 HTML 文件可能达到数十 MB，在浏览器中加载和交互时可能会有轻微延迟。建议在演示前进行性能测试。

Q：是否可以将 AgentCanvas 集成到自动化测试流程中？
A：可以。AgentCanvas 提供了库模式，开发者可以在 Python 代码中导入 LogfireClient、parse_run、render_html 等模块，程序化地获取 Trace 数据并生成 HTML 报告。这使其可以无缝集成到 CI/CD 流水线中，例如在每次测试运行后自动生成可视化报告，作为测试产物的一部分。

Q：如果 Logfire 项目被删除或令牌失效，已生成的 HTML 文件还能正常查看吗？
A：可以。AgentCanvas 生成的 HTML 文件是自包含的，所有可视化数据和交互逻辑都已嵌入文件中。即使 Logfire 项目被删除、令牌失效或网络断开，已生成的 HTML 文件依然可以正常打开和查看所有内容。这也是其“单文件自包含”设计的核心优势。

9. 项目地址

• GitHub 仓库： https://github.com/vstorm-co/agentcanvas