1. 上线第三天，Agent 开始“不听话”了
AI Agent 上线后最让人抓狂的不是它不会做，而是它昨天还乖乖调用搜索工具，今天突然开始乱删文件、乱调接口、简单问题烧掉几十倍 Token。你翻遍业务日志，只看到一句result: success，完全不知道中间发生了什么。这个场景几乎每个做 Agent 的团队都会撞上，因为 Agent 本质是一个动态决策系统，不是固定代码流程。传统应用出问题看日志就行，Agent 的链路是：用户问题 → LLM 理解 → 制定计划 → 选择工具 → 调用 API → 读取结果 → 再次推理 → 生成答案，中间任何一步偏了，最终结果就错，而你根本看不到它中间想了什么、调了什么、花了多少。
我试过最笨的办法：在每个节点print(response)，结果日志刷屏，还是定位不到是哪一步把/project/config当成临时文件删了。问题不在模型能力，而在可观测性缺失。这篇就聚焦一个具体排查场景：Agent 上线后行为漂移，怎么用 TaoToken 统一 Key 配合 Langfuse 追踪，快速判断“不听话”到底是模型、提示词还是通道配置导致的。适合已经跑通 Demo、准备上生产或已经上线踩坑的开发者，跟着做能拿到一套可复制的配置骨架和验证步骤。
2. 为什么排查前要先统一 Key 通道
在接入 Langfuse 之前，有个前置动作经常被忽略：把 Agent 里散落各处的模型调用收敛到一个统一入口。很多项目的 Key 是这么来的：Planner 用一个 Key，Tool 调用用一个 Key，RAG 总结又换一个 Key，甚至有人把不同厂商的 Key 硬编码在不同文件里。一旦行为漂移，你连“这次请求到底走了哪个通道、哪个模型”都说不清，Langfuse 里看到的 trace 也是碎的。
TaoToken 在这里的作用是提供一个统一的 API 入口，把模型调用集中管理。官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api 。统一 Key 之后，Agent 的每一次 LLM 调用都经过同一个通道，Langfuse 抓到的 trace 才能完整串起来。这一步不是为了“换个供应商”，而是为了让可观测性有落脚点——通道不统一，追踪就是断的。
具体操作上，先去控制台创建 Key，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，然后在 API Keys 页面生成密钥，地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。生成后不要写死在代码里，用环境变量注入。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各语言 SDK 的 base_url 配置方式，照着改就行。
3. 可复制的统一 Key 配置骨架
下面这套骨架我实测下来比较稳，核心思路是：所有模型调用走一个 client 工厂，base_url 指向 TaoToken，Key 从环境变量读，同时预留 Langfuse 的 trace 注入点。
先装依赖：
pip install openai langfuse然后写配置模块agent_llm.py：
import os from openai import OpenAI from langfuse.decorators import observe, langfuse_context # 统一 Key 通道：所有模型调用都从这里走 client = OpenAI( api_key=os.environ["TAOTOKEN_API_KEY"], base_url="https://taotoken.net/api", ) # 模型名按你实际使用的填，这里用占位 DEFAULT_MODEL = os.environ.get("AGENT_MODEL", "your-model-name") @observe() def call_llm(prompt: str, model: str = DEFAULT_MODEL): # 把关键元数据挂到当前 trace 上，方便 Langfuse 过滤 langfuse_context.update_current_observation( metadata={"channel": "taotoken", "model": model} ) resp = client.chat.completions.create( model=model, messages=[{"role": "user", "content": prompt}], ) usage = resp.usage langfuse_context.update_current_observation( usage={ "input": usage.prompt_tokens, "output": usage.completion_tokens, } ) return resp.choices[0].message.contentLangfuse 的环境变量也要配好，否则 trace 发不出去：
export LANGFUSE_PUBLIC_KEY="pk-lf-xxxx" export LANGFUSE_SECRET_KEY="sk-lf-xxxx" export LANGFUSE_HOST="https://cloud.langfuse.com" export TAOTOKEN_API_KEY="你的TaoToken Key" export AGENT_MODEL="你的模型名"这里有个关键点：@observe()装饰器会把函数调用自动变成 Langfuse 的一个 span，update_current_observation把通道信息和 Token 用量挂上去。这样在 Dashboard 里，你既能按channel=taotoken过滤，也能直接看到每次调用的 input/output token 数。Agent 的 Planner、Tool 调用、RAG 总结如果都走call_llm，整条链路就自动串成一个 trace。
4. 把 Agent 执行链路接进 Langfuse
光有 LLM 调用记录还不够，Agent 的“不听话”往往出在工具调用和规划步骤上。下面把工具调用也纳入追踪，用一个文件管理 Agent 举例，复现“为什么删错目录”的排查过程。
from langfuse.decorators import observe from agent_llm import call_llm @observe() def plan_task(question: str): prompt = f"你是任务规划器。用户请求：{question}\n输出要调用的工具和参数。" return call_llm(prompt) @observe() def call_tool(tool_name: str, params: dict): # 真实项目里这里接你的工具实现 if tool_name == "delete_files": return {"deleted": params.get("paths", []), "status": "success"} return {"status": "unknown_tool"} @observe() def agent_run(question: str): plan = plan_task(question) # 简化解析，实际项目按你的规划格式处理 tool_result = call_tool("delete_files", {"paths": ["/project/cache"]}) final = call_llm(f"根据工具结果生成回答：{tool_result}") return final跑一次：
agent_run("帮我清理项目中的临时文件")执行完去 Langfuse Dashboard，你会看到一棵 trace 树：
Trace: 帮我清理项目中的临时文件 ├── plan_task │ └── call_llm (channel=taotoken, input_tokens=..., output_tokens=...) ├── call_tool (delete_files) └── call_llm (生成回答)这时候如果发现删错了目录，直接点开plan_task那个 span，看它输出的工具参数里paths到底是什么。如果paths里出现了/project/config，问题就在规划阶段——要么提示词没约束清楚，要么模型理解偏了。如果paths是对的但call_tool执行错了，问题在工具实现。如果call_llm的 input_tokens 异常大，说明提示词里塞了太多无关上下文。这就是可观测性的价值：把“猜”变成“看”。
5. 验证调用链是否正常的操作步骤
配置完别急着上生产，先做一轮验证，确认 trace 能正常上报、Token 能对上、链路是完整的。
第一步，跑一个最小请求，确认通道通：
curl https://taotoken.net/api/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"your-model-name","messages":[{"role":"user","content":"ping"}]}'返回正常说明 Key 和通道没问题。如果这里就报 401，先查 Key 和 base_url，别往下走。
第二步，跑agent_run，然后去 Langfuse 看三件事：trace 是否出现、channel=taotoken的 metadata 是否挂上、usage 里的 token 数是否和响应里的 usage 一致。如果 trace 没出现，检查LANGFUSE_HOST和网络；如果 token 数为空，检查update_current_observation的 usage 字段名。
第三步，做一次 Token 消耗对比。同一个问题，分别用统一 Key 通道和之前的散装配置各跑一次，在 Langfuse 里按 trace 对比 input/output token。如果统一通道后 Token 明显下降，说明之前有重复调用或上下文冗余；如果反而上升，检查是不是把不该带的上下文塞进了 prompt。
第四步，模拟一次“行为漂移”。故意把规划提示词改模糊，比如把“只删除临时文件”改成“清理项目”，再跑一次，看 Langfuse 里plan_task的输出是否开始包含危险路径。这一步能帮你确认：当问题真的发生时，你的追踪链路能不能定位到根因。
验证通过的标准很简单：任意一次 Agent 请求，你能在 Langfuse 里看到完整的 trace 树，每个 LLM 调用都有 token 数，每个工具调用都有参数和结果，并且能按通道过滤。达到这个状态，再谈优化。
6. 本篇常见错排查
Langfuse 里看不到 trace：最常见的是环境变量没生效，尤其是LANGFUSE_HOST写错或没设。另一个原因是@observe()装饰的函数没有被真正调用，或者调用发生在装饰器作用域外。检查一下agent_run是不是被@observe()包住了。
Token 数和实际对不上：如果你在call_llm里手动传了 usage，但模型返回的 usage 字段名不同（有的用prompt_tokens，有的用input_tokens），就会对不上。统一用响应里的resp.usage取值，别自己算。
通道 metadata 丢失：update_current_observation必须在@observe()装饰的函数内部调用，且要在 LLM 请求前后都行，但别在函数外调。如果 metadata 没挂上，检查是不是在异步环境里用了同步装饰器。
Agent 行为漂移但 trace 正常：如果 trace 显示规划、工具、总结都“正常”，但结果还是错，问题可能在提示词或模型本身。这时候用模型对话功能单独测一下同一个 prompt，地址是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite ，把 trace 里记录的原始 prompt 贴进去，看模型单独跑会不会也偏。如果单独跑正常、Agent 里偏，问题在上下文拼接；如果单独跑也偏，问题在提示词或模型选择。
长期编码和 Agent 调试想省成本：如果你在反复调 Agent 的规划逻辑，每次改一点就跑一次全链路，Token 消耗会很快。这种情况可以看看 Coding Plan，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，适合需要长期迭代编码和 Agent 逻辑的场景。Claude Code 相关的接入配置在 https://taotoken.net/claudecode?utm_source=taotoken_aicg_blog_end&utm_content=claudecode&utm_campaign=rewrite ，有需要可以对照。
排查的核心逻辑就一句话：先确认通道统一，再确认 trace 完整，最后按 span 逐层看。模型、提示词、通道配置这三个变量，只要 trace 够细，一定能定位到是哪个。
