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

一、AgentCanvas 是什么

AgentCanvas 是开源 Python 可视化工具库，基于 Pydantic AI + Logfire 构建，核心能力是读取 Logfire 平台存储的 OpenTelemetry 标准 GenAI 智能体追踪日志，自动生成可离线使用的交互式智能体运行流程图，解决大模型 Agent 执行链路黑盒问题。

项目采用 MIT 开源协议，无需部署后端服务，最终输出单文件 HTML 可视化页面，支持本地打开、转发分享，专门面向 AI 智能体开发、调试、客户演示场景，自动统计 Token 消耗与模型调用成本，完整还原多层嵌套子智能体、工具调用、多轮对话全链路执行细节。

二、功能特色

1. 交互式智能体画布可视化
   支持缩放、拖拽画布，完整还原用户提问、主智能体、模型推理、工具调用、嵌套子智能体多层递归结构，每一步执行节点独立展示，层级关系清晰直观。

2. 全维度对话与追踪详情面板
   侧边栏完整留存全部多轮对话上下文；点击任意执行节点，弹窗展示模型厂商、调用耗时、响应ID、终止原因、工具参数、系统提示词等原始追踪数据。

3. 自动 Token 与调用成本核算
   内置 genai-prices 计费规则库，自动统计输入 Token、输出 Token、思考 Token，精准计算单节点、全流程模型调用费用，快速定位高开销推理步骤。

4. 离线单 HTML 文件导出
   所有前端资源内嵌至单个 HTML 文件，无需联网、无需后端服务，本地双击即可打开，支持直接发送给同事、客户做演示。

5. 演示导览分步讲解模式
   内置手动/自动分步播放功能，配合流程旁白，无需人工讲解，适合会议、项目交付向非技术人员展示 Agent 运行逻辑。

6. 完整命令行交互能力
   提供开箱即用 CLI 工具，支持查看历史追踪记录、指定 Trace ID 生成可视化、自定义导出路径、静默导出不自动打开页面等操作。

7. Python SDK 可编程调用
   底层封装独立解析、渲染接口，可嵌入自有项目，自动化批量生成智能体运行报告，适配自动化测试、日志巡检流程。

三、技术细节

3.1 整体技术栈

主体开发语言为 Python（占仓库代码98.6%），配套工程化工具链：uv 依赖管理、pre-commit 代码校验、Makefile 自动化脚本；前端采用原生 JS+CSS 渲染画布，无重型前端框架，保证单文件轻量化打包。

3.2 核心工作链路

Logfire OpenTelemetry GenAI 追踪数据 → Logfire Read API 拉取日志 → 日志解析器重构智能体递归树结构 → genai-pricing 成本计算模块 → HTML 静态资源打包渲染 → 输出离线可视化文件

3.3 核心模块分工

3.4 依赖与鉴权逻辑

1. 运行必备环境变量：LOGFIRE_READ_TOKEN，用于读取追踪日志只读权限；

2. 可选环境变量：LOGFIRE_BASE_URL 切换 Logfire 服务区域；

3. 示例 Demo 额外依赖：LOGFIRE_WRITE_TOKEN、OPENROUTER_API_KEY，仅用于生成测试智能体日志，非可视化核心依赖；

4. 数据标准：完全兼容 Pydantic AI 自动生成的 GenAI OpenTelemetry 追踪规范，无需手动埋点改造 Agent 代码。

四、应用场景

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

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

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

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

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

五、使用方法

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 对比，对比维度覆盖底层依赖、离线导出、成本计算、使用门槛、开源属性：

七、常见问题解答

Q：AgentCanvas 必须搭配 Pydantic AI 才能使用吗？

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

Q：LOGFIRE_READ_TOKEN 和写入 Token 有什么区别，能混用吗？

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

Q：导出的 HTML 文件无法打开是什么原因？

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

Q：AgentCanvas 支持本地存储日志，不依赖 Logfire 云端吗？

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

Q：为什么成本计算数值和实际账单存在小幅差异？

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

Q：能否自定义画布样式、修改前端展示界面？

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

八、相关链接

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

九、总结

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