帮你快速理解、总结文档立即下载

接入 Eino 数据

最近更新时间:2026-11-12 16:46:02
我的收藏

操作场景

Eino 是 CloudWeGo 开源的 Go 语言 AI 应用开发框架,Agent 运行时会产生多轮 ReAct 推理、模型调用、工具调用、向量检索、Embedding 和嵌套子 Agent 等数据。Agent 可观测(Agent Observability,AgentObs)可将这些数据统一采集并检索分析。在 Eino 应用中引入腾讯云 AgentObs SDK tencentcloud-agentobs-sdk-eino-go 后,只需将 SDK 提供的回调 Handler 注册到 ADK Runner、Graph / Chain / Workflow 或全局 callbacks,即可自动采集 Eino 回调数据,还原完整调用链路,并通过 OTLP/HTTP 协议将 Trace 上报到 腾讯云 AgentObs。产品能力介绍请参见 AgentObs 产品页,如需对比其他接入方式,请参见 选择接入方式。
接入完成后,您可以在 AgentObs 控制台查看以下信息:
每次用户请求的完整调用链,以及入口(entry)、Agent、推理轮次(Step)、模型调用、工具调用、检索、Embedding 和子 Agent 之间的父子关系。
模型调用的请求模型、请求参数(如 temperature、max_tokens)、输入/输出 Token、结束原因(finish_reason)、首 Token 延迟(TTFT)、耗时和输入/输出消息。
工具名称、调用参数、返回结果、耗时和错误信息。
由工具调起的子 Agent,以及多层嵌套关系。
同步调用与流式调用的完整链路。流式调用会记录 TTFT,流式内容在后台消费,不阻塞业务读写。
按会话(Session)和用户(User)聚合的多轮请求关联关系。
SDK 具有以下特点:
回调接入:以 Eino Callback Handler 方式接入,支持 ADK Agent(如 ChatModelAgent、Agentic Agent、嵌套 AgentTool)以及 Graph / Chain / Workflow。
自动合成推理轮次:为每轮模型调用合成 Step Span,工具调用按 tool_call_id 归属到发起该调用的轮次。
内容可控:支持关闭内容采集、自定义脱敏,并限制单个属性长度和单个 Span 的属性字节数。
退出前刷新:进程退出前调用 Shutdown,可结束入口 Span 并尽量将已采集数据发送出去。

前提条件

接入前,请确认已完成以下准备工作:
已准备具备写入权限的访问密钥(SecretId / SecretKey)。云 API 密钥信息请前往 API 密钥管理 获取,密钥需对目标主题有写入权限,权限模板参见 采集 AgentObs 数据。请使用最小权限的 CAM 子账号,不要将密钥写入代码。
已获取接入所需的地域(Region)或接入点。本 SDK 默认按地域拼接上报地址,请参见 地域和访问域名。以广州地域为例:
填写地域:ap-guangzhou。SDK 将使用公网地址 https://ap-guangzhou.cls.tencentcs.com/v1/traces。
若应用运行在腾讯云内网,可将 Intranet 设为 true,改用内网地址 https://ap-guangzhou.cls.tencentyun.com/v1/traces。
如需自定义接入点,可设置 Endpoint(未带路径时自动补全 /v1/traces)。设置 Endpoint 后无需再填写地域。
已基于 CloudWeGo Eino 开发应用,且应用可以正常运行。版本要求如下:
组件
支持版本
Go
1.23 及以上
CloudWeGo Eino
v0.9.x(SDK 当前依赖 github.com/cloudwego/eino v0.9.14)

步骤1:创建 AgentObs 应用

1. 进入 AgentObs 页面。
2. 单击应用接入,根据页面提示创建应用。
3. 在新创建的应用右侧单击编辑,复制 Trace 日志主题 ID。该 ID 用于后续配置中的 CLS_TOPIC_ID 或 Config.TopicID。同时记录应用所在地域,用于配置 CLS_DEFAULT_REGION 或 Config.Region。

步骤2:安装 SDK

在 Eino 项目目录执行以下命令:
go get github.com/TencentCloud/tencentcloud-agentobs-sdk-eino-go
并在代码中导入:
import agentobs "github.com/TencentCloud/tencentcloud-agentobs-sdk-eino-go"
说明:
安装命令会获取当前模块的最新版本。SDK 源码和官方示例请参见 tencentcloud-agentobs-sdk-eino-go。
请不要使用已废弃的内部模块路径。正确模块路径为 github.com/TencentCloud/tencentcloud-agentobs-sdk-eino-go。

步骤3:配置环境变量

建议通过环境变量注入地域、主题和密钥,避免把密钥写入代码。NewHandler 会在对应 Config 字段为空时读取这些环境变量。
macOS / Linux
Windows(PowerShell)
export TENCENTCLOUD_SECRET_ID=<your-secret-id>
export TENCENTCLOUD_SECRET_KEY=<your-secret-key>
export CLS_DEFAULT_REGION=ap-guangzhou
export CLS_TOPIC_ID=<your-topic-id>
$env:TENCENTCLOUD_SECRET_ID = "<your-secret-id>"
$env:TENCENTCLOUD_SECRET_KEY = "<your-secret-key>"
$env:CLS_DEFAULT_REGION = "ap-guangzhou"
$env:CLS_TOPIC_ID = "<your-topic-id>"
配置项
环境变量
是否必填
说明
Region
CLS_DEFAULT_REGION
未设置 Endpoint 时必填
CLS 地域,例如 ap-guangzhou。设置 Endpoint 后忽略该字段。地域与 Trace 日志主题须位于同一地域。
TopicID
CLS_TOPIC_ID
是
Trace 日志主题 ID,不要填写 AgentObs 应用 ID。
SecretID
TENCENTCLOUD_SECRET_ID
是
与 SecretKey 一起用于 HTTP Basic 鉴权。不要将密钥写入代码或提交到代码仓库。
SecretKey
TENCENTCLOUD_SECRET_KEY
是
与 SecretID 配对使用。
Endpoint
无
否
自定义上报地址。未带路径时自动补全 /v1/traces。默认仅接受 https;若使用 http,须同时设置 Insecure: true,且仅建议用于本地调试。URL 中不能包含用户名和密码。
Intranet
无
否
设为 true 时使用内网域名 {region}.cls.tencentyun.com,否则使用公网域名 {region}.cls.tencentcs.com。设置 Endpoint 时以 Endpoint 为准。
CrossRegion
无
否
跨地域上报时填写目标地域,SDK 会写入 x-cross-region 请求头。
ServiceName
无
否
资源属性 service.name,默认为 eino-agent。
Environment
无
否
部署环境,对应资源属性 deployment.environment.name。
Release
无
否
服务版本,对应资源属性 service.version。
SampleRate
无
否
按 Trace ID 采样,取值范围为 [0, 1]。默认值为 1。0 和 1 均会保留全部 Trace;(0, 1) 之间按比例采样。
DisableContentCapture
无
否
设为 true 时不采集消息内容、工具参数/结果和检索文档,仍保留 Token、耗时和各类 ID。
说明:
使用内置 CLS 导出器时,上报协议为 OTLP/HTTP(protobuf,gzip 压缩)。鉴权方式为 HTTP Basic(SecretId:SecretKey),并携带 topic_id 请求头。
单次导出请求超时默认 10 秒。更多高级配置(如内容脱敏 MaskFunc、属性长度限制、批处理队列、重试策略、自定义 TracerProvider)请参见仓库 README 中的配置说明。

步骤4:初始化采集

在运行任何 Agent 之前创建 Handler,并将其注册到 Eino 回调中。以下示例从环境变量读取密钥、地域和主题。
handler, err := agentobs.NewHandler(ctx, &agentobs.Config{
ServiceName: "customer-support-agent",
Environment: "production",
Release: "v1.4.0",
})
if err != nil {
log.Fatal(err)
}
defer func() {
shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
_ = handler.Shutdown(shutdownCtx)
}()
按您实际使用的 Eino 编程模型,选择一种注册方式。
ADK Agent
Graph / Chain / Workflow
全局注册
agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
Name: "support",
Description: "answers customer questions",
Model: chatModel,
})
if err != nil {
log.Fatal(err)
}
runner := adk.NewRunner(ctx, adk.RunnerConfig{Agent: agent, EnableStreaming: true})

// 每个用户请求(一个 turn)调用一次 StartTrace。
traceCtx := handler.StartTrace(ctx,
agentobs.WithSessionID("conversation-42"),
agentobs.WithTurnIndex(3),
agentobs.WithUserID("user-1001"),
agentobs.WithEntryType("api"),
)
events := runner.Query(traceCtx, "Where is my order?", adk.WithCallbacks(handler))
for {
event, ok := events.Next()
if !ok {
break
}
if event.Err != nil {
log.Printf("agent error: %v", event.Err)
continue
}
if output := event.Output; output != nil && output.MessageOutput != nil {
if _, err := output.MessageOutput.GetMessage(); err != nil {
log.Printf("read message: %v", err)
}
}
}
// 传空字符串时,最终回答取 Agent 输出。
handler.EndTrace(traceCtx, "")
chain, err := compose.NewChain[[]*schema.Message, *schema.Message]().
AppendChatModel(chatModel).
Compile(ctx, compose.WithGraphName("qa"))
if err != nil {
log.Fatal(err)
}
traceCtx := handler.StartTrace(ctx, agentobs.WithUserID("user-1001"))
defer handler.EndTrace(traceCtx, "")
if _, err := chain.Invoke(traceCtx, []*schema.Message{schema.UserMessage("hi")}, compose.WithCallbacks(handler)); err != nil && !errors.Is(err, context.Canceled) {
log.Printf("invoke: %v", err)
}
callbacks.AppendGlobalHandlers(handler)
全局注册后,无需在每次调用时传入 WithCallbacks。请仍在进程退出前调用 handler.Shutdown。
注意:
进程退出前必须调用 Shutdown。该方法会结束仍未关闭的入口 Span、等待流式回调采集完成,并关闭 SDK 自建的 TracerProvider。若使用外部 TracerProvider,Shutdown 只会对其执行 ForceFlush,不会关闭该 Provider。
使用 ADK 时,调用方必须把事件迭代器(如 events.Next())消费完,对应的 Agent Span 才会结束。
最外层 Graph / Chain / Workflow 默认会作为 Agent Span。如需关闭该行为,可将 DisableGraphAsAgent 设为 true。

步骤5:关联会话与用户(推荐)

建议为每一次用户请求调用一次 StartTrace,并在请求结束后调用 EndTrace。StartTrace 会创建入口 Span(enter_application),请将返回的 context 传给后续 Eino 调用。
也可以不调用 StartTrace:此时不会生成入口 Span,最外层 Agent 作为根 Span,会话 ID 和轮次 ID 默认取 Trace ID。
选项
说明
WithSessionID
设置 gen_ai.session.id。未设置时默认取 Trace ID。也可在 Config.SessionID 中设置默认值,请求级选项优先。
WithTurnID
直接设置 gen_ai.turn.id。一旦设置,将忽略 WithTurnIndex。
WithTurnIndex
当未设置 WithTurnID,且索引大于 0 时,生成 {sessionID}:t{index}。请使用您在会话内可稳定递增的值,例如用户消息序号。
WithUserID / WithUserName
设置用户 ID 和用户名。也可在 Config.UserID、Config.UserName 中设置默认值。
WithEntryType
设置入口类型,例如 api、cli 或 im。默认值为 sdk。
WithInput / WithInputMessages
写入入口 Span 的输入。未设置时,SDK 会使用首次观察到的 user 消息。
WithAttributes
为该 Trace 下的所有 Span 添加自定义字符串属性(例如 git.repo)。以 gen_ai. 或 eino. 开头的键会被忽略。
WithTraceID
指定 32 位十六进制 Trace ID。仅在使用 SDK 自建 TracerProvider 时生效;若传入外部 TracerProvider,Trace ID 由该 Provider 的 IDGenerator 决定。
未设置 WithTurnID 且 WithTurnIndex 未大于 0 时:若会话 ID 等于 Trace ID,则轮次 ID 等于 Trace ID;否则轮次 ID 为 {sessionID}:{traceID}。Step ID 格式为 {turnID}:s{n},轮次序号从1开始。
EndTrace(ctx, output) 用于写入最终回答并结束入口 Span。output 传空字符串时,优先使用最外层 Agent 的输出,其次使用最后一次模型输出。该方法重复调用是安全的,会保留第一次非空输出。入口 Span 也会在原始 context 结束且子回调全部完成后,或在 Shutdown 时结束。

步骤6:运行 Agent 并验证结果

1. 运行一次包含模型调用的 Agent 任务。建议同时触发一个工具调用,以便检查完整调用树。
2. 登录 AgentObs 页面。
3. 进入步骤1中创建的应用。
4. 打开调用链页面,选择包含测试请求的时间范围。
5. 打开最新 Trace,检查是否包含 entry、Agent、Step、Chat、Tool、Retriever 或 Embedding 等 Span。
6. 选择具体 Span,检查其耗时、状态、输入输出、Token 用量和模型请求参数等数据。
说明:
数据为异步批量导出,默认未满一批时最长等待 5 秒。测试后请稍候再查询;如需尽快看到数据,可在验证前调用 handler.Flush(ctx)。
进程退出前请调用 Shutdown,否则部分 Span 可能尚未导出。

采集数据说明

Span 层级与采集属性

SDK 会把一次 Eino 运行映射为如下调用树(默认会丢弃 Lambda、ToolsNode 等框架节点,其子 Span 挂到最近一个保留的父 Span 上;如需保留框架节点,将 IncludeFrameworkSpans 设为 true,其 gen_ai.span.kind 为 task):
entry (enter_application) StartTrace / EndTrace
└── agent (invoke_agent) ADK Agent,或最外层 Graph / Chain
├── step (react) 每轮 ReAct 合成一个
│ ├── chat (chat) ChatModel / AgenticModel
│ └── tool (execute_tool)
│ └── agent (invoke_subagent) 由 tool 调起的子 Agent
└── retriever / embedding
主要采集内容包括:
身份与上下文:会话 ID、轮次 ID、Step ID、用户信息、入口类型、Agent 名称与类型(默认 eino)。嵌套在其他 Agent 内的 Agent 会标记为 invoke_subagent。
模型调用:请求模型与参数、输入/输出消息、Token 用量(含 0 值,便于聚合)、结束原因、TTFT 和耗时。流式调用的 TTFT 取首个 chunk 的时间;非流式调用取拿到响应的时间。失败或取消且 Provider 未给出原因时,finish_reasons 分别为 ["error"] 或 ["cancelled"]。
工具与检索:工具名称、调用 ID、参数、结果、错误信息;检索查询、Top K、文档及文档数量(关闭内容采集时仍写入数量)。
Agent 汇总:该 Agent 及其子 Agent 的 Token 合计、工具调用次数和消息条数。
更完整的字段定义请参见 Agent Trace 字段定义说明。

Trace 采样

SampleRate 按 Trace ID 采样,取值须在 [0, 1] 之间,超出范围时 NewHandler 会返回错误。默认值为 1。0 和 1 均保留全部 Trace;例如设置为 0.1 时,大约每 10 条 Trace 保留 1 条。未被采样的 Span 会计入丢弃日志中的 sampled_out_spans。

内容采集与脱敏

将 DisableContentCapture 设为 true 后,不再采集消息内容、工具参数/结果和检索文档,仍保留 Token、耗时和 ID。
可通过 MaskFunc 在导出前对采集到的内容做脱敏,脱敏发生在长度截断之前。
MaxAttributeValueLength 默认 256 KiB,MaxSpanAttributeBytes 默认 1,000,000 字节。设为负数表示不限制。截断后的 JSON 仍保持合法。

错误归属

失败的 Chat、Tool 等 Span 会标记为 ERROR;Chat 失败时,它所在的 Step 也会标记为 ERROR。
只有最外层 Agent 失败,或 Agent 之外的组件失败时,入口 Span 才会标记为 ERROR。内层 Agent 失败后如果被外层恢复,不影响入口 Span。
context.Canceled 记为 eino.status=cancelled,中断/恢复记为 interrupted,这两种情况不设 ERROR 状态。
ADK 的 WillRetryError 只记录在 eino.retry.events 中,不算失败。

注意事项

不要把密钥写进代码或日志。配置校验失败时,错误信息中不会包含密钥。
Endpoint 默认只接受 HTTPS。仅在本地调试时才可设置 Insecure: true 以使用 HTTP。
必须把 ADK 事件迭代器消费完,Agent Span 才会结束。
部分模型若未上报 model.CallbackInput,Trace 中可能缺少 gen_ai.request.model、gen_ai.tool.definitions 以及 temperature 等请求参数。Eino 为未实现回调的模型自动注入的回调通常只带 messages。eino-ext 中的模型实现一般会上报,自定义模型请自行确认。
WithTraceID 仅在使用 SDK 自建 TracerProvider 时生效。
遥测数据不会被悄悄丢弃。采样、队列已满、属性截断或导出失败等情况,会按 DropLogInterval(默认 1 分钟)汇总输出日志。导出最终失败时会立即打印该批次的 Span 数量。如需查看请求体大小和各网络阶段耗时,可开启 ExportDiagnostics;诊断信息不会包含请求头、凭证、Span 内容或 Trace ID。
SDK 通过 Eino 回调采集数据,回调接口返回的是 context,不会把上报异常作为业务错误返回。NewHandler 在配置缺失或非法时会返回错误,请在启动阶段处理。网络或服务端异常时,SDK 会按重试策略缓冲并重试,最终失败会输出日志。

常见问题

NewHandler 返回 CLS topic ID / credentials / region is required

说明内置 CLS 导出器所需配置不完整。请确认已设置 CLS_TOPIC_ID(或 Config.TopicID)、TENCENTCLOUD_SECRET_ID / TENCENTCLOUD_SECRET_KEY(或 Config.SecretID / Config.SecretKey)。未自定义 Endpoint 时,还须设置 CLS_DEFAULT_REGION 或 Config.Region。

AgentObs 中没有 Trace 数据

请按以下顺序检查:
1. 确认在运行 Agent 之前已成功调用 NewHandler,并已通过 adk.WithCallbacks、compose.WithCallbacks 或 callbacks.AppendGlobalHandlers 注册 Handler。
2. 确认 CLS_DEFAULT_REGION(或 Endpoint)与 Trace 日志主题位于同一地域。
3. 确认 CLS_TOPIC_ID 为日志主题 ID,而不是 AgentObs 应用 ID。
4. 确认访问密钥具备目标日志主题的写入权限。
5. 确认运行环境能够访问对应接入点。内网地址仅在腾讯云 VPC 等内网环境可用。
6. 使用 ADK 时,确认已完整消费事件迭代器,并在请求结束后调用了 EndTrace。
7. 确认进程退出前调用了 Shutdown,或在查询前调用了 Flush。数据为异步批量导出,请等待至少一个刷新周期再查询。

AgentObs 中只有部分对话的 Trace

检查 SampleRate 是否设置在 (0, 1) 之间。0 和 1 都会保留全部 Trace。也可查看日志中是否出现 sampled_out_spans 或 queue_full_spans。

Trace 中缺少输入输出或工具参数

检查是否将 DisableContentCapture 设为了 true,以及 MaskFunc 是否过滤了相关内容。关闭内容采集不会影响调用树、Token、耗时和状态等数据的上报。

Trace 中缺少模型名称、temperature 等请求参数

请确认所使用的模型组件是否在回调中上报了 model.CallbackInput。Eino 为未实现回调的模型自动注入的回调通常只包含 messages,此时可能缺少 gen_ai.request.model、temperature 和 gen_ai.tool.definitions 等字段。

Agent Span 一直不结束

使用 ADK 时,必须把 Query / Run 返回的事件迭代器完整消费完,Agent Span 才会结束。请确认循环调用了 events.Next() 直到返回 false,并且流式消息(如 GetMessage())也被读取完成。

NewHandler 报错 http CLS endpoint requires Config.Insecure

自定义 Endpoint 使用了 http://,但未设置 Insecure: true。生产环境请改用 https;仅本地调试才可开启 Insecure。

进程退出后日志出现 processor_stopped_spans

说明有 Span 在 Shutdown 之后才结束。请确保业务请求完成后再调用 Shutdown,并为 Shutdown 预留足够超时时间,以便等待流式回调采集和导出完成。

相关文档