1. Agent 上线后为什么总在“盲调”从一次线上延迟抖动说起AI Agent 从 Demo 走到生产最折磨人的不是模型能力不够而是“看不见、管不住、改不了”。我试过最典型的一次用户反馈“回答变慢了”我打开日志只看到一行POST /api/chat 200 OK至于中间模型调了几次、检索命中了哪些文档、工具返回了什么、Token 花了多少全靠猜。这不是个例而是 Agent 应用在生产环境里的系统性工程缺失。传统 Web 应用有 APM 覆盖接口耗时、错误率、资源使用但 Agent 的核心问题完全不同。它的执行链路是动态的规划 → 检索 → 推理 → 工具 → 校验 → 生成每一步都可能分叉。失败模式也不是 HTTP 状态码能表达的而是幻觉、格式错误、工具选错、上下文漂移。成本结构更麻烦传统服务是服务器固定成本Agent 是 Token 动态成本随链路复杂度非线性增长。质量评估单元测试也测不出来需要持续评估输出质量、工具准确率、检索相关性。AgentInsight SDK 就是为这类问题设计的开源可观测工具基于 OpenTelemetry 协议支持 Python 和 TypeScript可以零侵入接入现有 Agent 应用采集 Trace 链路、模型调用、Token 消耗、响应耗时、异常错误等关键数据。它解决的是“可观测 → 可监控 → 可优化”三层闭环适合已经上线或即将上线 AI Agent、需要定位延迟与失败环节的工程团队。这篇内容不重复讨论“为什么 Agent 需要可观测”而是直接进入工程实践怎么用 AgentInsight SDK 一步步搭建可观测、可监控、可优化的 Agent 工程体系同时结合 TaoToken 统一 Key/API 通道打通调用日志与指标让链路数据真正可用。2. 前置准备TaoToken 统一通道与 AgentInsight SDK 安装配置在接入 AgentInsight 之前先把模型调用通道统一起来。很多团队的问题是Agent 里同时调了 OpenAI、Claude、国产模型每个 Key 分散在不同环境变量里日志也对不上。TaoToken 提供统一的 API 通道把模型调用收敛到一个 Base URL 和一把 Key这样 AgentInsight 采集到的 Trace 才能和调用日志一一对应。TaoToken 的 API 地址是https://taotoken.net/api官网入口是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。你可以在控制台创建 API Key然后在 Agent 项目里统一配置。这样做的好处是无论底层换哪个模型AgentInsight 里的 Trace 结构不变调优时对比的是同一套指标。先安装 AgentInsight SDK。Python 版本要求 3.10 以上pip install agentinsight-sdk pip install agentinsight-sdk openai pip install agentinsight-sdk langchain langchain-openai初始化有两种方式。生产环境推荐环境变量export AGENTINSIGHT_PUBLIC_KEYpk-... export AGENTINSIGHT_SECRET_KEYsk-... export AGENTINSIGHT_BASE_URLhttps://agent.goldebridge.com export TAOTOKEN_API_KEY你的 TaoToken Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api代码里直接初始化from agentinsight import AgentInsight client AgentInsight( public_keypk-..., secret_keysk-..., base_urlhttps://agent.goldebridge.com, tracing_enabledTrue, flush_at512, flush_interval5.0, sample_rate1.0, environmentproduction, release1.0.0, )这里几个参数值得说明。flush_at512是批量发送阈值攒够 512 条 Span 才发一次避免高频小包拖慢业务。flush_interval5.0是兜底间隔即使没攒够也会 5 秒发一次。sample_rate1.0是全量采集生产环境流量大时可以降到 0.1~0.3。environment和release是标签方便在平台上按版本过滤 Trace。如果你用 TaoToken 统一通道模型客户端这样配from openai import OpenAI llm_client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], )这样 AgentInsight 采集到的 generation Span 里模型调用地址就是 TaoToken 通道日志和指标能对齐。踩过的坑是有人把base_url写成带/v1的路径结果 SDK 拼接后变成/v1/v1/chat/completions报 404。TaoToken 的 Base URL 就是https://taotoken.net/api不要自己加后缀。3. 可复制配置observe 埋点字段清单与 JSON/TOML 片段AgentInsight 最核心的能力是observe装饰器它自动追踪函数调用嵌套时自动建立父子关系。先看一个真实 RAG Agent 场景from agentinsight import observe observe(as_typeagent, namerag-agent) def run_rag_agent(query: str) - str: docs retrieve_documents(query) answer generate_answer(query, docs) validated safety_check(answer) return validated observe(as_typeretriever, namedocument-retrieval) def retrieve_documents(query: str) - list[str]: results vector_store.similarity_search(query, k3) return [doc.page_content for doc in results] observe(as_typegeneration, nameanswer-generation) def generate_answer(query: str, docs: list[str]) - str: context \n.join(docs) prompt f基于以下上下文回答问题\n\n{context}\n\n问题{query} response llm_client.chat.completions.create( modelgpt-4, messages[{role: user, content: prompt}], temperature0.7, ) return response.choices[0].message.content observe(as_typeguardrail, namesafety-validation) def safety_check(answer: str) - str: if contains_sensitive_info(answer): return [已过滤回答包含敏感信息] return answer每个observe装饰的函数自动成为一个 Span嵌套调用时自动建立父子关系。在 AgentInsight 平台上你会看到完整 Tracerag-agent (agent) ├── document-retrieval (retriever) ├── answer-generation (generation) └── safety-validation (guardrail)每个 Span 自动记录函数名、输入/输出、开始/结束时间、执行耗时、异常信息。观察类型as_type的语义对照如下as_type 含义典型场景agentAgent 执行主体、主循环、多步推理chain链式调用、Prompt 模板链、预处理链tool工具调用、外部 API、数据库查询、代码执行generationLLM 生成、模型推理调用retriever检索器、向量检索、全文搜索embedding向量嵌入、文本向量化guardrail安全护栏、输入/输出校验、内容过滤evaluator评估器、自动评分、质量检测正确使用这些类型Trace 在平台上会呈现更清晰的语义结构。对于需要精细控制的场景比如异步调用、动态 Span 创建可以用底层 APIfrom agentinsight import AgentInsight client AgentInsight() with client.start_as_current_observation( nameprocess-user-query, as_typespan, ) as root_span: with root_span.start_as_current_observation( namellm-inference, as_typegeneration, modelgpt-4, input{query: 用户的具体问题}, model_parameters{temperature: 0.7, max_tokens: 500}, ) as gen_span: response call_llm(用户的具体问题) gen_span.update( outputresponse, usage_details{ prompt_tokens: 150, completion_tokens: 300, }, cost_details{total_cost: 0.0045}, ) client.flush()如果你用 LangChain接入更简单from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser from agentinsight.langchain import CallbackHandler handler CallbackHandler() llm ChatOpenAI( modelgpt-4, temperature0, openai_api_keyos.environ[TAOTOKEN_API_KEY], openai_api_baseos.environ[TAOTOKEN_BASE_URL], ) prompt ChatPromptTemplate.from_messages([ (system, 你是一个专业的技术助手请用中文回答。), (human, {input}), ]) chain prompt | llm | StrOutputParser() result chain.invoke( {input: 什么是 Agent 可观测}, config{callbacks: [handler]}, )CallbackHandler 会自动追踪 LangChain 链路中的每一个环节Prompt 模板渲染、LLM 调用、Output Parser 处理等。这里三件套必须写全Base URL 用https://taotoken.net/apiKey 用 TaoToken 控制台创建的 KeyModel ID 按你实际调用的模型填比如gpt-4、claude-3-5-sonnet等。生产环境建议把配置写成 JSON 或 TOML避免硬编码。比如agentinsight.toml[agentinsight] public_key pk-... secret_key sk-... base_url https://agent.goldebridge.com tracing_enabled true flush_at 512 flush_interval 5.0 sample_rate 0.3 environment production release 1.0.0 [taotoken] api_key 你的 TaoToken Key base_url https://taotoken.net/api default_model gpt-4读取时用tomllibPython 3.11或toml库加载这样不同环境切换只改配置文件代码不动。4. 验证请求从 Trace 到指标确认链路数据真的通了配置完成后第一步是验证数据能不能到平台。写一个最小可运行脚本import os from agentinsight import observe, get_client from openai import OpenAI llm_client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) observe(as_typegeneration, namesmoke-test-generation) def smoke_test(): response llm_client.chat.completions.create( modelgpt-4, messages[{role: user, content: 用一句话解释什么是可观测性。}], ) return response.choices[0].message.content if __name__ __main__: result smoke_test() print(模型返回, result) client get_client() client.flush() print(Trace 已发送请到 AgentInsight 平台查看。)运行后如果平台能看到一条名为smoke-test-generation的 Trace说明链路通了。如果看不到先检查flush()有没有调用再检查网络出口能不能访问agent.goldebridge.com。验证通过后把上下文传播加上这样 Trace 能关联到具体用户和会话from agentinsight import AgentInsight, propagate_attributes client AgentInsight() with client.start_as_current_observation(nameuser-request, as_typespan) as root: with propagate_attributes( user_iduser_12345, session_idsession_abc, metadata{ environment: production, variant: prompt-v2, feature: rag-agent, }, tags[production, v2, rag], ): answer run_rag_agent(用户的问题) client.flush()跨服务传播也支持通过 HTTP 头部基于 OpenTelemetry Baggage 协议在微服务之间传递上下文from agentinsight import propagate_attributes import requests with propagate_attributes( user_iduser_12345, session_idsession_abc, as_baggageTrue, ): result requests.post( http://downstream-service/api/process, jsondata, )有了这些数据你可以在平台上构建监控指标体系。核心指标分四类延迟类Trace 数量、平均耗时、P95/P99、首 Token 时间、成本类总成本、按项目拆分、按会话拆分、趋势对比、模型类各模型调用量、延迟分布、Token 用量、成本/调用、错误类错误率趋势、异常类型分布、失败 Trace 详情、智能预警。验证成功的结果是你在平台上能按用户、会话、标签、元数据过滤 Trace能下钻到某一条失败 Trace 看到具体是哪个 Span 报错、输入输出是什么、耗时多少。这时候可观测才算真正落地。5. 常见报错排查401、local proxy failed、reading choices、OAuth接入过程中最容易卡在几个报错上这里逐个对照排查。401 Unauthorized最常见的是 Key 配错。检查三处AgentInsight 的public_key/secret_key是否和控制台一致TaoToken 的 API Key 是否复制完整注意前后空格环境变量有没有被其他 shell 覆盖。如果用了.env文件确认加载顺序别让旧变量覆盖新变量。local proxy failed / connection refused这类报错通常是网络出口问题。先确认运行环境能不能访问https://taotoken.net/api和https://agent.goldebridge.com。如果是容器环境检查 DNS 配置和出站规则。注意不要配置任何非官方的网络转发工具直接用官方通道即可。如果公司网络有出口限制联系运维放行这两个域名。reading choices of undefined这个报错说明模型返回结构不对通常是 Base URL 配错导致请求打到了非预期端点。检查base_url是不是https://taotoken.net/api不要多加/v1。另外确认model参数是 TaoToken 支持的模型 ID写错模型名也可能返回非标准结构。还有一种情况是流式响应没处理完就取choices加个判空response llm_client.chat.completions.create(...) if not response or not response.choices: raise ValueError(模型返回为空检查 Base URL 和 Model ID) content response.choices[0].message.contentOAuth / authentication failed如果你用的是 Claude Code 或 Codex 这类工具认证方式可能不是简单 API Key。以 Claude Code 为例需要配置ANTHROPIC_BASE_URL和ANTHROPIC_API_KEYBase URL 指向 TaoToken 通道Key 用 TaoToken 创建的 Key。Codex 的auth.json里要写全三件套Base URL、Key、Model ID。如果出现 OAuth 相关报错先确认是不是混用了官方登录态和 API Key 两种认证方式二选一即可。Trace 不显示 / Span 丢失检查flush()有没有在请求结束前调用检查sample_rate是不是设太低检查observe装饰的函数是不是真的被执行了有些异步框架里装饰器位置不对会失效。如果是异步场景确认用的是支持 async 的装饰方式或者在事件循环结束后手动 flush。Token 统计为 0AgentInsight 依赖模型返回的 usage 字段。如果 TaoToken 通道返回的响应里没有 usage需要手动在gen_span.update()里补usage_details。另外确认模型 ID 在平台的定价表里能匹配到否则成本计算会是 0。排查顺序建议先看 SDK 日志有没有发送成功再看平台有没有收到最后看指标计算对不对。大部分问题出在第一步和第二步之间也就是网络和 Key 配置。6. 从可观测到可优化评分系统、实验框架与持续调优闭环可观测和可监控告诉你“发生了什么”可优化解决的是“怎么做得更好”。AgentInsight 支持三种评分类型可以对每次 Agent 执行进行质量标记from agentinsight import observe, get_client from agentinsight.api.commons.types.score_data_type import ScoreDataType observe(namecustomer-service-agent) def handle_customer_query(query: str) - str: answer run_rag_agent(query) return answer result handle_customer_query(如何退换货) client get_client() with client.start_as_current_observation( namequality-evaluation, as_typeevaluator, ) as eval_span: eval_span.score( namerelevance, value0.92, data_typeScoreDataType.NUMERIC, comment回答与问题高度相关, ) eval_span.score( namehallucination_free, value1.0, data_typeScoreDataType.BOOLEAN, ) eval_span.score( namesentiment, valuepositive, data_typeScoreDataType.CATEGORICAL, ) client.flush()评分来源可以多样人工评分适合运营/审核人员标注客服抽检打分自动评分适合代码逻辑自动判断是否包含关键词、格式是否正确LLM-as-Judge 适合用另一个 LLM 评估回答质量用户反馈适合用户点赞/点踩按钮反馈。有了评分就可以跑实验框架做 A/B 测试from agentinsight import AgentInsight, Evaluation client AgentInsight() def rag_task(*, item, **kwargs): input_data item[input] if isinstance(item, dict) else item.input return run_rag_agent(input_data) def relevance_evaluator(*, input, output, expected_outputNone, **kwargs): if not expected_output: return Evaluation(namerelevance, value0, comment缺少期望输出) overlap set(expected_output.split()) set(output.split()) score len(overlap) / max(len(expected_output.split()), 1) return Evaluation( namerelevance, valueround(score, 2), commentf关键词重合率: {score:.0%}, ) def cost_evaluator(*, input, output, expected_outputNone, **kwargs): cost len(output) * 0.00001 return Evaluation( namecost_score, valuemax(0, 1.0 - cost), commentf估算成本: ${cost:.4f}, ) result client.run_experiment( namerag-prompt-v2-vs-v1, data[ {input: 如何退换货, expected_output: 退换货流程 7天无理由 快递上门}, {input: 会员有什么权益, expected_output: 会员权益 折扣 积分 专属客服}, {input: 配送范围是什么, expected_output: 配送范围 全国 主要城市 次日达}, ], taskrag_task, evaluators[relevance_evaluator, cost_evaluator], ) for item_result in result.item_results: print(f输入: {item_result.item}) print(f输出: {item_result.output}) for evaluation in item_result.evaluations: print(f {evaluation.name}: {evaluation.value} ({evaluation.comment}))这个实验框架的价值在于把“感觉 Prompt 效果变好了”变成“数据证明 Prompt v2 的相关性评分比 v1 高 15%”。持续优化闭环就是采集 Trace 评分 → 识别低分场景 → 设计改进方案优化 Prompt / 更换模型 / 调整检索策略→ 运行 A/B 实验 → 发布最优版本 → 回到第一步。TypeScript 开发者也有完整 SDK。初始化用 OpenTelemetry 的 NodeSDKimport { AgentInsightSpanProcessor } from agentinsight-sdk/otel; import { NodeSDK } from opentelemetry/sdk-node; const sdk new NodeSDK({ spanProcessors: [ new AgentInsightSpanProcessor({ publicKey: process.env.AGENTINSIGHT_PUBLIC_KEY!, secretKey: process.env.AGENTINSIGHT_SECRET_KEY!, baseUrl: https://agent.goldebridge.com, }), ], }); sdk.start();OpenAI 集成用observeOpenAI包装import { observeOpenAI } from agentinsight-sdk/openai; import OpenAI from openai; const client observeOpenAI( new OpenAI({ apiKey: process.env.TAOTOKEN_API_KEY, baseURL: process.env.TAOTOKEN_BASE_URL, }), ); const result await client.chat.completions.create({ model: gpt-4, messages: [{ role: user, content: Hello! }], });生产环境还有几个最佳实践。采样策略上开发/测试环境sample_rate1.0全量采集生产环境 0.1~0.3 采样关键场景如付费用户通过propagate_attributes的 tags 标记确保被采集。数据脱敏方面TypeScript 版 SDK 内置了脱敏功能可以自动屏蔽 API Key、手机号、身份证号等敏感信息。多项目隔离上每个应用用独立 API Key数据完全隔离。批量发送默认flush_at512、flush_interval5s高并发场景可以调到flush_at1024、flush_interval10.0避免对业务性能产生影响。调优验证动作建议固定成流程每周跑一次实验对比每次 Prompt 变更都带评分每次模型切换都看延迟和成本曲线。这样 Agent 的优化就不是凭感觉而是数据驱动。需要长期做编码和 Agent 调优的团队可以用 Coding Plan 把通道和额度统一管理只是验证模型效果的直接用模型对话快速试接入和排障阶段API Keys 和接入文档是最常翻的两页。