1. Agent Harness 观测链路为什么总在工具调用处断掉多 Agent 编排跑起来之后最让人头疼的不是模型答得慢而是链路断在工具调用那一跳。主 Agent 的 Span 还在子 Agent 的 Span 没了工具调用的入参出参记了一半下游 HTTP 请求的 Trace Context 又丢了。你打开 Jaeger 一看整条链路像被剪成几段根本拼不回一次完整的任务执行过程。我试过在一个三 Agent 协作的客服场景里排查问题主 Agent 负责意图识别子 Agent 负责订单查询还有一个工具 Agent 负责调用内部 API。结果订单查询子 Agent 的 Span 是孤儿节点工具调用的 Span 干脆没上报。最后只能靠日志时间戳硬凑效率极低。问题的根因有三个一是 Agent Harness 没有统一的埋点入口每个 Agent 各写各的二是工具调用跨进程后 Trace Context 没有透传三是观测模块和业务代码耦合想换后端就得改代码。这篇要解决的就是这件事把 Agent Harness 的观测做成可插拔的用 OpenTelemetry 统一埋点用 Collector 统一收口再通过 TaoToken 的统一 Key 和 API 通道把模型调用这一段也纳入同一条 Trace。目标很明确——观测模块能像换插件一样替换链路数据可复现工具调用不再断链。适合谁看正在做多 Agent 编排、需要排查跨 Agent 调用问题的后端和平台工程师已经在用 OpenTelemetry 但发现 Agent 场景埋点不完整的同学以及想把模型调用链路和业务链路打通的可观测性负责人。核心检索词先明确OpenTelemetry Agent Harness 可插拔观测本质是给 Agent 运行时加一层统一的遥测采集层让 Span、Log、Metric 三要素在 Agent 编排和工具调用场景下都能被完整记录并且采集层可以独立替换而不影响业务逻辑。下面按六个部分展开先讲清楚问题场景和断链原因再讲 TaoToken 前置准备然后给可复制的 Collector 配置和埋点代码接着做一次端到端 Trace 验证再列常见报错排查最后给接入 CTA。2. TaoToken 前置准备统一 Key 与 API 通道接入在讲埋点之前先把模型调用这一段的通道准备好。Agent Harness 里的模型请求如果走的是各家不同的地址Trace 里就会出现多个不相关的出口链路自然拼不起来。TaoToken 提供统一的 API 通道把模型调用收敛到一个 Base URL 上这样 OpenTelemetry 的 HTTP 埋点就能统一捕获。你需要准备三样东西Base URL、API Key、Model ID。这三件套在后面的 Collector 配置和埋点代码里都会用到。Base URL 用https://taotoken.net/api注意这个地址不带任何查询参数。API Key 在控制台的 API Keys 页面创建创建后复制保存后面配置里用环境变量注入不要硬编码进代码。Model ID 根据你实际使用的模型填写比如claude-sonnet-4-20250514这类标识。在 Agent Harness 里Model ID 建议做成配置项方便不同 Agent 用不同模型时统一管理。如果你用的是 Claude Code 这类编码 Agent接入时同样填这三件套Base URL 填https://taotoken.net/apiKey 填你创建的 API KeyModel ID 填对应模型标识。这样 Claude Code 发出的模型请求就会走统一通道配合 OpenTelemetry 的 HTTP instrumentation 就能自动生成 Span。对于长期跑编码任务或 Agent 编排的场景可以考虑 Coding Plan它在统一通道的基础上更适合持续性的编码和 Agent 调用。如果只是先验证模型连通性可以直接用模型对话页面测试。前置准备的核心逻辑是先把模型调用的出口统一再谈链路追踪。否则每个 Agent 调不同地址Trace 里全是碎片Collector 再怎么配也拼不完整。这里给一个环境变量配置示例后面所有配置都基于这些变量export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEYsk-你的实际Key export TAOTOKEN_MODEL_IDclaude-sonnet-4-20250514 export OTEL_EXPORTER_OTLP_ENDPOINThttp://localhost:4317 export OTEL_SERVICE_NAMEagent-harness注意 API Key 不要写进代码仓库用环境变量或者密钥管理服务注入。OTLP 端点指向你本地或集群内的 Collector后面会配。3. 可复制配置Collector 与 Agent Harness 埋点这一部分是核心直接给可复制的配置和代码。分三块Collector 配置、Agent Harness 的 Span 埋点、工具调用的 Context 透传。3.1 OpenTelemetry Collector 配置Collector 负责接收 Agent Harness 发来的 OTLP 数据做处理后转发到后端。下面这份配置接收 gRPC 和 HTTP 两种 OTLP经过批处理和资源检测后分别导出到 Jaeger 和 Prometheus。# otel-collector-config.yaml receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 processors: batch: timeout: 5s send_batch_size: 512 resourcedetection: detectors: [env, system] timeout: 2s attributes: actions: - key: agent.harness.version value: 1.0.0 action: upsert exporters: otlp/jaeger: endpoint: jaeger:4317 tls: insecure: true prometheus: endpoint: 0.0.0.0:8889 debug: verbosity: detailed service: pipelines: traces: receivers: [otlp] processors: [resourcedetection, attributes, batch] exporters: [otlp/jaeger, debug] metrics: receivers: [otlp] processors: [resourcedetection, batch] exporters: [prometheus]这份配置的关键点resourcedetection自动打上主机和环境标签attributes给所有 Span 加上 Agent Harness 版本号方便后续按版本过滤。debugexporter 在调试阶段很有用能看到实际发出的 Span 结构验证通过后可以去掉。启动 Collector 用 Dockerdocker run -d --name otel-collector \ -p 4317:4317 -p 4318:4318 -p 8889:8889 \ -v $(pwd)/otel-collector-config.yaml:/etc/otelcol/config.yaml \ otel/opentelemetry-collector:latest \ --config/etc/otelcol/config.yaml3.2 Agent Harness 的 Span 埋点Agent Harness 的埋点要解决两个问题一是给每次 Agent 任务执行创建一个根 Span二是给每个工具调用创建子 Span 并正确设置父子关系。下面用 Python 的 OpenTelemetry SDK 写一个可插拔的埋点模块。核心思路是把埋点封装成一个 Tracer 类业务代码只调用start_agent_span和start_tool_span不直接依赖 OpenTelemetry API这样以后换观测后端只需要改这个模块。# harness_tracer.py import os 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 from opentelemetry.sdk.resources import Resource from opentelemetry.trace import SpanKind, Status, StatusCode class HarnessTracer: def __init__(self, service_nameNone): service_name service_name or os.getenv(OTEL_SERVICE_NAME, agent-harness) resource Resource.create({ service.name: service_name, agent.harness.pluggable: true, }) provider TracerProvider(resourceresource) exporter OTLPSpanExporter( endpointos.getenv(OTEL_EXPORTER_OTLP_ENDPOINT, http://localhost:4317), insecureTrue, ) provider.add_span_processor(BatchSpanProcessor(exporter)) trace.set_tracer_provider(provider) self.tracer trace.get_tracer(__name__) def start_agent_span(self, agent_name, task_id, attributesNone): attrs { agent.name: agent_name, agent.task_id: task_id, agent.type: orchestrator, } if attributes: attrs.update(attributes) return self.tracer.start_as_current_span( fagent.{agent_name}.execute, kindSpanKind.INTERNAL, attributesattrs, ) def start_tool_span(self, tool_name, tool_input, attributesNone): attrs { tool.name: tool_name, tool.input.size: len(str(tool_input)), tool.call.type: function, } if attributes: attrs.update(attributes) return self.tracer.start_as_current_span( ftool.{tool_name}.call, kindSpanKind.CLIENT, attributesattrs, ) def record_error(self, span, error): span.set_status(Status(StatusCode.ERROR, str(error))) span.record_exception(error)这个模块的可插拔体现在业务代码只依赖HarnessTracer的接口不直接 import OpenTelemetry。如果以后要换成其他观测后端只需要改HarnessTracer内部的 exporter 实现业务代码不动。3.3 工具调用的 Context 透传工具调用跨进程时Trace Context 必须通过 HTTP Header 透传否则下游服务生成的 Span 就是孤儿节点。OpenTelemetry 提供了TraceContextTextMapPropagator来做这件事。# tool_client.py import os import requests from opentelemetry import trace from opentelemetry.propagate import inject def call_tool_api(tool_name, payload): tracer trace.get_tracer(__name__) with tracer.start_as_current_span(ftool.{tool_name}.http) as span: headers {Content-Type: application/json} inject(headers) # 把 traceparent 注入到 headers span.set_attribute(http.url, f{os.getenv(TOOL_BASE_URL)}/{tool_name}) resp requests.post( f{os.getenv(TOOL_BASE_URL)}/{tool_name}, jsonpayload, headersheaders, timeout30, ) span.set_attribute(http.status_code, resp.status_code) if resp.status_code 400: span.set_status(trace.Status(trace.StatusCode.ERROR)) return resp.json()inject(headers)这一行是关键它会把当前 Span 的traceparent写入 HTTP Header。下游服务只要用同样的 Propagator 提取就能把 Span 挂到同一条 Trace 上。3.4 模型调用接入统一通道Agent Harness 里的模型调用走 TaoToken 统一通道配合 HTTP instrumentation 自动生成 Span。下面是一个调用示例Base URL 和 Key 从环境变量读取# model_client.py import os import requests from opentelemetry import trace def call_model(prompt, model_idNone): tracer trace.get_tracer(__name__) model_id model_id or os.getenv(TAOTOKEN_MODEL_ID) base_url os.getenv(TAOTOKEN_BASE_URL) api_key os.getenv(TAOTOKEN_API_KEY) with tracer.start_as_current_span(model.chat.completion) as span: span.set_attribute(model.id, model_id) span.set_attribute(model.provider, taotoken) resp requests.post( f{base_url}/v1/messages, headers{ x-api-key: api_key, anthropic-version: 2023-06-01, Content-Type: application/json, }, json{ model: model_id, max_tokens: 1024, messages: [{role: user, content: prompt}], }, timeout60, ) span.set_attribute(http.status_code, resp.status_code) return resp.json()这样模型调用的 Span 就和 Agent 执行、工具调用挂在同一条 Trace 上整条链路完整。4. 验证请求一次端到端 Trace 验证配置写完必须做一次端到端验证确认 Span 真的串起来了。验证分三步启动一个最小 Agent 任务、检查 Collector 日志、在 Jaeger 里看完整链路。4.1 启动最小验证任务写一个最小脚本模拟一次 Agent 任务主 Agent 执行、调用一个工具、再调用模型。# verify_trace.py import time from harness_tracer import HarnessTracer from tool_client import call_tool_api from model_client import call_model tracer HarnessTracer(service_nameagent-harness-verify) def run_task(): with tracer.start_agent_span(orchestrator, task-verify-001) as agent_span: agent_span.set_attribute(task.description, 端到端Trace验证) # 工具调用 with tracer.start_tool_span(order_query, {order_id: 12345}) as tool_span: result call_tool_api(order_query, {order_id: 12345}) tool_span.set_attribute(tool.result.count, len(result.get(items, []))) # 模型调用 model_resp call_model(总结订单状态) agent_span.set_attribute(model.response.length, len(str(model_resp))) time.sleep(2) # 等BatchSpanProcessor flush if __name__ __main__: run_task()运行前确保环境变量都设置好Collector 和 Jaeger 都在跑。python verify_trace.py4.2 检查 Collector 日志如果 Collector 配了debugexporter运行后应该能在日志里看到类似输出ResourceSpans #0 Resource SchemaURL: Resource attributes: - service.name: Str(agent-harness-verify) - agent.harness.pluggable: Str(true) ScopeSpans #0 ScopeSpans SchemaURL: InstrumentationScope __main__ Span #0 Trace ID : 4bf92f3577b34da6a3ce929d0e0e4736 Parent ID : ID : 00f067aa0ba902b7 Name : agent.orchestrator.execute Kind : Internal Attributes: - agent.name: Str(orchestrator) - agent.task_id: Str(task-verify-001) Span #1 Trace ID : 4bf92f3577b34da6a3ce929d0e0e4736 Parent ID : 00f067aa0ba902b7 ID : 00f067aa0ba902b8 Name : tool.order_query.call Kind : Client关键看两点Trace ID 是否一致Parent ID 是否正确指向父 Span。如果工具 Span 的 Parent ID 是空的说明 Context 没透传成功。4.3 在 Jaeger 里看完整链路打开 Jaeger UI按 service nameagent-harness-verify搜索应该能看到一条完整的 Trace结构如下agent.orchestrator.execute (agent-harness-verify) ├── tool.order_query.call (agent-harness-verify) │ └── tool.order_query.http (tool-service) └── model.chat.completion (agent-harness-verify)如果工具调用的下游服务也接了 OpenTelemetrytool.order_query.http这个 Span 会出现在下游服务的 service 下但 Trace ID 相同Jaeger 会自动拼在一起。验证成功的标志一条 Trace 里能看到 Agent 执行、工具调用、模型调用三个层级的 Span且父子关系正确没有孤儿节点。4.4 验证可插拔性可插拔的验证方法是把HarnessTracer的 exporter 从 OTLP 换成 ConsoleExporter业务代码不改重新运行Span 应该打印到控制台而不是发到 Collector。这证明观测模块和业务逻辑解耦成功。# 只改 harness_tracer.py 里的 exporter from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))业务代码verify_trace.py一行不动这就是可插拔观测的价值。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置和验证过程中最容易踩的坑集中在这几类报错逐个说清楚原因和修法。5.1 401 Unauthorized这个报错通常出现在模型调用环节原因是 API Key 没传对或者没传。检查三点环境变量TAOTOKEN_API_KEY是否设置成功请求头里是否带了x-api-keyKey 是否在控制台被禁用或删除。# 确认环境变量 echo $TAOTOKEN_API_KEY # 确认请求头 curl -v https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H Content-Type: application/json \ -d {model:$TAOTOKEN_MODEL_ID,max_tokens:10,messages:[{role:user,content:hi}]}如果 curl 能通但代码里 401多半是代码里 Key 读取逻辑有问题比如读了一个不存在的环境变量名。5.2 local proxy failed这个报错一般出现在 Collector 或 SDK 尝试连接 OTLP 端点时。原因是OTEL_EXPORTER_OTLP_ENDPOINT指向的地址不可达或者 Collector 没启动。检查 Collector 是否在跑docker ps | grep otel-collector # 测试端口连通性 nc -zv localhost 4317如果 Collector 在容器里SDK 在宿主机跑端点要填宿主机的 IP 而不是localhost。另外注意 gRPC 端点用 4317HTTP 用 4318填错端口也会报这个错。5.3 reading choices 相关报错这个报错通常出现在解析模型响应时原因是响应结构和你代码里假设的不一致。比如你按 OpenAI 的choices字段解析但实际返回的是 Anthropic 风格的content数组。修法是先打印原始响应确认结构再解析。resp call_model(test) print(resp.keys()) # 先看顶层字段如果是流式响应还要注意 SSE 格式的解析不能直接resp.json()。5.4 OAuth 相关报错如果 Agent Harness 里集成了需要 OAuth 的工具或服务报错通常是 token 过期或 scope 不足。检查 token 有效期和授权范围。对于模型调用本身TaoToken 用的是 API Key 而不是 OAuth所以模型调用不会出 OAuth 错误。如果工具调用链里有 OAuth 服务单独排查那个服务的 token 刷新逻辑。5.5 Span 断链排查如果 Jaeger 里看到孤儿 Span按这个顺序查工具调用的 HTTP Header 里有没有traceparent下游服务有没有用同样的 Propagator 提取Collector 的 pipeline 有没有把 traces 正确路由。最常见的是下游服务没配 Propagator导致提取失败。# 下游服务必须设置全局 Propagator from opentelemetry.propagate import set_global_textmap from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator set_global_textmap(TraceContextTextMapPropagator())5.6 三件套配置检查清单如果你用的是 Claude Code、Cline MCP 或 Codex 这类工具接入时确认三件套完整Base URL 填https://taotoken.net/apiKey 填创建的 API KeyModel ID 填对应模型标识。三者缺一不可少一个就会报连接或认证错误。Codex 的auth.json里同样需要这三项格式按工具要求填写。6. 接入 CTA把观测链路跑通到这里Collector 配置、Span 埋点、Context 透传、端到端验证都走完了。你现在应该有一条完整的 Trace从 Agent 执行到工具调用再到模型调用全部挂在同一个 Trace ID 下。下一步建议按这个顺序推进先把 API Key 和接入文档过一遍确认统一通道的调用方式然后在模型对话页面做一次最小连通性验证最后把 Coding Plan 接进你的 Agent Harness让长期编码任务的链路数据持续可观测。接入文档里有各语言的 SDK 示例和参数说明API Keys 页面管理你的 Key。模型对话适合快速验证模型是否通Coding Plan 适合长期跑 Agent 编排和编码任务的场景。观测模块的可插拔性验证完之后你可以尝试把 exporter 换成你实际用的后端业务代码不动这就是这套设计的价值所在。链路数据可复现、观测模块可替换多 Agent 编排的排查效率会明显不一样。