[Agent Feature] Hook system in admin agent

[robocanic]

What would you like to be added:
Implement hook system in admin agent，like middleware in langchain, hooks in claude code, etc.
Based on the hook system, inject trace and expose to outer otel-trace compatible backend like jaeger, langfuse

Why is this needed:

[chaojixinren]

What would you like to be added:您希望添加什么内容呢： Implement hook system in admin agent，like middleware in langchain, hooks in claude code, etc.在管理代理中实现钩子系统，就像 LangChain 中的中间件、Claude Code 中的钩子功能一样。 Based on the hook system, inject trace and expose to outer otel-trace compatible backend like jaeger, langfuse基于该钩子系统，可以注入追踪信息，并将这些信息传递给诸如 Jaeger、Langfuse 之类的、与 otel-trace 兼容的后端系统。

Why is this needed:  为什么需要这样做呢：

[Design Proposal] Hook 系统 + OTel Trace 导出

动机

agent 的 ReAct 管线(Interact → runLoop → reasonAct/observe)目前是运行时黑盒:
没有交互级关联(只有散落的日志行)、没有模型/工具的延迟与 token 成本可见性、
超时和降级回退被静默处理。且即将到来的横切需求(trace、metrics、审计、护栏、#1503 鉴权)
都没有统一的接入点,只能各自硬编码进策略代码。

参照 LangChain middleware / Claude Code hooks:在 agent 循环周围建立稳定的事件边界,
消费方订阅事件而不侵入策略;第一个消费方是 OTel tracing,经 OTLP 导出到
Jaeger(基础设施视角)/ Langfuse(LLM 视角,支持 GenAI 语义约定)。

总体结构

flowchart LR
    subgraph loop["ReAct 执行循环"]
        A[Interact] --> B[runLoop / iteration]
        B --> C[stage: reasonAct]
        C --> D[模型调用]
        C --> E[工具调用 xN]
        B --> F[stage: observe]
        F --> G[模型调用]
    end

    loop -- "事件: Interaction / Iteration /<br/>Stage / ModelCall / ToolCall (Start+End)" --> HM[HookManager<br/>hooks 组件, YAML 配置]

    HM --> T[TracingHook<br/>OTel span + GenAI 语义约定]
    HM --> L[LoggingHook<br/>按 interaction id 关联]
    HM -.-> X[后续: metrics / 审计 / 拦截型护栏]

    T --> OTLP[OTLP exporter]
    OTLP --> J[Jaeger]
    OTLP --> LF[Langfuse]
    OTLP -.双后端同时导出.-> COL[OTel Collector 扇出]

Loading

Hook 分两层:观察型(MVP,只读回调,唯一允许的影响是 *Start 回调返回派生的 context.Context 以携带 span；回调中 ctx context.Context 只负责取消与链路传播，state *HookState 携带 interaction / iteration / stage / model / tool 等 Hook 状态，Hook 状态变量统一命名为 state；
panic 一律 recover,永不破坏 agent)+ 拦截型(post-MVP,仅在模型/工具两个动作点上
middleware 链式包裹,可改写/短路,留给护栏场景)。作为新的 hooks runtime 组件接入,
在 main.go registerFactorys 中注册于 agent 之前(初始化顺序由注册顺序决定,
e2e_test.go 的第二个注册点需同步),HookManager 在 AgentComponent.Init(rt) 中解析注入。

Tool Call Hook 支持按工具筛选：定义 Hook 时可指定一个或多个 tool name，MVP 先做精确匹配；tools: ["*"] 表示监听全部工具，空列表视为无效配置，避免默认语义不明确。HookManager 在分发前按 state.ToolName 过滤，未匹配的 Hook 不执行。

Span 层级与跨进程传播

flowchart TD
    FE[前端请求<br/>traceparent 提取, trace id 回传] --> R

    subgraph trace["一条 trace(每次交互)"]
        R["interaction (root)<br/>session.id · 累计 token 用量"]
        R --> I["iteration[n]"]
        I --> S1["stage: reasonAct"]
        S1 --> M1["model call<br/>gen_ai.request.* · gen_ai.usage.*"]
        S1 --> T1["tool: query_metrics<br/>gen_ai.tool.name · degraded 标记"]
        I --> S2["stage: observe"]
        S2 --> M2["model call<br/>fallback_used 标记"]
    end

    T1 -- "HTTP 头注入 traceparent" --> MCP[远程 MCP server<br/>如 #1499 诊断工具, 接续同一 trace]

Loading

关键点:

• Stage 事件是结构必需:reasonActStep 中模型调用先结束、工具才执行,
  没有横跨两者的 stage span,工具 span 就无法归属到发起它的推理阶段。
• 传播需要两处边缘改动（Hook 抽象本身无法单独完成）：① 将 agent.Agent.Interact 的签名改为显式接收 ctx context.Context。这里的 ctx 是 Go 标准上下文，不是 Hook 的 state；HTTP 入口从请求头提取 traceparent 后，通过 context.WithoutCancel(ctx) 向 Agent 传递 SpanContext 与 baggage，同时剥离请求取消和 deadline，使 Agent 生命周期与 SSE 连接解耦（不影响 #1502）。② MCP 客户端 sendRequest(ctx context.Context, ...) 使用 OTel propagator 将当前 SpanContext 注入出站请求的 traceparent/tracestate 头，使远程 MCP server 接续同一条 trace。
• 内容采集受 capture_content: none|truncated|full 策略约束(默认 none，内容采集需显式 opt-in),
  OTLP 鉴权只走环境变量;采样用 ParentBased(TraceIDRatioBased)。
• 生命周期:*End 事件一律 defer 保证(覆盖提前返回与 observe 超时 fallback 路径);
  交互 goroutine 增加 recover(现状 panic 会崩进程);hooks.Stop() 负责
  ForceFlush,保证关闭不丢 span。
• TracerProvider 由 hooks 组件唯一拥有;不依赖 Genkit 内部 span 的拓扑
  (跨版本不稳定),Genkit span 共享同一 TP 作为补充。

范围与拆分

• hook 核心:事件模型 + HookManager + 组件装配 + 接口变更
  (Interact/NewReActAgent/runLoop)+ 切入点埋事件 + LoggingHook。
  验收:各场景(无工具/多工具/降级/超时 fallback/panic)的精确事件序列单测、
  并发隔离测试、开销基准(hooks 关闭时热路径仅 nil 判断)。
• TracingHook:span 层级 + GenAI 语义约定 + OTLP 导出 +
  入站提取/出站注入 + trace id 回传前端 + flush 契约。
  验收:Jaeger(docker-compose,可进可选 CI)与 Langfuse(文档化手动步骤)
  各一次端到端验证。
• 后续补充:拦截型护栏、Prometheus 指标 hook、ToolRetry 事件。

延后项:用户身份属性(等 #1503)、应用内多 exporter(双后端推荐走 Collector)。

[chaojixinren]

如果觉得可行的话请分配给我这个任务@robocanic

[robocanic]

有两个点 @chaojixinren ：

1. 定义一个tool call hook时需要支持制定tool call(s)
2. hook的ctx换个名字，叫做state，尽量和context做区分

[chaojixinren]

有两个点 @chaojixinren ：

1. 定义一个tool call hook时需要支持制定tool call(s)
2. hook的ctx换个名字，叫做state，尽量和context做区分

收到，已按建议更新描述内容：

1. Tool Call Hook 支持在定义时指定一个或多个目标 Tool，HookManager 会根据 state.ToolName 进行匹配后再分发。
2. Hook 携带的运行状态统一命名为 state/HookState；ctx 仅用于表示 Go 的 context.Context，负责取消控制和 Trace 上下文传播。