仪器
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 中等消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 需要 · Vendor-specific
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 读取环境变量
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
如果提供了`$ARGUMENTS`,请将您的工作范围限制在这些文件或目录中。否则,发现项目根并检测主要应用程序代码。
扫描代码库以确定: 语言:Python(查找`*.py`、`pyproject.toml`、`requirements.txt`)或 TypeScript(查找`*.ts`、`*.tsx`、`package.json`)正在使用的 LLM 框架 — 搜索这些模式的导入:导入模式·框架·集成`from openai`/ `import OpenAI`·OpenAI·`track_openai`
查找: 入口点:启动代理的顶级函数(例如,`main`、`run`、`agent`、`handle_message`、路由处理程序或用户的主要编排函数) LLM 调用站点:直接调用 LLM 提供程序的函数 工具函数:检索、搜索、API 调用或其他类似工具的操作 现有配置类:数据类、Pydantic 模型或包含模型名称、温度、提示或其他可调参数的普通类
对于每个检测到的框架,在模块级别添加适当的集成。请参阅上面的积分表和`references/integrations.md`了解确切的模式。 Python 示例: TypeScript 示例:
如果代理处理多轮对话(聊天机器人、支持代理、多步骤助手),则连线`thread_id`:对于单次代理或批处理跳过此操作。
遵循主要 Opik 技能中的设置决策树:如果项目有 `.env` / `.env.local` → 追加 `OPIK_API_KEY`、`OPIK_WORKSPACE`、`OPIK_URL_OVERRIDE`(如果缺失) 如果不存在 `.env` → Python:创建/更新 `~/.opik.config`; TypeScript:创建`.env`或`.env.local`永远不要引入第二个配置机制永远不要覆盖现有值
打印安装命令但不自动运行它。让用户决定。 Python:如果需要的话,加上任何集成包(大多数都包含在`opik`中)。 TypeScript:根据需要加上特定于框架的包:`opik-openai`、`opik-vercel`、`opik-langchain`、`opik-gemini`。
检测后,进行快速审核: [ ] 每个 LLM 调用点都被跟踪(通过集成包装器或 `@opik.track`) [ ] 仅有一个函数具有 `entrypoint=True` [ ] 入口点函数仅接受原始参数(`str`、`int`、`float`、`bool`、 `list`、`dict`) — 没有 Pydantic 模型、数据类或自定义类 [ ] 所有 `get_or_create_config()` 调用和配置字段访问都发生在 `@opik.track` 修饰的函数内部(或其中一个函数的下游)
# Instrument — Add Opik Tracing to a Codebase
You are instrumenting an existing codebase with Opik observability. Follow these steps precisely.
## Step 1 — Scope
If `$ARGUMENTS` is provided, scope your work to those files or directories. Otherwise, discover the project root and instrument the main application code.
## Step 2 — Detect Language & Frameworks
Scan the codebase to determine:
1. **Language**: Python (look for `*.py`, `pyproject.toml`, `requirements.txt`) or TypeScript (look for `*.ts`, `*.tsx`, `package.json`)
2. **LLM frameworks in use** — search imports for these patterns:
| Import pattern | Framework | Integration |
|---|---|---|
| `from openai` / `import OpenAI` | OpenAI | `track_openai` |
| `import anthropic` | Anthropic | `track_anthropic` |
| `from langchain` / `@langchain` | LangChain | `OpikTracer` callback |
| `from langgraph` | LangGraph | `OpikTracer` with `graph=` |
| `from crewai` | CrewAI | `track_crewai` |
| `import dspy` | DSPy | `OpikCallback` |
| `from google` … `genai` | Google Gemini | `track_genai` |
| `import boto3` … `bedrock` | AWS Bedrock | `track_bedrock` |
| `from llama_index` | LlamaIndex | `LlamaIndexCallbackHandler` |
| `import litellm` | LiteLLM | `OpikLogger` callback |
| `from pydantic_ai` | Pydantic AI | Logfire OTLP bridge |
| `from opik.integrations.adk` / `from google.adk` | Google ADK | `track_adk_agent_recursive` |
| `import ollama` | Ollama | `track_openai` with localhost base_url or manual `@opik.track` |
| `from agents import` / `from openai.agents` | OpenAI Agents SDK | `OpikTracingProcessor` |
| `from haystack` | Haystack | `OpikConnector` |
| `opik-openai` / `trackOpenAI` (TS) | OpenAI (TS) | `trackOpenAI` |
| `opik-vercel` / `OpikExporter` (TS) | Vercel AI SDK | `OpikExporter` |
| `opik-langchain` / `OpikCallbackHandler` (TS) | LangChain.js | `OpikCallbackHandler` |
| `opik-gemini` / `trackGemini` (TS) | Gemini (TS) | `trackGemini` |
3. **Existing Opik usage** — check if `opik` or `@opik.track` is already imported. If so, audit rather than re-instrument.
## Step 3 — Identify the Call Graph
Find:
- **Entrypoint**: the top-level function that kicks off the agent (e.g., `main`, `run`, `agent`, `handle_message`, a route handler, or whatever the user's main orchestration function is)
- **LLM call sites**: functions that call an LLM provider directly
- **Tool functions**: retrieval, search, API calls, or other tool-like operations
- **Existing config classes**: dataclasses, Pydantic models, or plain classes holding model names, temperatures, prompts, or other tunable parameters
### Entrypoint Parameter Rules
The function marked with `entrypoint=True` **must only accept primitive-typed parameters**: `str`, `int`, `float`, `bool`, and `list`/`dict` of primitives. This is because:
- Opik reads the function's type hints to build an **input form in the UI**
- Users will type these values manually in a text field via the Local Runner
- Complex types (Pydantic models, dataclasses, request objects, custom classes) cannot be entered in a UI input field
**If the candidate entrypoint accepts complex types** (e.g., a request model, a config object, a dataclass):
1. **Look higher in the call chain** for a function that already accepts primitives
2. If none exists, **create a thin wrapper function** that accepts only primitives, unpacks them, and calls the original function. Move the `entrypoint=True` decorator to this wrapper.
**Example — bad entrypoint (complex parameter):**
```python
# ❌ DO NOT mark this as entrypoint — RecommendRequest is a Pydantic model
@app.post("/recommend")
async def recommend(request: RecommendRequest):
summary, tool_results = await run_agent(user_message=build_user_message(request))
return RecommendResponse(city=request.city, recommendations=_extract_recommendations(tool_results), summary=summary)
```
**Example — good entrypoint (primitives only):**
```python
@opik.track(name="recommend-agent", entrypoint=True)
async def _run_entrypoint(user_message: str) -> tuple[str, list[dict]]:
"""Opik entrypoint — receives only the user message for Local Runner schema."""
return await run_agent(user_message=user_message)
@app.post("/recommend")
async def recommend(request: RecommendRequest):
summary, tool_results = await _run_entrypoint(user_message=build_user_message(request))
return RecommendResponse(city=request.city, recommendations=_extract_recommendations(tool_results), summary=summary)
```
The wrapper extracts the primitive values from the complex object and delegates to the existing logic. The HTTP handler calls the wrapper instead of the inner function directly, so the trace captures the full execution.
## Step 4 — Add Framework Integrations
For each detected framework, add the appropriate integration at the module level. See the integration table above and `references/integrations.md` for the exact patterns.
**Python examples:**
```python
# OpenAI
from opik.integrations.openai import track_openai
client = track_openai(OpenAI()) # wrap existing client
# Anthropic
from opik.integrations.anthropic import track_anthropic
client = track_anthropic(anthropic.Anthropic())
# LangChain / LangGraph
from opik.integrations.langchain import OpikTracer
tracer = OpikTracer()
# pass config={"callbacks": [tracer]} to invoke()
# LiteLLM inside @opik.track — CRITICAL: pass span context
from opik.opik_context import get_current_span_data
# in every litellm.completion() call, add:
# metadata={"opik": {"current_span_data": get_current_span_data()}}
```
**TypeScript examples:**
```typescript
// OpenAI
import { trackOpenAI } from "opik-openai";
const trackedClient = trackOpenAI(openai);
// Vercel AI SDK
import { OpikExporter } from "opik-vercel";
// set up NodeSDK with OpikExporter
```
## Step 5 — Add `@opik.track` Decorators (Python) or Client Tracing (TypeScript)
### Python
Add `import opik` at the top of each file you instrument.
| Function role | Decorator |
|---|---|
| Entrypoint (top-level agent) | `@opik.track(entrypoint=True, name="<agent-name>")` |
| LLM call | `@opik.track(type="llm")` |
| Tool / retrieval | `@opik.track(type="tool")` |
| Guardrail / validation | `@opik.track(type="guardrail")` |
| Other helper in the call chain | `@opik.track` |
- **Entrypoint parameters must be primitives only** (`str`, `int`, `float`, `bool`, `list`, `dict`). If the natural entrypoint takes a complex type, create a wrapper — see Step 3 "Entrypoint Parameter Rules".
- **Config access must happen inside `@opik.track`**: Any call to `client.get_or_create_config()` and subsequent access of config fields must occur inside a `@opik.track`-decorated function, or in a function called downstream from one. This is how Opik injects config metadata into the current trace. Calling it at module level or outside the traced call stack will raise an error.
- Place the decorator **above** any existing decorators (e.g., above `@app.route`)
- For async functions, `@opik.track` works the same way — no changes needed
- If the function is a **script entrypoint** (not a long-running server), add `opik.flush_tracker()` after the top-level call
### TypeScript
Use the client-based approach:
```typescript
import { Opik } from "opik";
const client = new Opik({ projectName: "<project-name>" });
// In the entrypoint function:
const trace = client.trace({ name: "<agent-name>", input: { ... } });
const span = trace.span({ name: "<operation>", type: "tool", input: { ... } });
// ... logic
span.end({ output: { ... } });
trace.end({ output: { ... } });
await client.flush();
```
For entrypoints that should be discoverable by `opik connect` — note that `params` must only use primitive types (`string`, `number`, `boolean`) since users enter these values in a UI text field:
```typescript
import { track } from "opik";
const myAgent = track(
{ name: "<agent-name>", entrypoint: true, params: [{ name: "query", type: "string" }] },
async (query: string) => { /* ... */ }
);
```
## Step 6 — Conversational Agents: Add `thread_id`
If the agent handles multi-turn conversations (chat bots, support agents, multi-step assistants), wire `thread_id`:
```python
@opik.track(entrypoint=True)
def handle_message(session_id: str, message: str) -> str:
opik.update_current_trace(thread_id=session_id)
return generate_response(session_id, message)
```
Skip this for single-shot agents or batch processing.
## Step 7 — Environment Config
Follow the setup decision tree from the main opik skill:
1. If the project has `.env` / `.env.local` → append `OPIK_API_KEY`, `OPIK_WORKSPACE`, `OPIK_URL_OVERRIDE` (if missing)
2. If no `.env` exists → Python: create/update `~/.opik.config`; TypeScript: create `.env` or `.env.local`
3. Never introduce a second config mechanism
4. Never overwrite existing values
5. Update `.env.example` / `.env.sample` if one exists
6. Set `project_name` in code, not in env files
### `OPIK_URL_OVERRIDE` path rules
The URL suffix depends on where Opik is hosted:
| Deployment | URL format | Example |
|---|---|---|
| Opik Cloud / managed | `<base>/opik/api` | `https://www.comet.com/opik/api` |
| Self-hosted (local) | `<base>/api` | `http://localhost:5173/api` |
- **Cloud/managed**: always append `/opik/api`
- **Self-hosted** (typically `localhost` or an internal hostname): append only `/api` — no `/opik` prefix
- When writing or suggesting an `OPIK_URL_OVERRIDE` value, apply this rule so users don't have to remember it
## Step 8 — Install Dependencies
Print the install command but do NOT run it automatically. Let the user decide.
**Python:**
```
pip install opik
```
Plus any integration packages if needed (most are included in `opik`).
**TypeScript:**
```
npm install opik
```
Plus framework-specific packages: `opik-openai`, `opik-vercel`, `opik-langchain`, `opik-gemini` as needed.
## Step 9 — Verify
After instrumentation, do a quick audit:
- [ ] Every LLM call site is traced (via integration wrapper or `@opik.track`)
- [ ] Exactly one function has `entrypoint=True`
- [ ] The entrypoint function accepts only primitive parameters (`str`, `int`, `float`, `bool`, `list`, `dict`) — no Pydantic models, dataclasses, or custom classes
- [ ] All `get_or_create_config()` calls and config field access happen inside `@opik.track`-decorated functions (or downstream from one)
- [ ] Script entrypoints call `opik.flush_tracker()` (Python) or `await client.flush()` (TypeScript)
- [ ] LiteLLM calls inside `@opik.track` pass `current_span_data` via metadata
- [ ] No hardcoded API keys were introduced
- [ ] Existing tests still import correctly (no circular imports introduced)
## Anti-Patterns to Avoid
- **Double-wrapping**: Don't add `@opik.track(type="llm")` to a function that already uses a framework integration (e.g., `track_openai`). The integration handles tracing.
- **Orphaned LiteLLM traces**: Always pass `current_span_data` when `OpikLogger` is used inside `@opik.track` code.
- **Complex entrypoint parameters**: The entrypoint function must only accept primitives (`str`, `int`, `float`, `bool`, `list`, `dict`). Pydantic models, dataclasses, or custom classes can't be typed into a UI input field. If the natural entrypoint takes a complex type, create a thin wrapper that accepts primitives.
- **Config access outside `@opik.track`**: `get_or_create_config()` and config field reads must happen inside a `@opik.track`-decorated function or downstream from one. Module-level or untraced calls will fail and won't attach config metadata to the trace.
- **Missing entrypoint**: Without `entrypoint=True`, Local Runner (`opik connect`) won't discover the agent.
- **Missing flush**: Scripts that exit without flushing lose trace data.
- **Overwriting config**: Check before writing to `.env` or `~/.opik.config`.
## References
For detailed API signatures and advanced patterns, see:
- `../opik/references/tracing-python.md` — Python SDK reference
- `../opik/references/tracing-typescript.md` — TypeScript SDK reference
- `../opik/references/integrations.md` — All framework integrations
- `../opik/references/observability.md` — Core concepts (traces, spans, threads)
---
> Source: [comet-ml/opik-skills](https://github.com/comet-ml/opik-skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
按说明文件中的顺序排列。
第 1 步——范围
第 2 步 — 检测语言和框架
第 3 步 — 识别调用图
入口点参数规则
第 4 步 — 添加框架集成
文件/命令 -> $ARGUMENTS · *.py · pyproject.toml · requirements.txt · *.ts · *.tsx · package.json · from openai
内容校验值 -> a5c6ca671c36
当前原文的自动摘译,尚未人工审校。
第 1 步——范围
如果提供了
$ARGUMENTS,则将您的工作范围限制在这些文件或目录中。否则,发现项目根并检测主要应用程序代码。第 2 步 — 检测语言和框架
扫描代码库以确定: 语言:Python(查找
*.py、pyproject.toml、requirements.txt)或 TypeScript(查找*.ts、*.tsx、package.json) 正在使用的 LLM 框架 — 搜索这些模式的导入:导入模式 · 框架 · 集成from openai/import OpenAI· OpenAI ·track_openai入口点参数规则
标有
entrypoint=True的函数必须只接受基元类型的参数:基元的str、int、float、bool和list/dict。这是因为: Opik 读取函数的类型提示以在 UI 中构建输入表单 用户将通过本地运行程序在文本字段中手动输入这些值 复杂类型(Pydantic 模型、数据类、请求对象、自定义类)无法在 UI 输入字段中输入