AgentCanvas

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

AgentCanvas：揭开 AI Agent 神秘面纱的交互式可视化利器

您是否曾为向客户解释 AI Agent 的复杂工作流程而烦恼？是否在追踪 AI 模型调用、工具执行及成本时感到力不从心？现在，Vstorm 开源的 AgentCanvas 工具将彻底改变这一切。AgentCanvas 是一款基于 Pydantic AI 的可视化利器，它能将接入了 Logfire 追踪的 AI Agent 运行日志，自动转化成一份生动、可交互的 HTML 流程图报告。这份报告不仅清晰展示了每一次模型调用、工具的运用、嵌套子智能体的层级关系，更能精确到 Token 消耗和实际成本，让 AI 的“大脑”一览无余。

AgentCanvas 的核心价值

AgentCanvas 的出现，旨在解决 AI Agent 可视化和成本透明化的难题。它将原本晦涩难懂的运行日志，转化为易于理解的视觉化叙事。最终输出的单个、自包含 HTML 文件，使其无需服务器即可离线查看，特别适合在向客户进行产品演示时，生动解答“AI 到底做了什么”这一关键问题。

AgentCanvas 的强大功能概览

• 直观的块状流程图：Agent 的整个运行脉络，以清晰的 用户 → Agent → 模型 → 工具 → 回答 流式结构呈现。用户可以地进行画布的平移、缩放与拖拽，深入探索每一个环节。
• 递归展示嵌套子智能体：当某个工具的执行本身又是一个的 Agent 时，AgentCanvas 会自动生成嵌套框架，支持任意深度的递归展开，完美解析复杂的多智能体系统。
• 详尽的对话记录：每一次对话交互都被成帧，侧边栏提供完整的 用户 → 助手 → 用户 → 助手 原始对话 transcript，方便回顾和分析。
• 生动的推理过程可视化：在每个模型调用节点和对话记录中，都能看到模型的“思考”摘要以及所消耗的 Reasoning Token 数量，让 AI 的决策过程更加透明。
• 精确的成本核算：借助 genai-prices 库，AgentCanvas 能够按每次模型调用和整体运行分别计算出实际的美元成本，彻底告别估算。
• 细致的 Token 用量统计：逐层展示 Input、Output 和 Reasoning Token 的数量，并提供总计，帮助用户全面了解 Token 的消耗情况。
• 深度细节面板：通过点击，用户可以穿透到每个节点的深度详情，查看 Provider、Finish Reason、Response ID、可用工具列表及其描述、输出模式、Thinking 配置等关键元数据。
• 引导式演示模式：提供自动播放和手动分步（支持空格、点击、方向键，甚至回退）两种演示模式，并配以自然语言旁白，极大地简化了向非技术人员进行产品演示的难度。
• 即时可用的单文件输出：生成的最终产物是一个的 HTML 文件，无需构建，无需部署服务器，可离线运行，方便通过邮件轻松分享。

想要加入 AI 开源项目交流？微信关注并回复“开源”，即可加入我们。

AgentCanvas 的使用指南

• 便捷安装：通过 pip 命令 pip install agentcanvas 即可一键安装。
• 配置 Logfire 读取令牌：设置环境变量 LOGFIRE_READ_TOKEN（或写入 .env 文件），以通过 Logfire Query API 读取 Agent 运行追踪数据。
• （可选）指定 Logfire 区域：如需读取欧盟区 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 的决策路径和工具调用逻辑。
• 原生支持递归架构：与其他流程图工具不同，AgentCanvas 对 Pydantic AI 的嵌套子 Agent 模式提供了原生的递归渲染能力。
• MIT 开源协议：允许用户地将其集成到内部工具链或商业项目中。

AgentCanvas 与同类竞品的深度对比

AgentCanvas 的应用场景

• 客户演示与汇报：在会议中直接展示 Agent 的完整决策流程、工具调用序列和实时成本，有效建立客户信任。
• 生产环境问题排查：通过可视化快速定位 Agent 在哪一步调用了错误的工具或出现了异常高的 Token 消耗。
• 成本审计与优化：基于精确到每次模型调用的成本数据，识别高消耗环节并优化 Prompt 或模型选择策略。
• Agent 架构文档化：将运行时的实际流程图作为技术文档或交付物，取代传统的静态架构图。
• 多智能体系统监控：在复杂的嵌套 Agent 系统中，递归可视化各层级的调用关系，避免“套娃”式的黑盒问题。