1. 项目定位与目标

AgentOps 是一个面向 AI Agent 的可观测性（Observability）与开发工具（DevTool）平台，致力于把 AI Agent 从原型阶段推进到生产阶段。最新发布版本为 0.4.21，社区持续活跃（见仓库 README 中的徽章与下载统计）。资料来源：README.md:1-50

平台在 README 的 Why AgentOps 部分明确指出其使命：在没有合适工具时，AI Agent 通常"速度慢、成本高、不可靠"，因此需要统一的会话重放（Session Replays）、事件延迟分析、Honeypot 与 Prompt Injection 检测（接入 PromptArmor）、API 计费跟踪以及多 Agent 框架可视化等能力。资料来源：README.md:18-36

整个项目是一个 monorepo，根目录同时托管 Python SDK（顶层 agentops/ 包）和完整的 Web/Dashboard 应用（app/ 子目录），并提供针对 LangChain、CrewAI、Gemini、Google ADK、OpenAI Agents、SmolAgents、watsonx、LiteLLM 等多种框架的接入示例。资料来源：examples/README.md:23-45, README.md:60-130

2. 顶层架构

2.1 系统组件概览

下图描述了 AgentOps 的整体组件划分与数据流向：客户端 SDK 采集 Span/事件 → 后端 API（opsboard + 指标模型）→ 数据库（Supabase / ClickHouse）→ 仪表盘（Next.js）。

flowchart LR
    subgraph Client["Python SDK (agentops/)"]
        DEC["@session / @agent\n@operation / @task / @workflow"]
        INSTR["Instrumentation\n(OpenTelemetry based)"]
        API["API Client\n(base.py / types.py)"]
    end
    subgraph Backend["后端服务 (app/)"]
        OPS["Opsboard API\n(FastAPI)"]
        METRICS["Metrics Models\n(metrics.py)"]
        SUPA["Supabase\n(Auth + Postgres)"]
    end
    subgraph Web["Web 应用"]
        DASH["Dashboard\n(Next.js App Router)"]
        HAND["Engineering Handbook"]
    end
    DEC --> INSTR
    INSTR --> API
    API --> OPS
    OPS --> METRICS
    OPS --> SUPA
    DASH --> OPS
    DASH --> SUPA

2.2 Monorepo 目录约定

app/README.md 描述了集中化的开发配置：根目录的 package.json 与 requirements-dev.txt 统一托管 ESLint、Prettier、TypeScript、Husky、Ruff 等工具链，子项目（dashboard/、api/、landing/）各自维护运行时依赖。资料来源：app/README.md:9-50

examples/README.md 进一步说明了示例目录的约定：每个集成框架一个子目录（如 langchain/、crewai/、openai_agents/、gemini/、google_adk/、smolagents/、watsonx/、litellm/），并通过 generate_documentation.py 把 Jupyter Notebook 自动转换为网站文档（docs/v2/examples/）。资料来源：examples/README.md:23-66

3. Python SDK 核心架构

3.1 装饰器驱动的追踪 API

SDK 提供了五个高层装饰器，构成 span 嵌套层次结构：

每个装饰器都支持输入/输出记录、异常处理以及 async/await 函数；可以互相嵌套以构建正确的 span 层级。资料来源：README.md:108-152

3.2 Instrumentation 与 OpenTelemetry

针对 OpenAI Agents 等框架的 instrumentor 是 SDK 的核心扩展点。以 agentops/instrumentation/agentic/openai_agents/README.md 为例，它定义了：

• Span 类型：Trace（根 span）、Agent（SpanKind.CONSUMER）、Function（SpanKind.CLIENT）、Generation、Response、Handoff。
• 属性提取器：attributes/ 子模块按职责拆分（completion.py 处理三种 API 格式、model.py 抽取模型参数、tokens.py 统计 token、response.py 解析 Response 对象）。
• 生命周期管理：exporter 仅在 Start 事件时创建 span 并放入跟踪字典，End 事件时查找已有 span 并手动结束；已结束的 span 会被跳过以避免重复。资料来源：agentops/instrumentation/agentic/openai_agents/README.md:1-90

这种 OpenTelemetry 兼容的设计使 SDK 可以与现有的 trace 后端和可视化工具协作。

3.3 API 客户端

agentops/client/api/base.py 定义了 BaseApiClient，封装了 HTTP 请求、Header 构造（含 User-Agent: agentops-python/<version>）与异步调用协议；agentops/client/api/types.py 则使用 TypedDict 描述常见响应（如 AuthTokenResponse 包含 token 和 project_id，UploadedObjectResponse 包含 url 和 size）。资料来源：agentops/client/api/base.py:1-80, agentops/client/api/types.py:1-20

4. 后端服务与 Dashboard

4.1 Opsboard 后端

app/api/agentops/opsboard/README.md 说明 Opsboard 是基于 FastAPI 的模块，负责用户/组织/项目的管理。技术栈包括 FastAPI（自动生成 OpenAPI 文档）、SQLAlchemy ORM、Pydantic 校验，以及认证模块。文件结构按职责拆分：app.py（应用与中间件）、environment.py、models.py、routes.py、schemas.py，以及 views/ 下的 users.py / orgs.py / projects.py。资料来源：app/api/agentops/opsboard/README.md:1-50

权限模型支持 owner/admin/developer/business_user 四种角色，项目可配置为 production、staging、development、community 等环境。

4.2 指标聚合

app/api/agentops/api/models/metrics.py 中的 ProjectMetricsDurationModel 提供了项目级聚合指标：min_duration、max_duration、avg_duration、total_duration、span_count、trace_count 以及时间窗口。所有数值字段都通过 ensure_int 验证器保证为整数，以避免空值导致的类型错误。资料来源：app/api/agentops/api/models/metrics.py:1-70

4.3 Dashboard 与 Span 解析

app/dashboard/README.md 描述了基于 Next.js App Router 的前端：app/(with-layout)/ 共享主布局；components/ui/ 使用 shadcn-ui 基础组件；hooks/ 提供 useMetrics、useTraces 等数据获取钩子。资料来源：app/dashboard/README.md:24-40

Dashboard 端通过 app/lib/span-utils.ts 中的 parseSpanName 解析 span 名：约定格式为 framework.entity_type.specific_name，按最后一个 . 拆分为 baseName 与 typeSuffix，例如 "adk.agent.HumanApprovalWorkflow" → { baseName: "adk.agent", typeSuffix: "HumanApprovalWorkflow" }。资料来源：app/dashboard/app/lib/span-utils.ts:1-30

4.4 Supabase 与认证

app/supabase/readme.md 列出了数据库与认证的配置流程：使用 Supabase CLI 进行本地启动、迁移、远程链接；需要将 https://app.agentops.ai 配置为 Site URL，并通过 GitHub OAuth 与自定义 SMTP 启用认证与 Webhook。资料来源：app/supabase/readme.md:1-40

5. 常见失败模式与注意事项

• 重复结束 Span：OpenAI Agents 的 exporter 必须检查 span 是否已 ended，否则会因重复 end 导致错误。资料来源：agentops/instrumentation/agentic/openai_agents/README.md:74-86
• Token 字段类型：空值会被 ensure_int 强制转为 0，自定义查询（fields/search/order_by 等）在 ProjectMetricsDurationModel 中尚未实现，会抛出 NotImplementedError。资料来源：app/api/agentops/api/models/metrics.py:30-50
• 示例与文档同步：贡献示例时需同时更新根 README.md 与 docs/v2/examples/，由 generate_documentation.py 自动化生成。资料来源：examples/README.md:48-60

See Also

• Decorators & Span Hierarchy（详细装饰器使用与 span 嵌套规则）
• Instrumentation Framework（OpenAI Agents、LangChain 等框架的接入原理）
• Opsboard API Reference（组织/项目/角色管理 API）
• Dashboard UI Components（基于 shadcn-ui 的组件与 Hooks）
• Supabase Setup Guide（认证、数据库迁移、Webhook 配置）

概述与定位

AgentOps Python SDK 是整个可观测性体系的核心入口,提供了从代码层面接入会话(LLM Agent / 工具调用 / 多步骤工作流)所需的装饰器、属性处理器以及与后端 API 通信的基础客户端。其设计目标可总结为「一行代码接入、零侵入采集、统一语义约定」。

SDK 主要承担三类职责:

1. 生成 OpenTelemetry 兼容的 Span 数据,通过 @session、@agent、@operation / @task、@workflow 等装饰器在用户函数或类方法上织入埋点 README.md。
2. 通过语义约定映射(SemConv)将不同 LLM 框架的原始数据结构(OpenAI Chat Completions、Response API、Anthropic、LiteLLM 等)规范化为统一的属性键,如 gen_ai.usage.input_tokens、gen_ai.tool.name 等 agentops/instrumentation/agentic/openai_agents/README.md。
3. 与 api.agentops.ai 通信,通过版本化的客户端(v3、v4)上报 Span 与日志,异步化以避免阻塞主业务线程 agentops/client/api/base.py、agentops/client/api/__init__.py。

SDK 核心架构

SDK 采用「装饰器 → 处理器 → Exporter → API Client」四层流水线:

flowchart LR
    A[用户代码<br/>@session/@agent/@operation] --> B[Decorators Factory<br/>生成 Span]
    B --> C[Attribute Processors<br/>语义约定映射]
    C --> D[Exporter<br/>生命周期管理]
    D --> E[API Client v3/v4<br/>异步 HTTP 上报]
    E --> F[(AgentOps 后端<br/>ClickHouse + Supabase)]

各层职责如下:

• Decorators Factory:接收用户函数/类,基于 Python 装饰器协议构造对应 SpanKind 的 Span。SpanKind.CONSUMER 用于 Agent 类型,SpanKind.CLIENT 用于 Function 与 Generation 类型,以此区分请求方向 agentops/instrumentation/agentic/openai_agents/README.md。
• Attribute Processors:通过 get_agent_span_attributes()、get_function_span_attributes()、get_generation_span_attributes()、get_response_span_attributes()、get_handoff_span_attributes() 等单一职责的 getter 将原始字段映射到 MessageAttributes、CoreAttributes、WorkflowAttributes 等常量键 agentops/instrumentation/agentic/openai_agents/README.md。
• Exporter:管理 Span 的开始与结束事件。Start 事件创建但不结束的 Span,End 事件通过追踪字典查询已有 Span,合并属性并设置状态(OK / ERROR) agentops/instrumentation/agentic/openai_agents/README.md。
• API Client:BaseApiClient 封装异步 HTTP 逻辑,自动附加 User-Agent(agentops-python/<version>)、Keep-Alive 等标准请求头 agentops/client/api/base.py。

装饰器体系

SDK 暴露给用户的入口是装饰器,通过嵌套使用即可构建完整的 Span 树:

这些装饰器统一支持输入/输出记录、异常捕获以及 async/await 函数 README.md。嵌套使用 @session > @agent > @operation 可以自动形成父子 Span 层级,后端据此重建调用拓扑。

后端通过 classify_span() 进一步基于属性特征对 Span 进行分类,识别 Gen AI、Log、Session Update 三种顶层类别,以及通过 gen_ai.operation.name、llm.system、ai.llm 等键区分 LLM 调用、Embedding、Tool 调用等子类型 app/api/agentops/api/interactors/spans.py。

Provider 集成与示例

SDK 已为多个主流 LLM 框架提供开箱即用的 Provider,每个 Provider 都遵循同一套语义约定,因此用户无需关心底层映射:

• OpenAI Agents SDK:覆盖 Chat Completions、Response API、Agents SDK 三种格式,提供 Trace、Agent、Function、Generation、Response、Handoff 六类 Span agentops/instrumentation/agentic/openai_agents/README.md。示例见 examples/openai_agents/。
• LangChain:演示链式调用与 Agent 调用的全链路追踪 examples/langchain/README.md。
• AutoGen / AG2:覆盖 AgentChat、MathAgent 等多 Agent 会话场景 examples/autogen/README.md。
• Smolagents:支持 Manager-Worker 多 Agent 层级与自定义工具 examples/smolagents/README.md。
• 其他:CrewAI、Gemini、Google ADK、Anthropic、LiteLLM 等 Provider 均有独立子目录,使用方式一致 examples/README.md。

所有 Provider 共享以下序列化原则:不主动序列化嵌套结构、保留原始字符串、避免解析消息体内的 JSON,以便在 OpenTelemetry 后端正确渲染 agentops/instrumentation/agentic/openai_agents/README.md。

数据上报与故障排查

上报链路通过版本化客户端进行隔离:ApiClient 默认指向 https://api.agentops.ai,并通过属性访问器惰性创建 V3Client 与 V4Client agentops/client/api/__init__.py。请求头由 BaseApiClient.prepare_headers() 统一注入,包括 SDK 版本号,便于后端做兼容性判断 agentops/client/api/base.py。

常见问题与排查要点:

• 认证失败:检查 AGENTOPS_API_KEY 是否配置,JWT 由后端签发,有效期 30 天 app/api/agentops/api/auth.py。
• Span 未结束:若业务异常退出导致 End 事件丢失,Exporter 会检测重复并基于已有属性重建完整 Span agentops/instrumentation/agentic/openai_agents/README.md。
• Trace 列表查询慢:后端使用 TraceListCache(默认 5 分钟 TTL)缓存按时间窗口和查询条件分页的结果 app/api/agentops/api/routes/v4/traces/views.py。

See Also

• Python SDK: Instrumentation 内部实现 — Span 生命周期与 Exporter 细节
• API 客户端: v3 / v4 协议 — HTTP 接口差异与认证流程
• Provider 接入指南 — 新框架接入的语义约定与最佳实践
• 示例库总览 — 各框架 Notebook 与脚本索引

概述与定位

AgentOps 是一个面向 AI Agent 的可观测性与开发工具平台,其核心能力由三部分协同支撑:Python SDK (agentops/) 用于在用户应用中采集 Trace、Span 与事件;后端 API 服务 (app/api/agentops/) 负责鉴权、组织/项目管理以及遥测数据接入;基于 Next.js 的 Dashboard (app/dashboard/) 则为终端用户提供会话回放、Trace 浏览与项目配置界面 README.md。

仓库根目录下的 app/ 是一个 monorepo,集中托管 API、Dashboard、Landing 等子项目,使用统一的 ESLint/Prettier/Ruff 配置与 just 命令进行编排,使用 Supabase 提供持久层、ClickHouse 提供高性能遥测存储 app/README.md。

仓库 Monorepo 结构

app/ 目录按职责拆分,每个子项目均可独立运行与部署:

资料来源:app/README.md

启动本地开发环境时,可使用 just 命令统一编排 API、Dashboard 与 Landing,也可单独进入子目录使用 uv run python run.py 或 bun dev 启动 app/README.md。

Opsboard 后端 API

Opsboard 模块是 AgentOps 仪表盘的后端,提供用户、组织、项目相关的 REST 接口,基于 FastAPI 构建并自动生成 OpenAPI 文档。其目录划分遵循关注点分离原则:app.py 负责 FastAPI 实例与中间件,environment.py 处理环境变量,models.py 定义 SQLAlchemy ORM 模型,schemas.py 通过 Pydantic 校验请求/响应,routes.py 聚合路由,具体业务逻辑下沉到 views/ 子模块中 app/api/agentops/opsboard/README.md。

Opsboard 的核心项目括:用户档案与偏好管理、组织与团队邀请、基于角色的访问控制(owner、admin、developer、business_user 四级角色)、项目环境配置(production、staging、development、community)以及面向 SDK 的 API Key 签发 app/api/agentops/opsboard/README.md。

SDK 与后端交互的基础契约由 agentops/client/api/base.py 与 agentops/client/api/types.py 定义。BaseApiClient 暴露异步 HTTP 方法,统一注入 User-Agent、Keep-Alive 等标准头,并通过 TokenFetcher 协议承载鉴权 token 的获取逻辑 agentops/client/api/base.py。TypedDict 形式的 AuthTokenResponse、UploadedObjectResponse 等类型在多个 API 模块间复用,确保 SDK 侧与服务端协议一致 agentops/client/api/types.py。

Dashboard 前端

Dashboard 是基于 Next.js App Router 的 Web 应用,使用 shadcn/ui 作为基础组件库,Tailwind CSS 处理样式,并通过 Supabase JS 直接读取部分持久化数据。其目录组织强调“按特性划分”:

• app/:路由页面、布局、加载/错误边界,其中 (with-layout)/ 分组共享主布局
• components/:可复用 UI 组件,ui/ 存放 shadcn-ui 风格的原子组件
• lib/:工具函数、TS 类型(types_db.ts)、Supabase 客户端封装
• hooks/:数据获取与上下文相关的自定义 Hook,例如 useMetrics、useTraces
• tests/ 与 public/:测试与静态资源

资料来源:app/dashboard/README.md

package.json 中暴露了常用脚本,例如 bun run dev 启动开发服务,bun run build 构建生产产物,bun run lint 与 bunx tsc --noEmit 分别进行风格检查与全量类型检查;类型定义通过 npx supabase gen types typescript 自动生成 app/dashboard/package.json。

Dashboard 解析 Span 时会调用 parseSpanName 这一工具函数,把形如 framework.entity_type.specific_name 的名称切分为 baseName 与 typeSuffix,以便在 UI 中按框架/实体类型分组展示(如 adk.agent.HumanApprovalWorkflow、crewai.task.ResearchTask) app/dashboard/app/lib/span-utils.ts。

数据流与典型故障模式

下图展示了从 SDK 到 Dashboard 的整体数据流,涵盖了 SDK 上报、Opsboard 鉴权、遥测入库与前端渲染四个关键阶段:

flowchart LR
    A[Python SDK agentops] --> B[HttpClient + BaseApiClient]
    B --> C{Opsboard API}
    C -->|/auth/token| D[Supabase Postgres]
    C -->|/v4/objects/upload| E[对象存储]
    C -->|traces/metrics/logs| F[ClickHouse]
    D --> G[Dashboard Next.js]
    F --> G
    E --> G
    G --> H[Span/Metric UI]

资料来源:agentops/client/api/base.py、app/api/agentops/opsboard/README.md、app/README.md

最常见的故障与排障要点集中在认证与数据库连接两侧:

• 登录跳转回登录页:通常由 Cookie 跨域配置引起,需保证 NEXT_PUBLIC_API_URL 与 JWT_SECRET_KEY 正确设置,本地开发时 API 会自动为 localhost 调整 Cookie,生产环境需共享根域 app/README.md。
• 数据库连接错误:必须确认 Supabase 相关变量(SUPABASE_HOST 等)在 api/.env 中完整配置 app/README.md。

工程流程层面的规范(如事故响应、贡献流程)由 app/handbook/ 维护,事故复盘参考了 Pragmatic Engineer 与 Posthog Handbook 的最佳实践 app/handbook/README.md。

See Also

• Python SDK 接入与 Instrumentation — 了解 SDK 如何产生 Trace/Span
• Examples 目录 — 各框架接入示例
• OpenAI Agents Instrumentation — 特定框架的 Span 处理细节

概述

AgentOps 提供了一套统一的"框架集成 + 遥测管道"，让用户能够在不修改业务代码的前提下，自动观测多个主流 LLM 与 Agent 框架的运行情况。SDK 端通过 OpenTelemetry 兼容的语义约定对运行事件进行捕获、归一化与编码，再通过 HTTP 客户端上报至 AgentOps 后端仪表盘进行可视化分析。

遥测管道覆盖了三类关键场景：

• LLM 调用追踪：记录模型名称、Prompt、参数、Token 用量与延迟；
• Agent 执行追踪：记录 Agent 名称、步骤、规划阶段、工具调用；
• 工具执行追踪：记录工具名、参数、结果与成功/失败状态。

资料来源：README.md:1-50

核心架构与数据流

AgentOps 的遥测管道遵循"采集 → 归一化 → 导出"三阶段模型。各框架集成模块都遵循一致的 OpenTelemetry 模式，从而让后端可以以统一格式消费数据。

flowchart LR
    A[用户应用<br/>User App] -->|调用 LLM/Agent/Tool| B(框架 SDK<br/>OpenAI Agents / LangChain / CrewAI / SmoLAgents / ...)
    B -->|拦截方法或回调| C[Instrumentation 层<br/>agentops.instrumentation.*]
    C -->|属性提取| D[SemConv 语义约定<br/>agentops.semconv]
    D -->|生成 OTel Span/Metric| E[Exporter<br/>Exporter.py]
    E -->|HTTP POST| F[BaseApiClient<br/>agentops.client.api.base]
    F -->|JSON over HTTPS| G[(AgentOps 后端<br/>Dashboard)]
    G --> H[会话回放 / 调试 / 计费分析]

各阶段职责如下：

1. Instrumentation 层：通过 monkey-patching 框架方法或订阅框架回调来拦截调用。例如 OpenAI Agents SDK 拦截 Runner 类并替换 trace processor；SmoLAgents 同样在 OpenTelemetry 之上构建捕获逻辑；
2. 属性提取器（Attribute Extractor）：从方法入参、返回值中提取符合语义约定的字段；
3. 语义约定（SemConv）：使用 agentops.semconv 中的常量（如 SpanAttributes.LLM_REQUEST_MODEL、ToolAttributes.TOOL_NAME）保证跨框架字段命名一致；
4. Exporter：将内部数据结构转换为 OpenTelemetry Span/Metric，并附加上 AgentOps 扩展字段；
5. BaseApiClient：通过 HttpClient 异步上传数据，统一带上 User-Agent: agentops-python/<version> 标识。

资料来源：agentops/instrumentation/agentic/openai_agents/README.md:1-40、agentops/instrumentation/agentic/smolagents/README.md:1-40、agentops/client/api/base.py:1-40

支持的框架集成

下表汇总了 examples/ 目录及 agentops/instrumentation/agentic/ 下的代表性集成方案，展示了 AgentOps 对主流框架的覆盖范围。

每一种集成都遵循相同的入口约定：用户在应用入口处调用 init(api_key=...)，对应框架的 instrumentation 会被自动激活，所有相关操作随后进入遥测管道。

资料来源：examples/README.md:1-70、agentops/integration/callbacks/langchain/README.md:1-30

语义约定与通用组件

为了让来自不同框架的事件具有可比性，AgentOps 在 agentops/semconv 中定义了一组语义约定常量，覆盖 Agent、Tool、Workflow 与 LLM/GenAI 四大类属性。例如：

• AgentAttributes.AGENT_NAME / AGENT_ROLE / AGENT_ID
• ToolAttributes.TOOL_NAME / TOOL_PARAMETERS / TOOL_RESULT / TOOL_STATUS
• WorkflowAttributes.WORKFLOW_NAME / WORKFLOW_TYPE / WORKFLOW_STEP_STATUS
• SpanAttributes.LLM_REQUEST_MODEL / LLM_REQUEST_TEMPERATURE / LLM_REQUEST_MAX_TOKENS

通用组件 agentops.instrumentation.common 提供了跨框架共享的能力，包括：

• 属性处理器（Attribute Handler）：纯函数，从 args/kwargs/return_value 中提取属性映射；
• WrapConfig：描述如何包装某个方法（trace_name、package、class_name、method_name、span_kind 等）；
• 同步 / 异步包装器：分别对应普通方法与流式方法，确保上下文在并发场景下正确传播。

这种"约定 + 通用组件 + 各框架 instrumentor"的层次划分，使得新增一个框架集成时，开发者只需编写轻量的属性提取与 wrapper，无需重复实现整个管道。

资料来源：agentops/semconv/README.md:1-50、agentops/instrumentation/common/README.md:1-50

使用模式与失败模式

典型使用流程

1. 在应用入口执行 from agentops import init; init(api_key=...)；
2. 正常编写业务代码，调用所选框架（OpenAI Agents / LangChain / CrewAI 等）；
3. 框架调用会被对应 instrumentor 自动拦截，进入遥测管道；
4. 事件经 BaseApiClient 上报至 AgentOps 后端；
5. 在 AgentOps Dashboard 中查看会话回放、Token 计费、错误断点等信息。

常见失败模式

• API Key 缺失或错误：初始化不会抛错，但所有事件将在 HTTP 层失败；需检查 AGENTOPS_API_KEY 环境变量；
• 框架版本不兼容：instrumentor 通常依赖具体的 monkey-patch 点，框架大版本升级后需要对应更新 SDK；
• 流式上下文丢失：异步流式调用若未使用 instrumentor 提供的 stream wrapper，可能导致部分 Span 缺失；
• 属性映射遗漏：自定义工具若未声明在 WrapConfig 中，将不会生成 Tool Span。

与后续路线图的关联

主 README 中的 Debugging Roadmap 明确将"事件延迟分析"、"Agent workflow 执行计费"、"Token 上限溢出标记"、"故障推理检测"、"生成代码校验"等列为已支持或进行中的能力，这些都是遥测管道在前端展现层的具体落地点。

资料来源：README.md:1-50

See Also

• OpenTelemetry Semantic Conventions for Generative AI Systems
• AgentOps LangChain Callback Handler
• OpenAI Agents SDK Instrumentation
• SmoLAgents Instrumentation
• AgentOps Instrumentation Common Module
• Examples Overview

Pitfall Log / 踩坑日志

项目：AgentOps-AI/agentops

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/AgentOps-AI/agentops | README/documentation is current enough for a first validation pass.

2. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/AgentOps-AI/agentops | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/AgentOps-AI/agentops | no_demo; severity=medium

4. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/AgentOps-AI/agentops | no_demo; severity=medium

5. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/AgentOps-AI/agentops | issue_or_pr_quality=unknown

6. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/AgentOps-AI/agentops | release_recency=unknown