对于实现 LoongSuite GenAI SemConv 的各类插桩库开发者而言，每个 GenAI 框架插桩都需要完成创建 Span、设置 SpanKind、挂载数十个 gen_ai.* 语义属性、按配置决定是否采集消息内容、处理异常并记录 Duration 和 Token Usage Metrics 等逻辑，样板代码高度重复。当规范升级时，每个插桩各自维护一套实现会导致升级成本成倍增长。
GenAI Utils 作为 LoongSuite GenAI SemConv 的工程化能力层，采用"分层解耦、统一收口"设计：插桩层只做数据提取，通过 Hook/Monkey-Patch 拦截框架调用，将数据填充到对应的 Invocation 数据对象；GenAI Utils 内部由 ExtendedTelemetryHandler 统一完成 Span 创建、属性挂载、Metrics 记录、Event 发送与 Context 管理。这样规范升级只需修改 Span Utils 和 Metrics 模块，所有下游插桩自动生效。
API 使用上遵循"填数据 + 交给 Handler"模型：获取 Handler 单例后，为每种操作选择对应的 InvokeAgent/ExecuteTool/Embedding 等 Invocation 类填入业务数据，再通过 Context Manager 完成遥测输出，无需直接操作 OTel API。
