操作场景
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 字段为空时读取这些环境变量。export TENCENTCLOUD_SECRET_ID=<your-secret-id>export TENCENTCLOUD_SECRET_KEY=<your-secret-key>export CLS_DEFAULT_REGION=ap-guangzhouexport 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 编程模型,选择一种注册方式。
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 合计、工具调用次数和消息条数。
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 预留足够超时时间,以便等待流式回调采集和导出完成。相关文档
选择接入方式