LangGraph 的 stream 方法在流式返回工具调用结果时,如果 stdout 被日志模块污染,问题通常不在 agent 逻辑,而在日志输出通道与流式传输通道共用了一个文件描述符。Python logging 默认的 StreamHandler 如果没有显式指定 stream,会使用 sys.stderr,但不少代码会通过 basicConfig 或自定义 handler 把日志打到 sys.stdout。LangGraph 在流式模式下需要从 stdout 读取结构化输出,日志行混入后,事件解析就会错位。处理方向不是修改 LangGraph 内部实现,而是让日志和流式数据走不同通道。
现象与检查点
典型现象是:终端里能看到工具调用结果前混入 INFO/WARNING 行;通过 pipe 或子进程读取 LangGraph 输出时 JSON 解析失败;在 stream() 迭代事件里出现日志文本;但换成非流式 invoke() 调用时一切正常。先确认三件事:日志 handler 是否绑定了 sys.stdout、LangGraph 是否真的从 stdout 取流、以及是否有第三方库的 logger 也输出到 stdout。
- 检查点 1:查看 logging 配置,确认 StreamHandler 的目标流。
- 检查点 2:在 LangGraph 调用前后用 sys.stdout.fileno() 重定向测试,观察流式事件是否变化。
- 检查点 3:检查 langgraph、openai、httpx 等库的 logger 是否被 propagate 到根 logger,且根 logger 是否有 stdout handler。
处理动作:把日志从 stdout 挪走
最直接的动作是全局配置日志输出到 stderr。如果你当前用 basicConfig 初始化,可以改成显式指定 stream 参数:
import logging
import sys
logging.basicConfig(
level=logging.INFO,
stream=sys.stderr,
format="%(asctime)s %(name)s %(levelname)s %(message)s",
)
如果项目里已经有 logger = logging.getLogger(__name__) 的写法,但根 logger 没有 handler,建议在入口处统一配置。若是某个第三方库直接在模块里创建了 stdout StreamHandler,需要找到它并移除或替换:
import logging
import sys
for name in ["httpx", "openai", "langgraph"]:
logger = logging.getLogger(name)
for handler in list(logger.handlers):
if hasattr(handler, "stream") and handler.stream is sys.stdout:
logger.removeHandler(handler)
handler.stream = sys.stderr
logger.addHandler(handler)
另一种更可控的方式是使用 contextlib.redirect_stdout 包裹 LangGraph 调用,让日志打印和流式返回在同一进程内分开:
import contextlib
import sys
with contextlib.redirect_stdout(sys.stderr):
events = agent.stream(config, stream_mode="updates")
for event in events:
print(event) # 这里的输出是结构化事件,未混入日志
这种方式适合临时验证,不建议作为长期方案,因为第三方库可能绕过 contextlib 直接写文件描述符。需要结合环境确认 LangGraph 具体版本的 stream 实现,部分版本会把 stdout 作为事件通道,此时 redirect 会破坏通信,只能使用 stderr 方案。
验证信号与分支排查
修改后,用命令重定向 stdout 到文件,再观察 stderr:
python run_agent.py 1>output.jsonl 2>error.log
grep -v '^\{' output.jsonl # 应无输出,说明 stdout 没有日志行
如果 output.jsonl 里只有结构化事件,error.log 里有正常日志,说明日志污染已解决。再检查 LangGraph stream 迭代到的每条事件内容,确认事件 JSON 中不再包含 log 字段以外的文本。
若污染依然存在,按以下分支排查:
- 是否启用了 uvicorn 或 fastapi 的日志重定向,这些框架可能把 access log 写入 stdout,需要单独配置 access_log 的输出文件或 stderr。
- 是否使用了 rich.logging.RichHandler,默认输出到 stdout,需要显式 console=Console(stderr=True)。
- 是否在子进程中调用 LangGraph,子进程的 stdout 被父进程日志写入,需要重定向子进程 stdout 到独立管道。
- 是否在 jupyter notebook 环境运行,notebook 会把 stdout 捕获并展示,容易造成误判,建议在终端脚本里验证。
风险边界要注意:不要把 stderr 也禁用或重定向到 /dev/null,否则会丢失 agent 的关键错误信息。建议至少保留 level=WARNING 的日志到 stderr,方便后续排查。