# https://github.com/AgentOps-AI/agentops 项目说明书 生成时间：2026-06-19 18:26:00 UTC ## 目录 - [Overview & Architecture](#page-1) - [Python SDK: Core, Decorators & Providers](#page-2) - [Backend API, Storage & Dashboard](#page-3) - [Framework Integrations & Telemetry Pipeline](#page-4) ## Overview & Architecture ### 相关页面 相关主题：[Python SDK: Core, Decorators & Providers](#page-2), [Backend API, Storage & Dashboard](#page-3), [Framework Integrations & Telemetry Pipeline](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/AgentOps-AI/agentops/blob/main/README.md) - [agentops/client/api/base.py](https://github.com/AgentOps-AI/agentops/blob/main/agentops/client/api/base.py) - [agentops/client/api/types.py](https://github.com/AgentOps-AI/agentops/blob/main/agentops/client/api/types.py) - [agentops/instrumentation/agentic/openai_agents/README.md](https://github.com/AgentOps-AI/agentops/blob/main/agentops/instrumentation/agentic/openai_agents/README.md) - [app/README.md](https://github.com/AgentOps-AI/agentops/blob/main/app/README.md) - [app/api/agentops/opsboard/README.md](https://github.com/AgentOps-AI/agentops/blob/main/app/api/agentops/opsboard/README.md) - [app/dashboard/README.md](https://github.com/AgentOps-AI/agentops/blob/main/app/dashboard/README.md) - [app/dashboard/app/lib/span-utils.ts](https://github.com/AgentOps-AI/agentops/blob/main/app/dashboard/app/lib/span-utils.ts) - [app/api/agentops/api/models/metrics.py](https://github.com/AgentOps-AI/agentops/blob/main/app/api/agentops/api/models/metrics.py) - [app/supabase/readme.md](https://github.com/AgentOps-AI/agentops/blob/main/app/supabase/readme.md) - [examples/README.md](https://github.com/AgentOps-AI/agentops/blob/main/examples/README.md)
# Overview & Architecture ## 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）。 ```mermaid 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 嵌套层次结构： | 装饰器 | 用途 | 典型层级 | |---|---|---| | `@session` | 标识一次完整工作流的根 span | 根 | | `@agent` | 标记 Agent 类的生命周期 | 子级 | | `@operation` / `@task` | 跟踪具体操作或任务 | 叶子/中间 | | `@workflow` | 跨多操作的复合工作流 | 子级 | 每个装饰器都支持输入/输出记录、异常处理以及 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/`）与异步调用协议；`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 配置） --- ## Python SDK: Core, Decorators & Providers ### 相关页面 相关主题：[Overview & Architecture](#page-1), [Framework Integrations & Telemetry Pipeline](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/AgentOps-AI/agentops/blob/main/README.md) - [agentops/client/api/base.py](https://github.com/AgentOps-AI/agentops/blob/main/agentops/client/api/base.py) - [agentops/client/api/types.py](https://github.com/AgentOps-AI/agentops/blob/main/agentops/client/api/types.py) - [agentops/client/api/__init__.py](https://github.com/AgentOps-AI/agentops/blob/main/agentops/client/api/__init__.py) - [agentops/instrumentation/agentic/openai_agents/README.md](https://github.com/AgentOps-AI/agentops/blob/main/agentops/instrumentation/agentic/openai_agents/README.md) - [app/api/agentops/api/interactors/spans.py](https://github.com/AgentOps-AI/agentops/blob/main/app/api/agentops/api/interactors/spans.py) - [app/api/agentops/api/routes/v4/traces/views.py](https://github.com/AgentOps-AI/agentops/blob/main/app/api/agentops/api/routes/v4/traces/views.py) - [examples/README.md](https://github.com/AgentOps-AI/agentops/blob/main/examples/README.md) - [examples/langchain/README.md](https://github.com/AgentOps-AI/agentops/blob/main/examples/langchain/README.md) - [examples/autogen/README.md](https://github.com/AgentOps-AI/agentops/blob/main/examples/autogen/README.md) - [examples/smolagents/README.md](https://github.com/AgentOps-AI/agentops/blob/main/examples/smolagents/README.md)
# Python SDK: Core, Decorators & Providers ## 概述与定位 AgentOps Python SDK 是整个可观测性体系的核心入口,提供了从代码层面接入会话(LLM Agent / 工具调用 / 多步骤工作流)所需的装饰器、属性处理器以及与后端 API 通信的基础客户端。其设计目标可总结为「一行代码接入、零侵入采集、统一语义约定」。 SDK 主要承担三类职责: 1. **生成 OpenTelemetry 兼容的 Span 数据**,通过 `@session`、`@agent`、`@operation` / `@task`、`@workflow` 等装饰器在用户函数或类方法上织入埋点 [README.md](https://github.com/AgentOps-AI/agentops/blob/main/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](https://github.com/AgentOps-AI/agentops/blob/main/agentops/instrumentation/agentic/openai_agents/README.md)。 3. **与 `api.agentops.ai` 通信**,通过版本化的客户端(v3、v4)上报 Span 与日志,异步化以避免阻塞主业务线程 [agentops/client/api/base.py](https://github.com/AgentOps-AI/agentops/blob/main/agentops/client/api/base.py)、[agentops/client/api/__init__.py](https://github.com/AgentOps-AI/agentops/blob/main/agentops/client/api/__init__.py)。 ## SDK 核心架构 SDK 采用「**装饰器 → 处理器 → Exporter → API Client**」四层流水线: ```mermaid flowchart LR A[用户代码
@session/@agent/@operation] --> B[Decorators Factory
生成 Span] B --> C[Attribute Processors
语义约定映射] C --> D[Exporter
生命周期管理] D --> E[API Client v3/v4
异步 HTTP 上报] E --> F[(AgentOps 后端
ClickHouse + Supabase)] ``` 各层职责如下: - **Decorators Factory**:接收用户函数/类,基于 Python 装饰器协议构造对应 SpanKind 的 Span。`SpanKind.CONSUMER` 用于 Agent 类型,`SpanKind.CLIENT` 用于 Function 与 Generation 类型,以此区分请求方向 [agentops/instrumentation/agentic/openai_agents/README.md](https://github.com/AgentOps-AI/agentops/blob/main/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](https://github.com/AgentOps-AI/agentops/blob/main/agentops/instrumentation/agentic/openai_agents/README.md)。 - **Exporter**:管理 Span 的开始与结束事件。Start 事件创建但不结束的 Span,End 事件通过追踪字典查询已有 Span,合并属性并设置状态(OK / ERROR) [agentops/instrumentation/agentic/openai_agents/README.md](https://github.com/AgentOps-AI/agentops/blob/main/agentops/instrumentation/agentic/openai_agents/README.md)。 - **API Client**:`BaseApiClient` 封装异步 HTTP 逻辑,自动附加 `User-Agent`(`agentops-python/`)、`Keep-Alive` 等标准请求头 [agentops/client/api/base.py](https://github.com/AgentOps-AI/agentops/blob/main/agentops/client/api/base.py)。 ## 装饰器体系 SDK 暴露给用户的入口是装饰器,通过嵌套使用即可构建完整的 Span 树: | 装饰器 | 用途 | 典型 Span 类型 | |--------|------|----------------| | `@session` | 整个工作流的根 Span | Trace | | `@agent` | Agent 生命周期,作用于类 | Agent (`SpanKind.CONSUMER`) | | `@operation` / `@task` | 单个操作或任务 | Operation / Task | | `@workflow` | 多步骤工作流 | Workflow | 这些装饰器统一支持输入/输出记录、异常捕获以及 `async/await` 函数 [README.md](https://github.com/AgentOps-AI/agentops/blob/main/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](https://github.com/AgentOps-AI/agentops/blob/main/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](https://github.com/AgentOps-AI/agentops/blob/main/agentops/instrumentation/agentic/openai_agents/README.md)。示例见 [`examples/openai_agents/`](https://github.com/AgentOps-AI/agentops/blob/main/examples/)。 - **LangChain**:演示链式调用与 Agent 调用的全链路追踪 [examples/langchain/README.md](https://github.com/AgentOps-AI/agentops/blob/main/examples/langchain/README.md)。 - **AutoGen / AG2**:覆盖 `AgentChat`、`MathAgent` 等多 Agent 会话场景 [examples/autogen/README.md](https://github.com/AgentOps-AI/agentops/blob/main/examples/autogen/README.md)。 - **Smolagents**:支持 Manager-Worker 多 Agent 层级与自定义工具 [examples/smolagents/README.md](https://github.com/AgentOps-AI/agentops/blob/main/examples/smolagents/README.md)。 - 其他:CrewAI、Gemini、Google ADK、Anthropic、LiteLLM 等 Provider 均有独立子目录,使用方式一致 [examples/README.md](https://github.com/AgentOps-AI/agentops/blob/main/examples/README.md)。 所有 Provider 共享以下序列化原则:不主动序列化嵌套结构、保留原始字符串、避免解析消息体内的 JSON,以便在 OpenTelemetry 后端正确渲染 [agentops/instrumentation/agentic/openai_agents/README.md](https://github.com/AgentOps-AI/agentops/blob/main/agentops/instrumentation/agentic/openai_agents/README.md)。 ## 数据上报与故障排查 上报链路通过版本化客户端进行隔离:`ApiClient` 默认指向 `https://api.agentops.ai`,并通过属性访问器惰性创建 `V3Client` 与 `V4Client` [agentops/client/api/__init__.py](https://github.com/AgentOps-AI/agentops/blob/main/agentops/client/api/__init__.py)。请求头由 `BaseApiClient.prepare_headers()` 统一注入,包括 SDK 版本号,便于后端做兼容性判断 [agentops/client/api/base.py](https://github.com/AgentOps-AI/agentops/blob/main/agentops/client/api/base.py)。 常见问题与排查要点: - **认证失败**:检查 `AGENTOPS_API_KEY` 是否配置,JWT 由后端签发,有效期 30 天 [app/api/agentops/api/auth.py](https://github.com/AgentOps-AI/agentops/blob/main/app/api/agentops/api/auth.py)。 - **Span 未结束**:若业务异常退出导致 End 事件丢失,Exporter 会检测重复并基于已有属性重建完整 Span [agentops/instrumentation/agentic/openai_agents/README.md](https://github.com/AgentOps-AI/agentops/blob/main/agentops/instrumentation/agentic/openai_agents/README.md)。 - **Trace 列表查询慢**:后端使用 `TraceListCache`(默认 5 分钟 TTL)缓存按时间窗口和查询条件分页的结果 [app/api/agentops/api/routes/v4/traces/views.py](https://github.com/AgentOps-AI/agentops/blob/main/app/api/agentops/api/routes/v4/traces/views.py)。 ## See Also - [Python SDK: Instrumentation 内部实现](instrumentation.md) — Span 生命周期与 Exporter 细节 - [API 客户端: v3 / v4 协议](api-client.md) — HTTP 接口差异与认证流程 - [Provider 接入指南](providers.md) — 新框架接入的语义约定与最佳实践 - [示例库总览](../examples/README.md) — 各框架 Notebook 与脚本索引 --- ## Backend API, Storage & Dashboard ### 相关页面 相关主题：[Overview & Architecture](#page-1), [Python SDK: Core, Decorators & Providers](#page-2)
相关源码文件 以下源码文件用于生成本页说明： - [app/README.md](https://github.com/AgentOps-AI/agentops/blob/main/app/README.md) - [app/api/agentops/opsboard/README.md](https://github.com/AgentOps-AI/agentops/blob/main/app/api/agentops/opsboard/README.md) - [app/dashboard/README.md](https://github.com/AgentOps-AI/agentops/blob/main/app/dashboard/README.md) - [app/dashboard/package.json](https://github.com/AgentOps-AI/agentops/blob/main/app/dashboard/package.json) - [app/dashboard/app/lib/span-utils.ts](https://github.com/AgentOps-AI/agentops/blob/main/app/dashboard/app/lib/span-utils.ts) - [agentops/client/api/base.py](https://github.com/AgentOps-AI/agentops/blob/main/agentops/client/api/base.py) - [agentops/client/api/types.py](https://github.com/AgentOps-AI/agentops/blob/main/agentops/client/api/types.py) - [app/handbook/README.md](https://github.com/AgentOps-AI/agentops/blob/main/app/handbook/README.md) - [README.md](https://github.com/AgentOps-AI/agentops/blob/main/README.md)
# Backend API, Storage & Dashboard ## 概述与定位 AgentOps 是一个面向 AI Agent 的可观测性与开发工具平台,其核心能力由三部分协同支撑:Python SDK (`agentops/`) 用于在用户应用中采集 Trace、Span 与事件;后端 API 服务 (`app/api/agentops/`) 负责鉴权、组织/项目管理以及遥测数据接入;基于 Next.js 的 Dashboard (`app/dashboard/`) 则为终端用户提供会话回放、Trace 浏览与项目配置界面 [README.md](https://github.com/AgentOps-AI/agentops/blob/main/README.md)。 仓库根目录下的 `app/` 是一个 monorepo,集中托管 API、Dashboard、Landing 等子项目,使用统一的 ESLint/Prettier/Ruff 配置与 `just` 命令进行编排,使用 Supabase 提供持久层、ClickHouse 提供高性能遥测存储 [app/README.md](https://github.com/AgentOps-AI/agentops/blob/main/app/README.md)。 ## 仓库 Monorepo 结构 `app/` 目录按职责拆分,每个子项目均可独立运行与部署: | 子目录 | 技术栈 | 主要职责 | | --- | --- | --- | | `app/api/` | FastAPI + SQLAlchemy + Pydantic | REST API、用户/组织/项目/遥测后端 | | `app/dashboard/` | Next.js (App Router) + shadcn/ui + Supabase JS | 前端控制台、可视化、Trace/Span 渲染 | | `app/landing/` | Next.js | 营销站点 | | `app/handbook/` | Markdown | 团队工程手册与事故响应流程 | 资料来源:[app/README.md](https://github.com/AgentOps-AI/agentops/blob/main/app/README.md) 启动本地开发环境时,可使用 `just` 命令统一编排 API、Dashboard 与 Landing,也可单独进入子目录使用 `uv run python run.py` 或 `bun dev` 启动 [app/README.md](https://github.com/AgentOps-AI/agentops/blob/main/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](https://github.com/AgentOps-AI/agentops/blob/main/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](https://github.com/AgentOps-AI/agentops/blob/main/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](https://github.com/AgentOps-AI/agentops/blob/main/agentops/client/api/base.py)。`TypedDict` 形式的 `AuthTokenResponse`、`UploadedObjectResponse` 等类型在多个 API 模块间复用,确保 SDK 侧与服务端协议一致 [agentops/client/api/types.py](https://github.com/AgentOps-AI/agentops/blob/main/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](https://github.com/AgentOps-AI/agentops/blob/main/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](https://github.com/AgentOps-AI/agentops/blob/main/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](https://github.com/AgentOps-AI/agentops/blob/main/app/dashboard/app/lib/span-utils.ts)。 ## 数据流与典型故障模式 下图展示了从 SDK 到 Dashboard 的整体数据流,涵盖了 SDK 上报、Opsboard 鉴权、遥测入库与前端渲染四个关键阶段: ```mermaid 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](https://github.com/AgentOps-AI/agentops/blob/main/agentops/client/api/base.py)、[app/api/agentops/opsboard/README.md](https://github.com/AgentOps-AI/agentops/blob/main/app/api/agentops/opsboard/README.md)、[app/README.md](https://github.com/AgentOps-AI/agentops/blob/main/app/README.md) 最常见的故障与排障要点集中在认证与数据库连接两侧: - **登录跳转回登录页**:通常由 Cookie 跨域配置引起,需保证 `NEXT_PUBLIC_API_URL` 与 `JWT_SECRET_KEY` 正确设置,本地开发时 API 会自动为 localhost 调整 Cookie,生产环境需共享根域 [app/README.md](https://github.com/AgentOps-AI/agentops/blob/main/app/README.md)。 - **数据库连接错误**:必须确认 Supabase 相关变量(`SUPABASE_HOST` 等)在 `api/.env` 中完整配置 [app/README.md](https://github.com/AgentOps-AI/agentops/blob/main/app/README.md)。 工程流程层面的规范(如事故响应、贡献流程)由 `app/handbook/` 维护,事故复盘参考了 Pragmatic Engineer 与 Posthog Handbook 的最佳实践 [app/handbook/README.md](https://github.com/AgentOps-AI/agentops/blob/main/app/handbook/README.md)。 ## See Also - [Python SDK 接入与 Instrumentation](README.md) — 了解 SDK 如何产生 Trace/Span - [Examples 目录](examples/README.md) — 各框架接入示例 - [OpenAI Agents Instrumentation](agentops/instrumentation/agentic/openai_agents/README.md) — 特定框架的 Span 处理细节 --- ## Framework Integrations & Telemetry Pipeline ### 相关页面 相关主题：[Overview & Architecture](#page-1), [Python SDK: Core, Decorators & Providers](#page-2), [Backend API, Storage & Dashboard](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [examples/README.md](https://github.com/AgentOps-AI/agentops/blob/main/examples/README.md) - [agentops/instrumentation/agentic/smolagents/README.md](https://github.com/AgentOps-AI/agentops/blob/main/agentops/instrumentation/agentic/smolagents/README.md) - [agentops/instrumentation/agentic/openai_agents/README.md](https://github.com/AgentOps-AI/agentops/blob/main/agentops/instrumentation/agentic/openai_agents/README.md) - [agentops/instrumentation/common/README.md](https://github.com/AgentOps-AI/agentops/blob/main/agentops/instrumentation/common/README.md) - [agentops/semconv/README.md](https://github.com/AgentOps-AI/agentops/blob/main/agentops/semconv/README.md) - [agentops/integration/callbacks/langchain/README.md](https://github.com/AgentOps-AI/agentops/blob/main/agentops/integration/callbacks/langchain/README.md) - [agentops/client/api/base.py](https://github.com/AgentOps-AI/agentops/blob/main/agentops/client/api/base.py) - [README.md](https://github.com/AgentOps-AI/agentops/blob/main/README.md)
# Framework Integrations & Telemetry Pipeline ## 概述 AgentOps 提供了一套统一的"框架集成 + 遥测管道"，让用户能够在不修改业务代码的前提下，自动观测多个主流 LLM 与 Agent 框架的运行情况。SDK 端通过 OpenTelemetry 兼容的语义约定对运行事件进行捕获、归一化与编码，再通过 HTTP 客户端上报至 AgentOps 后端仪表盘进行可视化分析。 遥测管道覆盖了三类关键场景： - **LLM 调用追踪**：记录模型名称、Prompt、参数、Token 用量与延迟； - **Agent 执行追踪**：记录 Agent 名称、步骤、规划阶段、工具调用； - **工具执行追踪**：记录工具名、参数、结果与成功/失败状态。 资料来源：[README.md:1-50]() ## 核心架构与数据流 AgentOps 的遥测管道遵循"采集 → 归一化 → 导出"三阶段模型。各框架集成模块都遵循一致的 OpenTelemetry 模式，从而让后端可以以统一格式消费数据。 ```mermaid flowchart LR A[用户应用
User App] -->|调用 LLM/Agent/Tool| B(框架 SDK
OpenAI Agents / LangChain / CrewAI / SmoLAgents / ...) B -->|拦截方法或回调| C[Instrumentation 层
agentops.instrumentation.*] C -->|属性提取| D[SemConv 语义约定
agentops.semconv] D -->|生成 OTel Span/Metric| E[Exporter
Exporter.py] E -->|HTTP POST| F[BaseApiClient
agentops.client.api.base] F -->|JSON over HTTPS| G[(AgentOps 后端
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/` 标识。 资料来源：[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 对主流框架的覆盖范围。 | 集成框架 | 集成方式 | 示例目录 | 主要捕获对象 | |---------|---------|---------|------------| | OpenAI Agents SDK | Trace Processor + Runner monkey-patch | `examples/openai_agents/` | Agent / Function / Generation / Trace Span | | LangChain / LangGraph | Callback Handler | `agentops/integration/callbacks/langchain/` | LLM / Chain / Tool | | CrewAI | OpenTelemetry Instrumentor | `examples/crewai/` | Agent / Task / Tool | | SmoLAgents | OpenTelemetry Instrumentor | `examples/smolagents/` | Model / Step / Tool | | AG2 / AutoGen | Instrumentor | `examples/ag2/`, `examples/autogen/` | Agent Chat / Tool | | Google ADK | Instrumentor | `examples/google_adk/` | Agent / Workflow（含人工审批）| | Anthropic Claude | 示例脚本 | `examples/anthropic/` | 同步/异步/工具调用 | | Gemini / Watsonx / LiteLLM | 示例脚本 | `examples/gemini/`, `examples/watsonx/`, `examples/litellm/` | 多模型 Provider 调用 | 每一种集成都遵循相同的入口约定：用户在应用入口处调用 `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](https://app.agentops.ai) 中查看会话回放、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/semconv/README.md) - [AgentOps LangChain Callback Handler](agentops/integration/callbacks/langchain/README.md) - [OpenAI Agents SDK Instrumentation](agentops/instrumentation/agentic/openai_agents/README.md) - [SmoLAgents Instrumentation](agentops/instrumentation/agentic/smolagents/README.md) - [AgentOps Instrumentation Common Module](agentops/instrumentation/common/README.md) - [Examples Overview](examples/README.md) --- --- ## Doramagic 踩坑日志 项目：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