资讯动态

使用 AgentOps 回调集成监控 LlamaIndex Agent:从安装、初始化到事件采集原理

发布时间:2026/9/12 13:16:14 来源:尧图企业网站定制
使用 AgentOps 回调集成监控 LlamaIndex Agent从安装、初始化到事件采集原理【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index导读llama-index-callbacks-agentops是 LlamaIndex 官方回调Callback集成包它将 LlamaIndex 的 Agent 工作流与 AgentOps 可观测平台打通只需一行初始化代码Agent 运行过程中的 LLM 调用、工具调用与异常就会被自动采集并上报到 AgentOps 仪表盘。读完本文你将掌握该包的安装方式、两种初始化姿势、init()全部可用参数以及事件采集的底层实现原理span/event 双处理器架构。安装该包以独立集成包的形式发布通过 pip 直接安装pip install llama-index-callbacks-agentops从 pyproject.toml 可以看到它的依赖与约束agentops0.2.2,0.3底层 AgentOps Python SDKllama-index-core0.13.0,0.15依赖 LlamaIndex 核心库提供的 instrumentation插桩框架要求Python 3.10,4.0当前包版本为0.5.0采用 MIT 协议。快速上手两种初始化方式方式一全局 Handler推荐利用llama_index.core提供的set_global_handler将 AgentOps 注册为全局回调处理器from llama_index.core import set_global_handler set_global_handler(agentops, api_key...)在核心库 global_handlers.py 中agentops分支会执行懒加载——只有在调用时才从llama_index.callbacks.agentops导入AgentOpsHandler并执行AgentOpsHandler.init(**eval_params)若包未安装则抛出 ImportError 并提示安装命令。这意味着api_key之外的所有关键字参数都可以通过set_global_handler原样透传。方式二直接初始化 Handler如果你希望更显式地控制处理器生命周期可以直接导入并初始化from llama_index.callbacks.agentops import AgentOpsHandler AgentOpsHandler.init(api_key...)该类的导出声明位于init.py同时它也被注册进 LlamaIndex 命令行映射见 mappings.json便于相关工具链识别。两种方式底层走的是同一条路径AgentOpsHandler.init()。init() 参数详解根据 base.py 中AgentOpsHandler.init()的方法签名可用的关键字参数如下参数类型默认值说明api_keyOptional[str]NoneAgentOps 平台 API Key用于身份认证parent_keyOptional[str]None父级 API KeyAgentOps 组织/账户层级扩展场景endpointOptional[str]None自定义上报端点用于自托管 AgentOps 或代理环境max_wait_timeOptional[int]None事件批量上报的最大等待时间秒级max_queue_sizeOptional[int]None上报队列的最大长度超出后的处理策略由 AgentOps SDK 决定tagsOptional[List[str]]None附加到会话的标签列表便于在仪表盘按标签过滤instrument_llm_callsboolTrue是否由 AgentOps SDK 额外插桩 LLM 调用inherited_session_idOptional[str]None继承已有会话 ID用于多进程/多服务串联同一会话init()内部会将这些参数构造为一个参数字典并过滤掉所有值为None的键后再传给 AgentOps 的AOClient因此任何 AgentOpsAOClient支持的参数都可以沿用同名关键字透传README 亦明确说明这一点。此外init()还强制注入了两个会话行为参数auto_start_sessionTrue初始化后自动开启会话skip_auto_end_sessionFalse不跳过会话自动结束逻辑即允许会话自动结束。也就是说只要调用了init()AgentOps 会话生命周期管理会自动开启无需额外手动调用。底层原理Span 与 Event 双处理器架构AgentOpsHandler继承自核心库的BaseInstrumentationHandler位于llama_index.core.instrumentation它本身不直接消费事件而是在init()时从根 dispatcher 获取分发器instrument.get_dispatcher()创建一对共享状态的处理器并注册AgentOpsSpanHandler继承SimpleSpanHandler负责 span 生命周期与异常关联AgentOpsEventHandler继承BaseEventHandler负责把 LlamaIndex 事件翻译成 AgentOps 事件并调用ao_client.record()上报。两者通过AgentOpsHandlerState一个 Pydantic 模型共享运行时状态该状态维护了四类映射span 是否源自 Agent 聊天is_agent_chat_span、Agent 聊天起始事件agent_chat_start_event、span 的父 spanspan_parent、span 内抛出的异常集合span_exception。Span 处理器异常捕获与上报AgentOpsSpanHandler在new_span时登记子 span 与父 span 的关联在prepare_to_exit_span时清理状态在prepare_to_drop_span时处理异常若当前 span 因异常被丢弃先尝试把异常关联到父 span避免父 span 重复上报子 span 已记录的异常若该异常尚未被记录则调用self._ao_client.record(ErrorEvent(detailsstr(err)))上报为 AgentOps 的ErrorEvent。事件处理器LLM 与工具调用映射AgentOpsEventHandler.handle()只处理 Agent 场景下的事件核心映射逻辑如下AgentRunStepStartEvent标记当前 span 为 Agent 聊天 span触发后续事件采集LLMChatStartEvent且处于 Agent 聊天 span 中缓存该事件的 span 关联供结束事件回溯模型名LLMChatEndEvent且处于 Agent 聊天 span 中把消息列表转换为{content, role}结构作为prompt把响应内容作为completion并从response.raw[usage]中提取prompt_tokens/completion_tokens再通过get_chat_start_event()沿祖先 span 链回溯到对应的 start 事件获取model字段最终构造LLMEvent上报AgentToolCallEvent将event.argumentsJSON 字符串反序列化为参数对象连同工具名构造ToolEvent上报。其中check_is_agent_chat_span()会沿span_parent链递归检查所有祖先 span判断某个事件是否处于 Agent 运行步骤之下get_chat_start_event()同样沿祖先链寻找最近的LLMChatStartEvent。这正是只采集 Agent 场景下 LLM 调用这一设计意图的实现细节。使用建议与注意事项Agent 场景限定从源码可见普通非 Agent的 LLM 调用不会被采集——LLMChatEndEvent只有在is_agent_chat_event为真时才上报。若你的业务是纯 RAG 问答而非 Agent 编排该集成可能无法覆盖所有调用。异常自动采集span 内抛出的异常会自动转为ErrorEvent上报无需手动 try/except 包装。版本配套包依赖llama-index-core0.13.0,0.15升级 LlamaIndex 核心库时请注意保持在该区间以免 instrumentation API 不兼容。自托管端点企业内部部署 AgentOps 时通过endpoint参数指定上报地址即可。相关文件索引集成包 README官方安装与初始化说明核心实现 base.pyAgentOpsHandler、Span/Event 双处理器与状态模型包导出init.py公开 API 面包配置 pyproject.toml依赖与版本约束全局 Handler 注册表set_global_handler(agentops, ...)的分发逻辑【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

读完文章,也想定制专属网站?

尧图设计师 24 小时内与您沟通定制方案

免费获取报价