AgentOps

AgentOps 快速入门

给 AI Agent 装上”行车记录仪”——两行代码接入，每次 LLM 调用、工具执行、Agent 对话全记录，还能回放复盘。

这是什么？适合谁？

AgentOps 是一个AI Agent 可观测性平台。它要解决的核心问题是：当你的 AI Agent 在跑的时候，你根本不知道它每一步做了什么、在哪一步出错、钱花在哪了。AgentOps 就像一个”行车记录仪 + 黑匣子”，把它接入你的 Agent 代码后，每次 LLM 调用、工具执行、Agent 间对话都会自动记录下来，上传到可视化 Dashboard。

从技术角度看，AgentOps 提供了一套Python SDK，通过 agentops.init() 两行代码即可接入。接入后它会自动拦截 OpenAI、Anthropic、CrewAI、AutoGen、LangChain、LlamaIndex 等 400+ LLM 和框架的 API 调用，不需要你手动埋点。记录下来的数据包括：每个 LLM 请求的 prompt/response、token 消耗、延迟、错误堆栈、工具调用参数与返回值，甚至 prompt injection 攻击记录。

核心能力：

• 事件可视化：Dashboard 上以时间线展示每个 Session 的全链路事件，谁调了谁、花了多少钱、哪里报错一目了然。
• Time Travel Debugging（时间旅行调试）：可以回放任意一个历史 Session 的完整执行过程，精确到每一步的状态——就像看监控录像一样定位 bug。
• 审计日志：完整的操作记录，适合企业合规和团队协作场景。
• 错误追踪：自动捕获异常并关联到具体的 LLM 调用或工具执行，快速定位根因。
• Prompt Injection 记录：自动检测并记录可疑的 prompt injection 攻击事件。

适合谁？如果你在用 CrewAI、AutoGen、LangChain 等框架做 Agent 开发，想快速看清 Agent 内部发生了什么而不想自己搭监控；如果你是初创团队或个人开发者，需要在有限的预算内获得专业级的 Agent 可观测性；如果你需要向客户或老板展示 Agent 的运行情况，Dashboard 的可视化非常直观。

不适合谁？如果项目对数据隐私有极高要求（所有事件数据上传到 AgentOps 云端），需要私有化部署的可以考虑 LangSmith Self-Hosted 或自建方案；如果每月事件量远超 5,000 次且预算紧张，Pro $40/月可能不够用，超量后需要 Enterprise 定制。

准备工作

开始之前，请准备以下几样：

1. Python 3.9 及以上版本：AgentOps Python SDK 兼容性很好，PyPI classifiers 已列出 3.9-3.13。访问 https://www.python.org/downloads/ 安装。
2. AgentOps API Key：去 https://app.agentops.ai 注册账号（免费），在 Dashboard → Settings 里找到你的 API Key。
3. 大模型 API Key：AgentOps 本身不调用模型，但它需要监控你的 LLM 调用。准备好 OpenAI / Anthropic / DeepSeek 等你正在用的模型 key。
4. 一个已有的 Agent 项目（可选）：如果你已经有 CrewAI / AutoGen / LangChain 项目，改两行代码就能接入；如果没有，本文会提供一个最小示例。

3 步快速上手

第 1 步：安装 AgentOps

打开终端，在虚拟环境里安装：

pip install agentops python-dotenv

agentops 是核心 SDK，python-dotenv 用来管理 .env 文件里的 API Key（推荐方式，避免把 key 写死在代码里）。

安装完成后验证：

python -c "import agentops; print(agentops.__version__)"

第 2 步：拿到 API Key 并初始化

在项目根目录创建 .env 文件：

AGENTOPS_API_KEY=your-api-key-here
OPENAI_API_KEY=«redacted:sk-…»

然后写一个最小示例 hello_agentops.py：

import os
from dotenv import load_dotenv
load_dotenv()

import agentops

# 第 1 行：导入 agentops
# 第 2 行：初始化（自动读取 AGENTOPS_API_KEY 环境变量）
agentops.init(tags=["quickstart"])

# 这之后的 LLM 调用都会被自动追踪
from openai import OpenAI
client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "你是一位简洁的助手。"},
        {"role": "user", "content": "用一句话解释什么是 AI Agent？"},
    ],
)

print(response.choices[0].message.content)

# 结束 session，确保数据全部上传
agentops.end_session("Success")

这就是最小的接入方式：两行代码（import agentops + agentops.init()），之后所有 OpenAI 调用自动被追踪。tags=["quickstart"] 帮你在 Dashboard 里快速找到这次测试。

第 3 步：跑起来并查看 Dashboard

python hello_agentops.py

运行后，打开 https://app.agentops.ai，你会看到：

• 一个新 Session 出现在列表里，标签是 quickstart
• 点进去可以看到这次 Session 的完整时间线：LLM 调用的 prompt、response、token 消耗、延迟
• 如果代码里发生了异常，Dashboard 会自动标红高亮

如果 Dashboard 里没看到数据，检查：

1. AGENTOPS_API_KEY 是否正确（在终端里 echo $AGENTOPS_API_KEY 确认）
2. agentops.init() 是否在 LLM 调用之前执行
3. 网络能否访问 api.agentops.ai

常见踩坑

1. 「装好了但 Dashboard 看不到数据」：最常见的原因是 agentops.init() 放在了 LLM 调用之后，或者 end_session() 没调用就退出了程序。确保 init 在最前面，程序结束前调用 end_session()。
2. 「Token 双重计费」：AgentOps 的记录本身不会额外消耗 LLM token，但你看见的 token 统计包含了你原始 LLM 调用的消耗——那不是 AgentOps 收的钱，是你付给 OpenAI/Anthropic 的钱。
3. 「免费层 5,000 events 用完了」：一个 event 不是一次 LLM 调用，而是一个追踪单元（一次 LLM call、一次 tool call、一个 span 都算 event）。一个复杂的 Agent Session 可能产生几十上百个 events，免费额度要省着用。建议先在简单 Agent 上测试，确认配置正确后再跑复杂任务。
4. 「CrewAI 集成没生效」：AgentOps 对 CrewAI 的自动追踪需要 agentops.init() 在 from crewai import ... 之前执行。如果你先 import 了 CrewAI 才 init AgentOps，自动追踪会失效。正确顺序：先 agentops.init()，再 from crewai import Agent, Task, Crew。
5. 「敏感数据上传到了云端」：AgentOps 默认会记录 LLM 的 prompt 和 response 内容。如果你的 prompt 里有用户的 PII（电话号码、身份证等），需要在 agentops.init() 里配置 auto_start_session=False 或开启数据脱敏（Enterprise 功能）。
6. 「国内服务器访问 AgentOps 很慢」：AgentOps 的服务器在海外，国内访问可能有延迟。数据上传是异步的，不会阻塞你的 Agent 执行，但 Dashboard 加载可能较慢。如果影响使用，可以考虑 LangSmith 或自建 LangFuse。

初级用法

• 监控 CrewAI 团队：在你的 crew = Crew(...) 前面加两行 import agentops; agentops.init()，每个 Agent 的思考过程、工具调用、最终输出都会自动记录。
• 监控 AutoGen 对话：同样两行代码，AutoGen 的 Agent 间对话轮次、代码执行结果、LLM 调用全部可视化。
• 手动记录自定义事件：用 @agentops.record_action 装饰器标记你自己的函数，AgentOps 会自动记录函数名、参数、耗时和返回值。

@agentops.record_action("fetch_user_data")
def fetch_user_data(user_id: str):
    # 这个函数的调用会自动出现在 Dashboard 上
    return {"user_id": user_id, "name": "Alice"}

• 给 Session 打标签：agentops.init(tags=["production", "v2.1"]) 方便在 Dashboard 里按标签筛选，区分测试环境和生产环境。

高级玩法

• Time Travel Debugging 实战：在 Dashboard 里打开任意一个历史 Session，进入 Replay 模式，可以像播放视频一样查看每一步的执行——包括 LLM 的流式输出回放。对于”偶发性 bug”排查特别有用：复现当时的状态，看 Agent 到底在那一刻看到了什么。
• 自定义 Span 层级：用 agentops.start_span() / agentops.end_span() 构建多层级的追踪树，比 record_action 更灵活，适合复杂工作流。
• 接 MCP Server：AgentOps 提供了 MCP Server，可以把 trace 数据直接接入你的 MCP 客户端（如 Claude Desktop、Cursor），在对话中分析 Agent 执行日志。
• 集成到 CI/CD：在自动化测试脚本里初始化 AgentOps，每次 CI 跑完自动生成 Agent 执行报告，把 Agent 质量也纳入 CI 检查项。
• 多项目隔离：通过不同的 AGENTOPS_API_KEY（对应不同的 Project），可以在一个团队内隔离不同产品的 Agent 监控数据。

小技巧

1. 默认关掉 auto_start_session：agentops.init(auto_start_session=False)，然后在你真正需要监控的代码段手动 agentops.start_session()。避免在开发和调试阶段浪费免费额度。
2. tags 用得好省时间：给不同环境打不同标签（["dev"]、["staging"]、["prod"]），Dashboard 里一键切换视图，不用翻找。
3. 结合 end_session 的状态码：agentops.end_session("Success") / agentops.end_session("Fail") / agentops.end_session("Indeterminate")，Dashboard 里会自动按状态分类，快速定位失败 Session。
4. 善用 record_action 的 name 参数：@agentops.record_action("semantic_search_v2") 比默认的函数名更易读，尤其在 Dashboard 里排查问题时。
5. 注意 import 顺序：agentops.init() 必须在所有你希望自动追踪的框架 import 之前执行。建议把 agentops.init() 放在文件的最顶部，紧跟环境变量加载。

参考链接

• AgentOps 官方网站
• AgentOps 官方文档
• AgentOps Quickstart
• AgentOps GitHub 仓库
• AgentOps Python SDK (PyPI)
• AgentOps 集成示例