AgentCanvas是什么
AgentCanvas是一款由Vstorm开源、专为Pydantic AI量身打造的可视化工具。只需你的Agent接入Logfire追踪，它就能自动将运行日志转化为一份可交互的HTML流程图报告。每一次模型调用、工具执行、嵌套子智能体、Token消耗以及精准成本，全都一目了然。最终输出的是一个独立的HTML文件，无需服务器支持，离线即可打开查看。这在给客户做演示时尤为实用——既能清晰展示“AI到底做了什么”，又无需让对方深入技术细节。
AgentCanvas的主要功能
- 块状流程图：以
User → Agent → Model → Tools → Answer的流式结构完整呈现Agent的运行链路，支持画布平移、缩放和拖拽，操作体验流畅顺手。 - 嵌套子智能体递归展示：当某个工具本身也是一个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的项目地址
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系统中，递归可视化各层级调用关系，避免“俄罗斯套娃”式的黑盒，系统运行状态一览无余。