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

AgentCanvas是什么

AgentCanvas到底是什么？简单说，它是Vstorm开源的一款专为Pydantic AI打造的可视化工具。只要你的Agent接入了Logfire追踪，它就能把运行日志自动转化成一份可交互的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文件，无需构建、无需服务器、可离线运行、方便邮件发送，省心。

如何使用AgentCanvas

• 安装工具
  ：一行命令搞定：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 ，对某一次特定运行生成流程图。

• 自定义输出文件名
  ：执行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的定位，这里把它和两个常见的竞品——LangSmith、Phoenix（Arize）——放在一起做了个横向对比：

对比维度	AgentCanvas	LangSmith	Phoenix (Arize)
核心定位	Pydantic AI专用可视化报告生成	LangChain生态全链路追踪与评估	多框架LLM可观测性与评估
可视化形式	单文件交互式HTML流程图（可离线）	在线Web平台（需登录）	在线Web平台（需登录）
成本展示	✅ 精确到每次调用的美元成本	⚠️ Token统计，成本需额外配置	⚠️ Token统计，成本需额外配置
嵌套Agent支持	✅ 原生递归渲染	⚠️ 支持但非专门优化	⚠️ 支持但非专门优化
部署方式	本地CLI工具，输出单HTML	SaaS平台 + 本地SDK	SaaS平台 + 本地SDK
开源协议	MIT	部分开源（LangSmith闭源）	Apache 2.0
Pydantic AI原生	✅ 深度集成	⚠️ 通用兼容	⚠️ 通用兼容
演示模式	✅ 自动导览 + 手动逐步	❌ 无	❌ 无

AgentCanvas的应用场景

• 客户Demo与汇报
  ：在会议中直接展示Agent的完整决策链路、工具调用顺序和实时成本，让客户看到具体细节，信任感自然就建立起来了。

• 生产环境调试
  ：通过可视化快速定位Agent在哪一步调用了错误的工具、或者产生了异常高的Token消耗，定位问题效率提升一个台阶。

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

• Agent架构文档化
  ：把运行时的实际流程图作为技术文档或交付物，比静态架构图更真实、更有说服力。

• 多智能体系统监控
  ：在复杂的嵌套Agent系统中，递归可视化各层级调用关系，避免“俄罗斯套娃”式的黑盒，系统运行状态一览无余。