如何在Jupyter Notebook中高效调试AI智能体代码？

AI Agent在运行过程中的状态变化远比普通脚本复杂——它可能会自动选择工具、截断上下文、甚至基于概率做出不同的决策。传统的print大法很难捕捉到瞬时的内部数据，而Jupyter Notebook的单元格执行和变量持久化能力正好可以作为Agent调试的“控制台”。我们将从最基础的日志注入开始，逐步深入到断点调试和流程可视化。

在Notebook中捕获Agent的思考过程

LangChain等框架虽然提供了默认的调试输出，但在Notebook中这些日志往往会淹没在大量的单元格输出里。我们可以利用LangChain的回调机制，把关键信息定向到Notebook的输出区域，并给不同类型的信息加上颜色标记。

先定义一个简单的回调处理器，它继承自BaseCallbackHandler，专门负责在LLM调用和工具执行时打印结构化的摘要。下面的代码使用Python的rich库来实现带颜色的输出，如果你的Notebook环境没有安装rich，也可以换成普通的print语句。关键在于通过on_llm_start和on_tool_end等方法捕获时机，避免日志过于碎片化。

from langchain.callbacks.base import BaseCallbackHandler
from rich.console import Console
from rich.panel import Panel

class NotebookDebugCallback(BaseCallbackHandler):
    def __init__(self):
        self.console = Console()

    def on_llm_start(self, serialized, prompts, **kwargs):
        self.console.print(Panel.fit(
            "[bold blue]LLM 请求开始[/bold blue]n"
            f"提示词长度: {len(prompts[0]) if prompts else 0} 字符",
            border_style="blue"
        ))

    def on_llm_end(self, response, **kwargs):
        content = response.generations[0][0].text
        self.console.print(Panel.fit(
            f"[bold green]LLM 返回内容[/bold green]n{content[:200]}...",
            border_style="green"
        ))

    def on_tool_start(self, serialized, input_str, **kwargs):
        self.console.print(Panel.fit(
            f"[bold yellow]工具调用: {serialized['name']}[/bold yellow]n参数: {input_str}",
            border_style="yellow"
        ))

接下来在创建Agent时直接传入这个回调实例，就可以在Notebook中看到清晰的日志面板。这种“对话式”的日志风格特别适合Agent调试，因为你能一眼看出LLM的思考内容和工具执行结果之间的时间顺序。如果想把日志保存下来事后分析，还可以在回调里面增加一个文件写入逻辑，但Notebook环境本身的可视化输出已经足够快速定位大部分逻辑错误。

利用IPython调试器打断点追踪调用链

当Agent进入了某个意料之外的工具调用分支，静态的日志可能无法告诉你变量当时的具体值。这时候就需要请出Jupyter Notebook的内置调试器。在需要暂停的代码位置插入from IPython.core.debugger import set_trace 然后调用 set_trace()，就可以在单元格执行时进入交互式调试状态。

假设你的Agent在执行时会调用一个自定义的搜索工具，而这个工具在接收到某些参数时表现异常。你可以在工具函数内部加入断点：

def search_tool(query: str) -> str:
    from IPython.core.debugger import set_trace; set_trace()
    # 模拟搜索逻辑
    results = perform_search(query)
    return results[0] if results else "未找到结果"

当Agent运行到这一行代码时，Notebook会停住，并在当前单元格下方出现一个输入区域，显示 ipdb> 提示符。你可以通过 p query 打印变量，用 n 执行下一行，或 c 继续运行。这种方式比在脚本里用pdb方便得多，因为所有交互都在同一个浏览器界面完成，而且还可以随时查看之前单元格中定义的变量状态。

更进一步的技巧是结合Notebook的 %%debug 魔法命令。你可以在一个单元格顶部加上 %%debug，然后在该单元格内运行Agent的入口函数，Notebook会自动在出现异常时进入调试器，而不需要预先埋入断点。这对于复现某些偶发性的错误特别有用，因为你不需要修改原有代码，只需在调试单元格里捕获异常上下文。

用可视化图分析Agent的工具调用路径

在调试复杂的多步骤Agent时，纯文本的调用顺序可能让人眼花缭乱。我们可以借助Graphviz在Notebook中绘制出工具调用的有向图，直观地展示每一步决策分支。LangChain内置了工具调用追踪功能，通过get_openai_callback可以拿到每次调用的元数据，但要将它转换成图结构还需要一点额外的工作。

下面是一个简单的实现，它从Agent的回调记录中收集工具请求和响应，然后生成一个Mermaid图（可以用IPython.display直接渲染）。Notebook的原生Mermaid渲染支持非常好，不需要额外安装扩展。

from IPython.display import display, Markdown

def generate_tool_graph(tool_events):
    mermaid = ["graph TD"]
    for i, event in enumerate(tool_events):
        node_id = f"T{i}"
        mermaid.append(f"    {node_id}[{event['tool_name']}]")
        if 'parent_id' in event:
            mermaid.append(f"    {event['parent_id']} --> {node_id}")
    display(Markdown("```mermaidn" + "n".join(mermaid) + "n```"))

你需要在回调处理器中维护一个事件列表，每调用一个工具时记录下它的名称和由哪个动作触发。最终得到一张清晰的流程图，甚至可以看到Agent在哪些步骤出现了循环调用或者错误的选择。这对于分析ReAct类型的Agent特别有帮助，因为这类Agent经常需要多次调用工具才能得到最终答案，路径可视化可以让你瞬间发现不合理的绕路行为。

流式输出与Token消耗的实时监控

使用Jupyter Notebook调试Agent还有一个得天独厚的优势：它完美支持流式输出。你可以利用 StreamingStdOutCallbackHandler 或自己实现的回调，让LLM生成的文本像打字机一样实时显示在单元格输出区域。这不仅对调试有益，也能让你直观感受到Agent的思考速度。

不过，在生产环境中我们更关心成本，因此可以在回调里增加一个简单的Token计数器。LangChain的get_openai_callback上下文管理器可以在一次调用中统计Token使用量，但将它集成到自定义回调中会更加灵活。下面是一个结合流式输出和Token统计的示例：

from langchain.callbacks.base import BaseCallbackHandler
import sys

class StreamAndCountCallback(BaseCallbackHandler):
    def __init__(self):
        self.total_tokens = 0
        _current_content = ""

    def on_llm_new_token(self, token: str, **kwargs):
        sys.stdout.write(token)  # Notebook会实时显示
        self.total_tokens += 1

    def on_llm_end(self, response, **kwargs):
        # 补充完整Token统计（gpt-4等返回的response可能包含实际token数）
        if hasattr(response, "llm_output") and response.llm_output:
            usage = response.llm_output.get("token_usage", {})
            self.total_tokens = usage.get("total_tokens", self.total_tokens)
        print(f"n[本次调用共消耗 {self.total_tokens} tokens]")

将该回调传入Agent后，在Notebook中执行Agent时就能看到文本一路生成出来，调用结束后立刻显示Token消耗。这个小小的改进能帮助你评估不同Prompt设计或工具选择对成本的冲击，尤其适合在调试阶段控制预算。

Jupyter Notebook强大的交互能力和可视化生态，使得调试AI智能体不再是一件枯燥的排错苦差。通过定制化日志、交互式断点以及调用路径图，你可以像解剖一样逐层理解Agent的行为，并在问题萌芽时就将其扼杀在开发阶段。

AI_Agent调试Jupyter_Notebook智能体开发修改时间：2026-08-12 19:48:48