1. Agent 上线后为什么必须补上可观测性大模型 Agent 上线之后真正让人头疼的不是“能不能跑”而是“跑得好不好、贵不贵、错在哪”。传统服务挂了会报 500Agent 挂了往往只是回答变差、工具调错、Token 悄悄翻倍用户不投诉你根本发现不了。可观测性就是给 Agent 装上仪表盘、行车记录仪和黑匣子让日志、指标、链路追踪三路信号同时在线。这篇聚焦大模型 Agent 的线上运维场景从可观测性角度切入交付可直接复制的config.toml与settings.json配置骨架并给出验证 Agent 运行状态的具体操作步骤。适合已经跑通 Agent 原型、准备上生产或刚上线需要排障的开发者。读完你能拿到一套最小可用的观测配置知道每个字段为什么这么填也能用几条命令确认 Agent 是否真的在正常工作。我试过在没有任何观测的情况下排查一次“回答变慢”的问题最后靠翻服务器日志才定位到是某个工具调用超时导致重试整个过程花了两个小时。如果当时有链路追踪五分钟就能看到是哪一步卡住。下面按“先搭骨架、再验证、最后排障”的顺序展开。2. TaoToken 前置准备拿到可观测的调用入口Agent 的观测数据里最核心的一类就是 LLM 调用本身——每次请求的模型、Token 数、延迟、是否触发工具调用。要让这些数据可采集前提是调用入口统一且可配置。TaoToken 提供兼容 OpenAI 协议的 API 入口Agent 侧只需要改base_url和api_key就能把模型调用收敛到一个可观测的通道上。你需要先准备两样东西一个 API Key以及确认接入地址。API 地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为base_url使用。API Key 在控制台的 API Keys 页面创建创建后只显示一次建议立刻写入环境变量而不是硬编码进代码。export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api把 Key 放环境变量的好处是后面config.toml和settings.json里只引用变量名不会把密钥提交到 Git。如果你还没创建 Key可以先去控制台生成一个再回来继续配置。接入文档里有完整的字段说明遇到协议细节可以对照查。注意API Key 属于敏感凭证不要写进前端代码、不要贴到公开仓库、不要在日志里打印完整值。观测系统采集请求信息时也要对Authorization头做脱敏。3. 可复制的可观测性配置骨架这一节给出两份配置文件config.toml负责 Agent 运行时的观测开关与采样策略settings.json负责日志、指标、追踪三路输出的具体参数。两份文件配合使用前者偏“采什么”后者偏“怎么输出”。3.1 config.toml观测开关与采样# config.toml - Agent 可观测性主配置 [agent] name order-support-agent version 1.3.0 environment production [llm] provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY default_model gpt-4o-mini request_timeout_ms 30000 max_retries 2 [observability] enabled true # 采样率生产环境建议 0.1~0.3避免全量采集压垮存储 trace_sample_rate 0.2 # 错误请求强制全采不受采样率影响 always_sample_errors true # 是否记录完整 prompt/response含敏感信息时设为 false capture_payload false [observability.logs] level INFO format json output stdout include_trace_id true [observability.metrics] enabled true export_interval_ms 15000 prefix agent [observability.traces] enabled true exporter otlp endpoint http://localhost:4317 service_name order-support-agent几个关键字段值得展开。trace_sample_rate控制链路采样比例生产环境不建议全量否则存储和带宽成本会快速上升always_sample_errors保证出错请求一定被记录排障时不会因为采样丢失现场。capture_payload默认关闭因为 Agent 的输入输出可能包含用户隐私开启前要确认合规要求。3.2 settings.json三路信号输出参数{ logging: { handlers: [console, file], file_path: /var/log/agent/agent.log, rotation: { max_size_mb: 100, backup_count: 7 }, fields: { trace_id: true, span_id: true, user_id: true, session_id: true, model: true, token_usage: true, latency_ms: true } }, metrics: { counters: [ agent.requests.total, agent.requests.failed, agent.tool.calls.total, agent.tool.calls.failed, agent.llm.tokens.total ], histograms: [ agent.request.duration_ms, agent.llm.duration_ms, agent.tool.duration_ms, agent.steps.per_request ], gauges: [ agent.queue.depth, agent.active_sessions ] }, tracing: { propagate_headers: [traceparent, x-trace-id], span_attributes: { llm.model: string, llm.tokens.prompt: int, llm.tokens.completion: int, tool.name: string, tool.success: bool, agent.step: int } } }settings.json里的fields决定了每条日志带哪些上下文。trace_id和span_id是串联三路信号的钥匙务必打开。指标部分把计数器、直方图、仪表分开声明直方图用于延迟分布计数器用于累计量仪表用于瞬时值三者用途不同不要混用。3.3 把配置接进 Agent 代码配置写好后需要在 Agent 初始化时加载。下面这段代码演示如何读取两份配置并初始化观测组件。import json import os import tomllib from pathlib import Path def load_config(config_path: str config.toml, settings_path: str settings.json) - dict: with open(config_path, rb) as f: config tomllib.load(f) with open(settings_path, r, encodingutf-8) as f: settings json.load(f) # 把 api_key 从环境变量注入避免明文 key_env config[llm][api_key_env] config[llm][api_key] os.environ.get(key_env, ) if not config[llm][api_key]: raise RuntimeError(f环境变量 {key_env} 未设置) return {config: config, settings: settings} def init_observability(cfg: dict): obs cfg[config][observability] if not obs[enabled]: return None # 这里按你的观测后端初始化示例用 OTLP from opentelemetry import trace from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter provider TracerProvider() provider.add_span_processor( BatchSpanProcessor( OTLPSpanExporter(endpointobs[traces][endpoint]) ) ) trace.set_tracer_provider(provider) return trace.get_tracer(obs[traces][service_name])加载逻辑里有两个细节一是api_key从环境变量注入配置文件里只留变量名二是观测初始化失败不应该阻断 Agent 主流程可以用 try/except 包住降级为无观测运行。4. 验证 Agent 运行状态的具体操作配置接好之后不能假设它一定生效。下面给出从启动到验证的完整步骤每一步都有可观察的结果。4.1 启动并确认配置加载# 启动 Agent 服务 python -m agent.server --config config.toml --settings settings.json # 预期输出JSON 格式日志 # {time:2025-01-15T10:00:01,level:INFO,event:config.loaded, # agent:order-support-agent,observability:true,sample_rate:0.2}看到observability: true说明观测开关已打开。如果这里是false检查config.toml里[observability] enabled是否为true。4.2 发一条测试请求curl -X POST http://localhost:8000/chat \ -H Content-Type: application/json \ -d {user_id:test-001,message:查询订单 ORD001 的状态}预期返回里应该包含trace_id字段。把这个trace_id记下来后面查链路要用。{ answer: 订单 ORD001 当前状态为已签收。, trace_id: a1b2c3d4e5f6, tokens: 312, steps: 2, latency_ms: 1180 }4.3 用 trace_id 查链路# 如果用的是 OTLP Jaeger直接在 Jaeger UI 搜索 trace_id # 命令行方式示例用 otel-cli 或你的后端查询接口 curl http://localhost:16686/api/traces/a1b2c3d4e5f6链路里应该能看到至少两个 span一个llm.call一个tool.query_order。每个 span 上带duration_ms、model、tool.name等属性。如果只看到一个 span说明工具调用没有被追踪检查settings.json里tracing.span_attributes是否覆盖了工具相关字段。4.4 确认指标已上报# Prometheus 风格查询 curl http://localhost:9090/api/v1/query?queryagent_requests_total返回结果里agent_requests_total应该至少为 1。如果为 0检查export_interval_ms是否太长还没到上报周期或者指标前缀agent是否和查询时一致。4.5 验证错误请求被强制采样把采样率临时设为 0然后发一条会触发错误的请求比如查询不存在的订单确认错误链路仍然被记录。# 临时改 config.toml trace_sample_rate 0.0 always_sample_errors true重启后发错误请求再用trace_id查链路应该仍能查到。这一步验证的是“采样不丢错误现场”生产排障非常依赖这个行为。5. 本篇常见错误排查配置和验证过程中下面几个问题出现频率最高按现象、原因、处理三段式列出。现象一日志里没有 trace_id 字段。原因通常是settings.json的logging.fields.trace_id没打开或者 Agent 代码里没有把当前 span 的 trace_id 注入日志上下文。处理方式是先确认配置为true再检查日志中间件是否在请求入口处绑定了 trace_id。现象二指标查询返回空。常见原因是export_interval_ms设置过大还没到第一次上报或者指标前缀和查询语句不一致。先等一个上报周期再用curl直接查后端确认数据是否到达。如果后端有数据但查询为空多半是前缀或标签对不上。现象三链路里工具调用 span 缺失。说明工具调用没有走被追踪的包装函数。检查工具注册时是否用了观测装饰器或者settings.json里tracing.span_attributes是否声明了tool.name。有些框架需要显式开启工具追踪开关。现象四采样率设为 0 后错误链路也丢了。这是always_sample_errors没生效。确认配置里该项为true并检查代码里判断“是否错误”的逻辑是否在采样决策之前执行。顺序错了错误请求会先被采样率过滤掉。现象五api_key读取失败导致启动报错。环境变量名和config.toml里api_key_env不一致是最常见原因。用echo $TAOTOKEN_API_KEY确认变量存在再核对配置文件里的变量名拼写。另外注意不要在配置文件里直接写 Key 明文。现象六OTLP 导出连接被拒。检查endpoint地址和端口是否正确本地 collector 是否已启动。gRPC 默认端口 4317HTTP 默认 4318两者不要混用。如果 collector 在容器里注意localhost在容器内指向容器自身需要改成宿主机地址或服务名。6. 把观测数据用起来从验证到排障配置跑通只是第一步真正产生价值的是用这些数据定位问题。给你一条我常用的排障路径先看指标确认异常范围再用 trace_id 拉链路定位到具体步骤最后看该步骤的日志确认原因。比如错误率上升先在指标里按agent.requests.failed的时间序列确认是哪个时间段开始涨然后从错误日志里取几个trace_id在链路系统里看这些请求卡在哪一步如果是tool.query_order的duration_ms异常高就去查该工具的日志和下游依赖。三步下来大部分线上问题都能收敛到具体原因。如果你需要长期跑编码类或 Agent 类任务可以考虑用 Coding Plan 把调用额度固定下来避免按量计费在观测数据里出现成本尖峰。验证模型行为是否正常时模型对话页面可以直接对比不同模型的输出配合观测数据判断是模型问题还是工具问题。接入过程中遇到协议或字段问题接入文档里有完整说明API Keys 页面可以随时管理凭证。观测体系不是一次配完就结束它需要跟着 Agent 迭代持续调整采样率、告警阈值和采集字段。建议每次上线新版本时顺手检查一遍config.toml和settings.json是否还匹配当前架构别让观测配置成为被遗忘的角落。
1. Agent 上线后为什么必须补上可观测性大模型 Agent 上线之后真正让人头疼的不是“能不能跑”而是“跑得好不好、贵不贵、错在哪”。传统服务挂了会报 500Agent 挂了往往只是回答变差、工具调错、Token 悄悄翻倍用户不投诉你根本发现不了。可观测性就是给 Agent 装上仪表盘、行车记录仪和黑匣子让日志、指标、链路追踪三路信号同时在线。这篇聚焦大模型 Agent 的线上运维场景从可观测性角度切入交付可直接复制的config.toml与settings.json配置骨架并给出验证 Agent 运行状态的具体操作步骤。适合已经跑通 Agent 原型、准备上生产或刚上线需要排障的开发者。读完你能拿到一套最小可用的观测配置知道每个字段为什么这么填也能用几条命令确认 Agent 是否真的在正常工作。我试过在没有任何观测的情况下排查一次“回答变慢”的问题最后靠翻服务器日志才定位到是某个工具调用超时导致重试整个过程花了两个小时。如果当时有链路追踪五分钟就能看到是哪一步卡住。下面按“先搭骨架、再验证、最后排障”的顺序展开。2. TaoToken 前置准备拿到可观测的调用入口Agent 的观测数据里最核心的一类就是 LLM 调用本身——每次请求的模型、Token 数、延迟、是否触发工具调用。要让这些数据可采集前提是调用入口统一且可配置。TaoToken 提供兼容 OpenAI 协议的 API 入口Agent 侧只需要改base_url和api_key就能把模型调用收敛到一个可观测的通道上。你需要先准备两样东西一个 API Key以及确认接入地址。API 地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为base_url使用。API Key 在控制台的 API Keys 页面创建创建后只显示一次建议立刻写入环境变量而不是硬编码进代码。export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api把 Key 放环境变量的好处是后面config.toml和settings.json里只引用变量名不会把密钥提交到 Git。如果你还没创建 Key可以先去控制台生成一个再回来继续配置。接入文档里有完整的字段说明遇到协议细节可以对照查。注意API Key 属于敏感凭证不要写进前端代码、不要贴到公开仓库、不要在日志里打印完整值。观测系统采集请求信息时也要对Authorization头做脱敏。3. 可复制的可观测性配置骨架这一节给出两份配置文件config.toml负责 Agent 运行时的观测开关与采样策略settings.json负责日志、指标、追踪三路输出的具体参数。两份文件配合使用前者偏“采什么”后者偏“怎么输出”。3.1 config.toml观测开关与采样# config.toml - Agent 可观测性主配置 [agent] name order-support-agent version 1.3.0 environment production [llm] provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY default_model gpt-4o-mini request_timeout_ms 30000 max_retries 2 [observability] enabled true # 采样率生产环境建议 0.1~0.3避免全量采集压垮存储 trace_sample_rate 0.2 # 错误请求强制全采不受采样率影响 always_sample_errors true # 是否记录完整 prompt/response含敏感信息时设为 false capture_payload false [observability.logs] level INFO format json output stdout include_trace_id true [observability.metrics] enabled true export_interval_ms 15000 prefix agent [observability.traces] enabled true exporter otlp endpoint http://localhost:4317 service_name order-support-agent几个关键字段值得展开。trace_sample_rate控制链路采样比例生产环境不建议全量否则存储和带宽成本会快速上升always_sample_errors保证出错请求一定被记录排障时不会因为采样丢失现场。capture_payload默认关闭因为 Agent 的输入输出可能包含用户隐私开启前要确认合规要求。3.2 settings.json三路信号输出参数{ logging: { handlers: [console, file], file_path: /var/log/agent/agent.log, rotation: { max_size_mb: 100, backup_count: 7 }, fields: { trace_id: true, span_id: true, user_id: true, session_id: true, model: true, token_usage: true, latency_ms: true } }, metrics: { counters: [ agent.requests.total, agent.requests.failed, agent.tool.calls.total, agent.tool.calls.failed, agent.llm.tokens.total ], histograms: [ agent.request.duration_ms, agent.llm.duration_ms, agent.tool.duration_ms, agent.steps.per_request ], gauges: [ agent.queue.depth, agent.active_sessions ] }, tracing: { propagate_headers: [traceparent, x-trace-id], span_attributes: { llm.model: string, llm.tokens.prompt: int, llm.tokens.completion: int, tool.name: string, tool.success: bool, agent.step: int } } }settings.json里的fields决定了每条日志带哪些上下文。trace_id和span_id是串联三路信号的钥匙务必打开。指标部分把计数器、直方图、仪表分开声明直方图用于延迟分布计数器用于累计量仪表用于瞬时值三者用途不同不要混用。3.3 把配置接进 Agent 代码配置写好后需要在 Agent 初始化时加载。下面这段代码演示如何读取两份配置并初始化观测组件。import json import os import tomllib from pathlib import Path def load_config(config_path: str config.toml, settings_path: str settings.json) - dict: with open(config_path, rb) as f: config tomllib.load(f) with open(settings_path, r, encodingutf-8) as f: settings json.load(f) # 把 api_key 从环境变量注入避免明文 key_env config[llm][api_key_env] config[llm][api_key] os.environ.get(key_env, ) if not config[llm][api_key]: raise RuntimeError(f环境变量 {key_env} 未设置) return {config: config, settings: settings} def init_observability(cfg: dict): obs cfg[config][observability] if not obs[enabled]: return None # 这里按你的观测后端初始化示例用 OTLP from opentelemetry import trace from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter provider TracerProvider() provider.add_span_processor( BatchSpanProcessor( OTLPSpanExporter(endpointobs[traces][endpoint]) ) ) trace.set_tracer_provider(provider) return trace.get_tracer(obs[traces][service_name])加载逻辑里有两个细节一是api_key从环境变量注入配置文件里只留变量名二是观测初始化失败不应该阻断 Agent 主流程可以用 try/except 包住降级为无观测运行。4. 验证 Agent 运行状态的具体操作配置接好之后不能假设它一定生效。下面给出从启动到验证的完整步骤每一步都有可观察的结果。4.1 启动并确认配置加载# 启动 Agent 服务 python -m agent.server --config config.toml --settings settings.json # 预期输出JSON 格式日志 # {time:2025-01-15T10:00:01,level:INFO,event:config.loaded, # agent:order-support-agent,observability:true,sample_rate:0.2}看到observability: true说明观测开关已打开。如果这里是false检查config.toml里[observability] enabled是否为true。4.2 发一条测试请求curl -X POST http://localhost:8000/chat \ -H Content-Type: application/json \ -d {user_id:test-001,message:查询订单 ORD001 的状态}预期返回里应该包含trace_id字段。把这个trace_id记下来后面查链路要用。{ answer: 订单 ORD001 当前状态为已签收。, trace_id: a1b2c3d4e5f6, tokens: 312, steps: 2, latency_ms: 1180 }4.3 用 trace_id 查链路# 如果用的是 OTLP Jaeger直接在 Jaeger UI 搜索 trace_id # 命令行方式示例用 otel-cli 或你的后端查询接口 curl http://localhost:16686/api/traces/a1b2c3d4e5f6链路里应该能看到至少两个 span一个llm.call一个tool.query_order。每个 span 上带duration_ms、model、tool.name等属性。如果只看到一个 span说明工具调用没有被追踪检查settings.json里tracing.span_attributes是否覆盖了工具相关字段。4.4 确认指标已上报# Prometheus 风格查询 curl http://localhost:9090/api/v1/query?queryagent_requests_total返回结果里agent_requests_total应该至少为 1。如果为 0检查export_interval_ms是否太长还没到上报周期或者指标前缀agent是否和查询时一致。4.5 验证错误请求被强制采样把采样率临时设为 0然后发一条会触发错误的请求比如查询不存在的订单确认错误链路仍然被记录。# 临时改 config.toml trace_sample_rate 0.0 always_sample_errors true重启后发错误请求再用trace_id查链路应该仍能查到。这一步验证的是“采样不丢错误现场”生产排障非常依赖这个行为。5. 本篇常见错误排查配置和验证过程中下面几个问题出现频率最高按现象、原因、处理三段式列出。现象一日志里没有 trace_id 字段。原因通常是settings.json的logging.fields.trace_id没打开或者 Agent 代码里没有把当前 span 的 trace_id 注入日志上下文。处理方式是先确认配置为true再检查日志中间件是否在请求入口处绑定了 trace_id。现象二指标查询返回空。常见原因是export_interval_ms设置过大还没到第一次上报或者指标前缀和查询语句不一致。先等一个上报周期再用curl直接查后端确认数据是否到达。如果后端有数据但查询为空多半是前缀或标签对不上。现象三链路里工具调用 span 缺失。说明工具调用没有走被追踪的包装函数。检查工具注册时是否用了观测装饰器或者settings.json里tracing.span_attributes是否声明了tool.name。有些框架需要显式开启工具追踪开关。现象四采样率设为 0 后错误链路也丢了。这是always_sample_errors没生效。确认配置里该项为true并检查代码里判断“是否错误”的逻辑是否在采样决策之前执行。顺序错了错误请求会先被采样率过滤掉。现象五api_key读取失败导致启动报错。环境变量名和config.toml里api_key_env不一致是最常见原因。用echo $TAOTOKEN_API_KEY确认变量存在再核对配置文件里的变量名拼写。另外注意不要在配置文件里直接写 Key 明文。现象六OTLP 导出连接被拒。检查endpoint地址和端口是否正确本地 collector 是否已启动。gRPC 默认端口 4317HTTP 默认 4318两者不要混用。如果 collector 在容器里注意localhost在容器内指向容器自身需要改成宿主机地址或服务名。6. 把观测数据用起来从验证到排障配置跑通只是第一步真正产生价值的是用这些数据定位问题。给你一条我常用的排障路径先看指标确认异常范围再用 trace_id 拉链路定位到具体步骤最后看该步骤的日志确认原因。比如错误率上升先在指标里按agent.requests.failed的时间序列确认是哪个时间段开始涨然后从错误日志里取几个trace_id在链路系统里看这些请求卡在哪一步如果是tool.query_order的duration_ms异常高就去查该工具的日志和下游依赖。三步下来大部分线上问题都能收敛到具体原因。如果你需要长期跑编码类或 Agent 类任务可以考虑用 Coding Plan 把调用额度固定下来避免按量计费在观测数据里出现成本尖峰。验证模型行为是否正常时模型对话页面可以直接对比不同模型的输出配合观测数据判断是模型问题还是工具问题。接入过程中遇到协议或字段问题接入文档里有完整说明API Keys 页面可以随时管理凭证。观测体系不是一次配完就结束它需要跟着 Agent 迭代持续调整采样率、告警阈值和采集字段。建议每次上线新版本时顺手检查一遍config.toml和settings.json是否还匹配当前架构别让观测配置成为被遗忘的角落。
