AgentCanvas – 开源Pydantic AI智能体可视化工具

AgentCanvas是Vstorm推出的开源可视化工具，基于Pydantic AI构建。工具可读取Logfire采集的AI智能体追踪日志，自动生成可交互HTML流程图报告，完整还原模型调用、工具执行、嵌套子智能体流程，同步展示Token消耗与精准计费数据。

一、AgentCanvas主要功能：

1、模块化流程图展示：

以「用户→智能体→大模型→工具→结果」完整链路绘制运行流程，画布支持平移、缩放、拖拽交互。

2、递归嵌套子智能体渲染：

识别工具内嵌套的次级Agent，自动生成分层框架，无层级限制，可自由展开折叠。

3、完整对话存档：

每轮对话独立分区，侧边栏完整留存用户与智能体原始交互文本记录。

4、推理过程可视化：

每个模型节点附带思考摘要与推理Token消耗，清晰呈现AI思考逻辑。

5、精准费用核算：

依托genai-prices价格库，单独统计单次调用成本与整条链路总消耗（美元计价）。

6、分层Token统计：

分层展示输入、输出、推理三类Token用量，并自动汇总全流程总量。

7、详情弹窗面板：

点击节点展开完整元数据，包含服务商、结束原因、响应ID、可用工具清单、输出格式、思考配置等信息。

8、演示讲解模式：

支持自动轮播、手动分步操控（空格/点击/方向键进退回放），配套文字旁白，适配客户产品演示。

9、独立单文件导出：

仅生成一份HTML文件，无需编译、无需后端服务，离线可运行，便于邮件分发传输。

二、AgentCanvas核心优势：

1、无侵入接入：

无需改动现有Agent业务代码，直接读取Logfire标准OpenTelemetry GenAI追踪链路数据。

2、成本透明可控：

基于真实Token消耗精准核算费用，破解AI运行黑盒、成本难以预估的行业痛点。

3、降低客户理解门槛：

将底层技术链路转化为直观可视化图表，非技术人员也能看懂智能体决策与工具调用逻辑。

4、原生适配嵌套Agent：

区别于通用绘图工具，原生支持Pydantic AI多层级子智能体递归渲染。

5、MIT开源协议：

开放源码，可自由集成至内部平台或商用项目，无版权约束。

三、AgentCanvas使用教程：

1、工具安装：执行pip命令一键安装

`pip install agentcanvas`

2、配置访问凭证：配置环境变量LOGFIRE_READ_TOKEN，也可写入.env文件，用于调用Logfire查询接口读取追踪日志。

3、（可选）区域切换：读取欧盟区Logfire数据时，补充环境变量

`LOGFIRE_BASE_URL=https://logfire-eu.pydantic.dev`

4、生成最新任务流程图：运行`agentcanvas`，自动拉取最近一次运行记录，输出agent_flow.html并自动唤起浏览器。

5、查看全部历史记录：`agentcanvas --list`，展示所有可渲染的运行追踪条目。

6、指定单条Trace生成报告：`agentcanvas --trace-id 追踪ID`，渲染指定单次智能体运行流程。

7、自定义输出配置：`agentcanvas -o report.html --no-open`，自定义文件名称，关闭自动浏览器打开。

8、（可选）生成测试样例：进入项目仓库目录，依次执行

uv sync --all-extras --prerelease=allow
uv run --prerelease=allow python assets/scripts/main.py

生成测试追踪数据后，再执行可视化命令预览效果。

9、代码集成调用：Python项目可直接导入LogfireClient、parse_run、render_html，代码化读取追踪数据、渲染HTML并本地保存。