如果你开发过基于 LLM 的 agent，大概率经历过这样的时刻：agent 的行为变得难以预测，它可能调用了错误的工具，或者在多个步骤之间反复横跳，又或者本该并行的操作却串行执行了。你打开追踪记录，看到一堆 span 和嵌套调用，虽然信息很全，但要在脑子里还原出整个执行流程，依然费劲。这时候，一张清晰的执行图往往胜过千言万语。
Opik 提供了 Agent Graphs 功能，可以把 agent 的执行流程可视化出来。它支持多种框架，包括 LangGraph、Google Agent Development Kit（ADK），也支持手动记录。有了这张图，你就能直观地看到 agent 的层次结构、执行顺序、工具调用关系以及循环结构，调试效率会大幅提升。
为什么需要 Agent Graph？
传统的追踪记录擅长展示"发生了什么"，比如每个 span 的输入输出和耗时。但当 agent 的逻辑变得复杂时，比如有多个子 agent 嵌套、条件分支、并行处理，单靠文字列表很难快速理解整体结构。这就像看一份详细的旅行日志，虽然记录了每一条路、每一个景点，但你很难一眼看出整个行程的路线图。
Agent Graph 做的就是把这本旅行日志变成一张地图。你可以看到起点、终点、中间经过哪些节点、哪些节点是并行的、哪些是循环的。对于调试来说，这能帮你快速定位问题区域。比如，你发现某个工具被调用了多次，在图上就能看到是不是有一个循环结构在反复触发它。又比如，你怀疑某个子 agent 没有被正确调用，图上一看便知。
Opik 目前支持三种方式来记录 agent 图：LangGraph、Google ADK 和手动跟踪。下面我们逐一介绍。
LangGraph：通过 OpikTracer 记录图
LangGraph 是一个流行的 agent 编排框架，它本身就使用图结构来定义工作流。Opik 的集成非常自然：你只需要在创建 OpikTracer 回调时，把编译后的图传进去就行。
python
from opik.integrations.langchain import OpikTracer
opik_tracer = OpikTracer(graph=app.get_graph(xray=True))这里 app 是你的 LangGraph 应用，app.get_graph(xray=True) 会返回图的定义。把这个 tracer 添加到 LangGraph 的配置中，Opik 就会自动记录 agent 图的定义。之后在 Opik 仪表板里，点击 trace 侧边栏的 Show Agent Graph 按钮，就能看到可视化的图。
这种方式的好处是几乎零成本。你不需要额外写代码来描述图，LangGraph 本身已经定义了结构，Opik 直接读取即可。对于已经用 LangGraph 构建的 agent，这是最省事的方案。
Google ADK：自动生成可视化
如果你用的是 Google 的 Agent Development Kit（ADK），那就更简单了。Opik 会自动为你的 agent 工作流生成可视化表示，不需要任何额外配置。你只需要按照 ADK 集成配置指南，把 OpikTracer 回调加进去，agent 图就会被自动捕获并展示。
ADK 自动生成的图会展示以下内容：
- Agent 层级和关系：哪些 agent 是父级，哪些是子级。
- 顺序执行流：步骤之间的先后顺序。
- 并行处理分支：哪些操作是同时进行的。
- 工具连接和依赖：工具如何与 agent 连接。
- 循环结构和迭代：哪里存在循环，循环了几次。
举个例子，一个简单的天气和时间查询 agent，它的执行图会清晰地显示出所有 agent 步骤、LLM 调用和工具调用。对于更复杂的多 agent 架构，自动图可视化的价值就更大了，它能让你看清嵌套的 agent 层级和复杂的执行模式。
这种"开箱即用"的体验对于 ADK 用户来说非常友好。你不需要关心图的格式，也不需要手动维护，Opik 会自动处理。
手动跟踪：用 Mermaid 定义图
如果你使用的框架不在上述之列，或者你想完全自定义 agent 图，Opik 也提供了手动记录的方式。你可以在 trace 的 metadata 中嵌入一个 Mermaid 格式的图定义。
Mermaid 是一种基于文本的图表描述语言，它可以用简单的语法画出流程图、时序图等。Opik 支持在 metadata 的 _opik_graph_definition 字段中放入 Mermaid 定义。
python
import opik
from opik import opik_context
@opik.track
def chat_agent(input: str):
# Update the current trace with the agent graph definition
opik_context.update_current_trace(
metadata={
"_opik_graph_definition": {
"format": "mermaid",
"data": "graph TD; U[User]-->A[Agent]; A-->L[LLM]; L-->A; A-->R[Answer];"
}
}
)
return "Hello, how can I help you today?"
chat_agent("Hi there!")这段代码定义了一个简单的图：用户指向 Agent，Agent 指向 LLM，LLM 指回 Agent，Agent 指向 Answer。在 Opik 仪表板中，点击 Show Agent Graph 就能看到这个图。
手动方式的好处是灵活。你可以为任何框架、任何自定义逻辑绘制图。比如你的 agent 有一个复杂的状态机，或者你想在图中标注特定的决策点，都可以通过 Mermaid 实现。缺点是需要自己维护图定义，如果 agent 逻辑变了，图也要同步更新。
三种方式的对比与选择
简单总结一下：
- LangGraph ：如果你用 LangGraph，直接用
OpikTracer(graph=app.get_graph(xray=True))，最省事。 - Google ADK：如果你用 ADK，什么都不用做，Opik 自动生成图。
- 手动跟踪：适用于其他框架，或者需要高度自定义图的场景。用 Mermaid 语法在 metadata 中定义。
从使用体验上看，ADK 最自动化，LangGraph 次之，手动方式最灵活但也最费心。你可以根据自己的技术栈和需求选择。
Agent Graph 能帮你解决什么问题？
可视化图不仅仅是为了好看，它在实际调试中有很多具体用途。
第一，快速定位异常路径。 当 agent 行为不符合预期时，图能帮你迅速找到问题出在哪个节点。比如你发现最终答案没有引用检索到的文档，在图上可以看到是不是检索节点和生成节点之间的连接断了，或者检索节点根本没有被执行。
第二，理解循环和迭代。 很多 agent 会包含循环结构，比如反复调用工具直到满足条件。在文字追踪里，循环可能表现为多个相似的 span，不容易看出边界。在图上，循环会清晰地显示出来，你还能看到循环的次数。
第三，分析并行效率。 如果 agent 有并行分支，图能告诉你哪些操作是同时进行的。如果发现本该并行的操作实际上串行了，可能意味着你的编排逻辑有问题，或者资源竞争导致效率下降。
第四，沟通和文档。 一张清晰的 agent 图是很好的文档材料。新成员加入团队时，看图比看代码更容易理解整体架构。在讨论优化方案时，图也是共同的参照物。
第五，验证修复效果。 当你修改了 agent 的逻辑后，重新运行并查看图，可以确认新的执行路径是否符合预期。比如你添加了一个新的工具节点，图上应该能看到它被正确连接。
实际使用中的一些小建议
虽然 Agent Graph 功能本身不复杂，但结合追踪数据一起看，效果更好。在 Opik 仪表板中，你可以先看图，了解整体结构，然后点击图中的节点，跳转到对应的 trace 或 span，查看详细的输入输出和耗时。这种"先宏观后微观"的调试方式，比一上来就翻 span 列表要高效得多。
另外，如果你使用手动方式，建议把图定义放在一个集中的地方，比如一个常量或配置文件，这样修改时不容易遗漏。Mermaid 语法虽然简单，但写复杂图时也容易出错，可以先用在线编辑器验证一下。
对于 LangGraph 用户，记得在每次图结构变化后，重新创建 OpikTracer 或者更新 graph 参数，确保记录的图是最新的。ADK 用户则不需要担心这个问题，Opik 会自动同步。
下一步可以探索什么？
如果你已经用上了 Agent Graph，不妨进一步了解 Opik 的其他能力。官方推荐了几个方向：
- Opik 的 50 多个集成：看看有没有适合你技术栈的框架，可以更省事地接入追踪。
- 记录追踪：深入学习如何记录 trace 和 span，包括自定义元数据、附件等。
- 评估 agent：了解如何用 Opik 对 agent 进行自动化评估，把可观测性和质量评估结合起来。
Agent 的可观测性是一个持续投入的过程。一开始你可能只需要记录基本的输入输出，随着 agent 变复杂，你会需要更细粒度的 span、更丰富的元数据，以及像 Agent Graph 这样的可视化工具。Opik 把这些能力都整合在一个平台里，让你可以逐步深入，而不必频繁切换工具。
写在最后
调试复杂的 agent 从来不是一件轻松的事。当执行路径变得曲折、嵌套层次变多时，单纯依靠文字日志会让人抓狂。Agent Graph 提供了一种直观的方式来理解 agent 的行为，它把抽象的调用关系变成了一张看得见的图。无论你用 LangGraph、Google ADK 还是自己手写框架，Opik 都提供了对应的记录方式。
如果你还没试过，建议从你当前的项目入手，把 agent 图记录打开，跑一次典型的请求，然后看看生成的图。你可能会发现一些之前没注意到的结构问题，比如多余的循环、意外的分支，或者缺失的连接。发现问题的那一刻，这张图就已经值回票价了。