AgentCanvas：开源AI智能体追踪可视化工具，一键生成离线交互式执行流程图

一、AgentCanvas 是什么

先问一个问题：当你的AI智能体跑了一堆复杂逻辑，中间调用了多个工具、嵌套了好几个子智能体，最后卡住了——你该怎么办？逐行翻日志？太痛苦了。AgentCanvas 就是专为解决这个痛点而生的。

简单说，AgentCanvas 是一个开源的Python可视化工具库，基于Pydantic AI + Logfire构建。它的核心能力是：读取Logfire平台存储的OpenTelemetry标准GenAI智能体追踪日志，自动生成一个可离线使用的交互式智能体运行流程图。你可以把它想象成AI智能体的“X光机”，直接把那些看不见的执行链路变成一张清晰的图。

这个项目采用MIT开源协议，不需要部署后端服务，最终输出的是一个单文件HTML可视化页面——本地直接打开就能看，还能转发给团队成员。它面向AI智能体开发、调试、客户演示场景，能自动统计Token消耗与模型调用成本，完整还原多层嵌套子智能体、工具调用、多轮对话的全链路执行细节。换句话说，AgentCanvas 让黑盒变成白盒。

四、应用场景

AgentCanvas 到底能用在哪些地方？下面这五个场景，基本覆盖了智能体开发到交付的全流程：

1. AI Agent 开发调试
   
   开发人员定位工具调用失败、子智能体循环推理、超长Token消耗等问题时，直接查看每一步模型入参与返回结果，替代翻阅海量原始日志。效率提升不止一个量级。

2. 项目交付客户演示
   
   面向不懂代码的产品、业务、客户，使用分步导览模式可视化展示智能体完整工作逻辑，量化展示模型调用成本，让交付说服力大大提升。

3. AI 成本审计与优化
   
   批量分析智能体运行日志，快速筛选高Token、高费用执行链路，针对性精简提示词、替换低成本模型，有效降低大模型调用开支。

4. 团队协作日志复盘
   
   导出离线HTML文件分享给团队成员，无需共享Logfire账号，离线就能复现智能体完整执行流程，特别适合线上故障复盘、需求评审。

5. 自动化测试报告生成
   
   通过内置Python SDK集成到自动化测试流程，每次Agent用例执行后自动生成可视化报告，留存完整运行链路用于回归校验。

五、使用方法

使用AgentCanvas，门槛很低。从安装到出图，基本上就是几行命令的事。

5.1 环境安装

用pip一键安装：

pip install agentcanvas

项目推荐使用uv作为依赖管理工具，仓库内置的Demo可以通过uv一键安装全部示例依赖，省心不少。

5.2 环境变量配置

系统需要配置一个只读日志凭证（必填）：

export LOGFIRE_READ_TOKEN="你的Logfire只读Token"

如果需要切换Logfire服务区域，补充配置BASE_URL：

export LOGFIRE_BASE_URL="对应区域服务地址"

5.3 命令行基础操作

几个最常用的命令，看一眼就能上手：

1. 读取最新一条追踪，自动生成并打开可视化页面

agentcanvas

2. 查看全部历史追踪记录列表，获取Trace ID

agentcanvas --list

3. 指定Trace ID生成对应智能体流程图

agentcanvas --trace-id 追踪ID字符串

4. 自定义导出文件名，静默导出不自动打开页面

agentcanvas -o agent_report.html --no-open

5.4 Python SDK 代码调用

如果你需要在Python项目中直接调用，可以导入核心模块，自定义日志拉取与渲染逻辑，批量生成可视化报告。这个在自动化运维、测试脚本场景下特别好用。

5.5 官方 Demo 运行

仓库assets目录内置了完整的测试智能体代码，包含多工具调用、多层嵌套子智能体、多轮对话场景。执行示例脚本会自动向Logfire写入测试追踪日志，然后再通过agentcanvas命令生成可视化样例，是上手的最佳捷径。

六、竞品对比

市面上已经有一些AI追踪可视化工具了，AgentCanvas和它们比到底好在哪？这里选了LangSmith和OpenTelemetry Jaeger GenAI面板两款主流产品，从七个维度做了对比：

产品名称	AgentCanvas	LangSmith	OpenTelemetry Jaeger GenAI 面板
开源属性	完全开源（MIT）	闭源SaaS，仅基础功能免费	开源，需自行部署Jaeger服务
底层日志平台	Logfire	LangChain自有追踪存储	通用OTel采集器，无专属日志平台
离线单HTML导出	支持，全资源内嵌	不支持，必须联网访问平台	不支持，依赖部署后的服务地址
自动模型成本核算	内置genai-prices自动计算	仅展示Token数量，无自动计费	仅展示耗时与Token，无定价库
嵌套子智能体可视化	原生递归层级展示	单层链路，多层子Agent展示混乱	仅平铺跨度，无智能体业务层级
使用门槛	轻量CLI工具，一行命令出图	仅适配LangChain框架，绑定自有SDK	需运维部署采集器、存储、可视化服务
客户演示导览模式	内置分步讲解功能	无专属演示模式	无业务导向演示功能

可以说，AgentCanvas 在离线能力、嵌套层级可视化、使用门槛和开源自由度上，形成了明显的差异化优势。

七、常见问题解答

这里整理了几个大家最常问的问题，一次性说清楚：

A：核心日志标准是OpenTelemetry GenAI规范。只要你的智能体能生成符合该标准的追踪并上报至Logfire，就能用AgentCanvas。Pydantic AI是原生适配框架，无需手动埋点；其他框架需要自行完成OTel GenAI埋点上报。

A：READ_TOKEN只有日志读取权限，安全性更高，是AgentCanvas运行的必需凭证。WRITE_TOKEN用于向Logfire写入追踪日志，仅在运行Demo生成测试数据时需要。可视化流程不需要写入权限，不建议混用。

A：有三种可能。第一，导出过程中断导致文件损坏，重新执行agentcanvas命令即可。第二，浏览器本地文件安全策略限制，换Chrome、Edge主流浏览器打开。第三，Trace ID不存在或日志已过期，先用agentcanvas --list确认追踪记录有效。

A：当前版本数据源仅支持Logfire API读取云端存储的OTel追踪日志，暂无本地日志文件解析功能。所有智能体运行数据必须先上报Logfire平台。

A：genai-prices采用公开标准定价计算，但部分厂商的阶梯定价、活动折扣、私有部署定制价无法自动识别。这个数值作为成本参考完全够用，但不能完全等同于服务商的实际账单金额。

A：项目开源，前端静态资源存放在仓库assets目录，你可以自行修改CSS、JS代码后本地重新打包渲染。CLI暂未提供可视化样式自定义参数，需要修改源码进行二次开发。

八、相关链接

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

九、总结

AgentCanvas 是一款轻量化、开源且专门适配Logfire与Pydantic AI的智能体追踪可视化工具。它依托标准OpenTelemetry日志数据，构建出交互式离线画布，完美补齐了AI Agent开发流程中执行链路不透明、成本难以直观统计、演示素材难以分享的短板。相比同类工具，它有一键生成离线HTML、原生支持多层嵌套子智能体、内置自动计费、低使用门槛等差异化优势，同时提供命令行与Python SDK两种调用方式，兼顾个人开发者的快速调试与企业自动化报告场景。MIT开源协议降低了二次改造与商用的限制，可以说，它是面向大模型智能体开发、复盘、客户交付场景的一个非常实用的轻量化可视化解决方案。