AgentOps LiteLLM 集成实战多提供商 LLM 调用监控与可观测性指南【免费下载链接】agentopsPython SDK for AI agent monitoring, LLM cost tracking, benchmarking, and more. Integrates with most LLMs and agent frameworks including CrewAI, Agno, OpenAI Agents SDK, Langchain, Autogen, AG2, and CamelAI项目地址: https://gitcode.com/GitHub_Trending/ag/agentops本文基于仓库中examples/litellm/目录的官方示例README 与 litellm_example.py展开系统讲解如何用 AgentOps SDK 对 LiteLLM 的多提供商 LLM 调用进行自动插桩与监控从环境准备、API Key 配置、Trace 生命周期的完整代码走读到agentops.init()全参数解析、SDK 底层拦截机制以及仓库集成测试与手动测试脚本的验证方式。读完本文你可以直接复制运行仓库示例并理解 AgentOps 是如何在源码层面捕获 LiteLLM 的同步、流式与异步调用。一、背景LiteLLM 与 AgentOps 各解决什么问题LiteLLM 是一个统一接口库允许你用 OpenAI 格式调用 100 种 LLM包括 OpenAI、Llama、Mistral、Claude、Gemini、Gemma、DALL-E、Whisper 等。切换到不同模型时只需要修改 API Key 和litellm.completion(model...)中的 model 参数见 示例文件注释。AgentOps 则负责可观测性它会自动插桩instrumentLiteLLM 调用为性能、用量模式和模型行为提供洞察README 中 AgentOps Integration 一节。示例文件的头部注释还指出了一点LiteLLM 集成将可观测性扩展到了依赖 LiteLLM 的各类 agent 库使基于这些库构建的 agent 也能被观察。本仓库中这一点有源码佐证——smolagents 的插桩器直接包裹了smolagents.models中的LiteLLMModel.generate/LiteLLMModel.generate_streaminstrumentor.py并生成形如litellm.{operation} ({model_name})的 span 名称第 214 行。示例目录包含四个文件文件用途README.md前置条件、安装命令、示例说明litellm_example.py可运行的多提供商 LLM 访问示例litellm_example.ipynb同一示例的 Notebook 版本requirements.txt依赖清单仅包含litellmagentops与python-dotenv需在环境中另行安装示例注释中给出的安装命令为pip install -U litellm/pip install -U agentops/pip install -U python-dotenv二、前置条件与安装README 声明的运行环境约束与安装步骤如下Python 版本 3.10 3.13安装依赖pip install agentops litellm补充两个仓库内可查证的版本事实v1 文档docs/v1/integrations/litellm.mdx注明 AgentOps supportslitellm1.3.1集成测试的 VCR 录制夹具test_litellm_provider.yaml中请求头显示录制时的用户代理为litellm/1.58.1可以推断当前测试矩阵是在 litellm 1.58.x 上录制的。三、配置 API Key示例代码支持两种配置方式litellm_example.py 第 17–29 行环境变量方式推荐在.env文件或环境中设置AGENTOPS_API_KEYagentops.init()默认会读取该变量同时设置所选提供商的 key如OPENAI_API_KEY。参数直传方式把 key 替换后传给agentops.init(api_key...)。示例注释明确提醒不要将 API key 提交到公开仓库。示例采用的完整写法是先用python-dotenv加载.env再用os.getenv提供回退值import os from dotenv import load_dotenv load_dotenv() os.environ[AGENTOPS_API_KEY] os.getenv(AGENTOPS_API_KEY, your_api_key_here) os.environ[OPENAI_API_KEY] os.getenv( OPENAI_API_KEY, your_openai_api_key_here ) # or the provider of your choosing由于 LiteLLM 是多提供商门面v2 文档docs/v2/integrations/litellm.mdx给出了多提供商 key 的配置形态按实际使用的提供商设置对应变量即可export OPENAI_API_KEYyour_openai_api_key_here export ANTHROPIC_API_KEYyour_anthropic_api_key_here export AGENTOPS_API_KEYyour_agentops_api_key_here四、完整示例逐行解析以下是 litellm_example.py 的核心逻辑安装与 import 步骤省略import litellm import agentops agentops.init(auto_start_sessionFalse, trace_nameLiteLLM Example) tracer agentops.start_trace( trace_nameLiteLLM Example, tags[litellm-example, agentops-example], ) # 注意必须用 litellm.completion() 的模块级调用方式详见下一节 messages [{role: user, content: Write a 12 word poem about secret agents.}] response litellm.completion(modelgpt-4o-mini, messagesmessages) print(response.choices[0].message.content) agentops.end_trace(tracer, end_stateSuccess) # 编程化校验 span 是否被正确记录 try: agentops.validate_trace_spans(trace_contexttracer) print(Success! All LLM spans were properly recorded in AgentOps.) except agentops.ValidationError as e: print(fError validating spans: {e}) raise各步骤说明agentops.init(...)初始化 SDK 单例客户端。auto_start_sessionFalse表示不自动开启会话改为手动用start_trace管理trace_name指定默认 trace 的名称。从源码看agentops/init.py 第 141–146 行init()内部还会探测当前是否运行在 Jupyter NotebookZMQInteractiveShell中是则自动将auto_start_session置为False——这正是 Notebook 场景需要手动start_trace/end_trace的原因示例脚本与该行为保持一致。agentops.start_trace(trace_name..., tags...)开启一个新的 trace根 span并返回TraceContext支持多个并发、用户管理的 tracetags会附加到 trace span 上便于后续在控制台按litellm-example等标签检索start_trace 实现。litellm.completion(model..., messages...)一次普通的 LiteLLM 补全调用。AgentOps 会自动为其生成 LLM span无需显式埋点。agentops.end_trace(tracer, end_stateSuccess)结束 trace 并标记终态end_trace 实现。agentops.validate_trace_spans(trace_contexttracer)编程化自检。该函数与ValidationError异常在 agentops/validation.py 中定义并由包级 agentops/init.py 第 38 行 导出。示例用它验证 LLM 调用确实产生了 span适合写进 CI 或冒烟脚本。关键陷阱必须用litellm.completion()而不是from litellm import completion示例代码用整段注释强调了这一要求litellm_example.py 第 34–47 行# 错误AgentOps 无法拦截 from litellm import completion completion() # 正确AgentOps 可拦截 import litellm litellm.completion()原因是 AgentOps 通过包裹litellm模块上的函数来完成插桩from litellm import completion拿到的是原始未包裹的函数引用插桩会失效。v1 集成文档docs/v1/integrations/litellm.mdx也把这一点列为正式警告AgentOps requires a minor adjustment to how you call LiteLLM. This is because of other existing integrations that use thecompletionfunction.另需注意v2 文档docs/v2/integrations/litellm.mdx演示了另一条接入路径——通过 LiteLLM 自身的回调机制litellm.success_callback [agentops]挂接 AgentOps。两套写法分别来自 v1/v2 文档实际接入时以你所用 SDK 版本的文档为准仓库examples/litellm/目录给出的权威可运行示例采用的是litellm.completion()模块级调用方式。五、agentops.init()参数速查完整示例只用了两个参数但init()支持更多配置签名与文档字符串下表覆盖与 LiteLLM 场景相关的常用项参数说明 / 默认值api_keyAgentOps API Key不传则读取AGENTOPS_API_KEY环境变量endpoint服务端点不传则读取AGENTOPS_API_ENDPOINT默认https://api.agentops.aiapp_url控制台地址不传则读取AGENTOPS_APP_URL默认https://app.agentops.aimax_wait_time队列刷新前最长等待时间毫秒默认 5000max_queue_size事件队列最大长度默认 512default_tags会话/trace 默认标签用于分组排序旧参数tags已弃用传入会触发弃用告警trace_name默认 trace 名称缺省为defaultinstrument_llm_calls是否对 LLM 调用插桩并发出 LLM 事件auto_start_session客户端创建时是否自动开启会话auto_init是否在 import 时自动初始化客户端默认 Trueskip_auto_end_session不根据框架决策自动结束会话例如由 Crew 判断任务完成时机env_data_opt_out是否关闭环境数据采集log_level客户端日志级别默认CRITICALfail_safe出错时是否抑制异常并继续执行log_session_replay_url是否向控制台打印会话回放 URL默认 Trueexporter_endpoint导出器端点不传则读取AGENTOPS_EXPORTER_ENDPOINT此外agentops.configure(**kwargs)第 176–224 行允许在运行中更新上述大部分配置并对无效参数发出告警。六、底层机制AgentOps 从哪里拦截 LiteLLM 调用LiteLLM 以 OpenAI 兼容格式转发请求因此从源码结构看AgentOps 的 LLM 提供商插桩集中在 agentops/instrumentation/providers/openai/ 目录下其中 wrappers/ 子目录按 OpenAI 接口面拆分为chat.py、completion.py、embeddings.py、image_gen.py、responses.py另有stream_wrapper.py专门处理流式响应。插桩器与配置分别由 instrumentor.py 和 config.py 承载。这解释了第四节的调用方式约束只有litellm模块属性上的函数被包裹后litellm.completion()调用才会进入插桩路径。对于构建在 LiteLLM 之上的 agent 框架仓库同样提供了直接插桩。以 smolagents 为例instrumentor.py 第 96–97 行 用wrap_function_wrapper包裹smolagents.models模块的LiteLLMModel.generate与LiteLLMModel.generate_stream声明的依赖为smolagents 1.0.0与litellm第 67 行span 名称模板为litellm.{operation} ({model_name})。这与示例注释中LiteLLM 集成使依赖 LiteLLM 的 agent 库可被观察的说法相互印证。七、用仓库测试与手动脚本验证仓库为 LiteLLM 链路提供了三层验证手段集成测试tests/integration/test_llm_providers.py 第 287–307 行 的test_litellm_provider依次覆盖三类调用——同步completion、streamTrue的流式补全、异步acompletion正好对应生产代码中最常见的三种 LiteLLM 使用形态。夹具与录制tests/fixtures/providers.py 第 87–98 行 的litellm_client夹具会注入litellm.openai_key、litellm.anthropic_key、litellm.openrouter_key支撑多提供商测试对应的 VCR 录制文件为 tests/fixtures/recordings/test_litellm_provider.yaml其中还包含对x-litellm-api-key请求头的脱敏处理见 tests/fixtures/vcr.py 第 67 行。手动 Canary 脚本tests/core_manual_tests/providers/litellm_canary.py 是一个端到端手工验证脚本agentops.init(default_tags[litellm-provider-test])之后依次发起同步、流式、异步acompletion调用再调用agentops.stop_instrumenting()停止插桩并发起一次未追踪的completion调用最后end_session(end_stateSuccess)。脚本尾部注释说明其用途是验证一次会话只产生一个 LLM 事件。这个脚本是排查插桩是否生效、停止插桩后是否不再记录这类问题的现成模板。示例自带的agentops.validate_trace_spans自检见第四节则是日常开发中最轻量的验证方式。八、延伸阅读与文件索引官方 Notebook 版本示例examples/litellm/litellm_example.ipynbv1 集成文档含安装步骤与会话控制台观察指引docs/v1/integrations/litellm.mdxv2 集成文档含success_callback接法、流式与多提供商示例docs/v2/integrations/litellm.mdxSDK 入口与 Trace APIagentops/init.pyOpenAI 兼容面插桩实现agentops/instrumentation/providers/openai/smolagents/LiteLLM 框架级插桩agentops/instrumentation/agentic/smolagents/instrumentor.py集成测试与夹具tests/integration/test_llm_providers.py、tests/fixtures/providers.py注意事项小结Python 版本须落在 3.10–3.12调用必须使用import litellm后的模块级litellm.completion()写法以确保被插桩API key 一律走环境变量并避免入库多提供商场景下只需按提供商补充对应的 key 环境变量其余代码保持不变。【免费下载链接】agentopsPython SDK for AI agent monitoring, LLM cost tracking, benchmarking, and more. Integrates with most LLMs and agent frameworks including CrewAI, Agno, OpenAI Agents SDK, Langchain, Autogen, AG2, and CamelAI项目地址: https://gitcode.com/GitHub_Trending/ag/agentops创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考