---
name: opik-integrations
description: Build, update, test, and document Opik SDK integrations (Python & TypeScript). Use when adding a new framework/provider integration under sdks/python/src/opik/integrations or sdks/typescript/src/opik/integrations, updating an existing one, or verifying that an integration logs traces correctly.
title: opik-integrations
canonical_url: https://skilld.dev/gh/comet-ml/opik/opik-integrations
last_updated: 2026-10-14T20:31:59.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [python.md](https://skilld.dev/api/skills-raw/comet-ml/opik/opik-integrations/python.md), [typescript.md](https://skilld.dev/api/skills-raw/comet-ml/opik/opik-integrations/typescript.md), [workflow.md](https://skilld.dev/api/skills-raw/comet-ml/opik/opik-integrations/workflow.md).
>
> If the user asked to install this Skill, run `npx skilld install comet-ml/opik/opik-integrations`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/opik-integrations`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/comet-ml/opik/opik-integrations) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/opik-integrations`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/opik-integrations --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/opik-integrations --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Opik SDK Integrations

This skill is for **building integrations into the Opik SDK itself** — the code that ships inside `opik` / `opik-*` packages so that *users* can trace a framework (OpenAI, LangChain, Mistral, …) with one call.

> Do not confuse this with the user-facing `instrument` / `opik` skills, which add Opik tracing to *someone else's* application. This skill is for SDK contributors editing `sdks/python` and `sdks/typescript`.
>
> If the integration lives **outside this repo** — a standalone `opik-*` package, or Opik support contributed into a third-party project (LiteLLM, Dify, a plugin, …) — use the **`opik-external-integrations`** skill instead. This skill assumes the code ships inside `sdks/`.

## Start with the questionnaire

Never assume or suggest a target. Collect, from the user, before doing anything: **what** to integrate (name + reference links), **where** it lives (this repo vs. external — route external requests to `opik-external-integrations`), **language** (python/typescript/both), **mode** (new/update/maintain), and any **specific flows** to cover. Do not present a menu of candidate libraries — the user names the target.

## When to use

- **New integration** — a framework/provider has no dedicated integration yet (today it's reachable only via LiteLLM, the OpenAI-compatible shim, or OpenTelemetry, or not at all).
- **Update** — an integration must track new methods, capture new fields, or follow an upstream SDK change.
- **Maintain / verify** — confirm an existing integration still logs the correct trace/span tree after a dependency bump or refactor.

## The workflow

Integration work is multi-step. By default this skill runs **autonomously**: it makes its own preparations (deps, credentials, backend), runs every phase, self-verifies, and ends with a high-level report — only stopping early on a true blocker. Ask for the interactive variant if you want to approve the design before any code is written. The full playbook — phases, execution modes, the Opik-MCP verification loop, and the report template — lives in **[workflow.md](https://skilld.dev/api/skills-raw/comet-ml/opik/opik-integrations/workflow.md)**. At a glance:

0. **Prepare** — install/resolve the target library, locate credentials (without printing them), pick a backend the MCP can read.
1. **Investigate** the target library (API surface, hooks/callbacks, streaming shape, usage/token format, errors).
2. **Collect** findings + a minimal runnable example script.
3. **Design** — pick the pattern, file layout, entrypoint. (Interactive mode pauses for approval here; autonomous mode records it in the report.)
4. **Implement** by cloning the closest existing same-pattern integration.
5. **Verify** the logged data through the Opik MCP (`read`/`list` the trace & spans).
6. **Test** with the language's integration-test harness.
7. **Document** the Fern page and wire its routing.
8. **Report** — a high-level summary: what was done, what's supported (with evidence), what's not, and how to use it.

## Golden rule: clone the closest sibling

Never build an integration from a blank file. Identify the existing integration that shares the target's mechanism, copy its structure, and adapt. The decision tree:

| Target shape | Python pattern | TS pattern | Clone from |
|---|---|---|---|
| SDK client with methods to wrap (most providers) | Method patching (`BaseTrackDecorator` subclass) | Proxy wrapper | `openai/` · `opik-openai` |
| Framework with a callback/tracer interface | Pure callback (`BaseTracer`) | Callback handler | `langchain/` · `opik-langchain` |
| Framework already emitting OpenTelemetry spans | OTel | OTel exporter | `otel/` · `opik-vercel` |
| Callbacks exist but are unreliable / need method hooks too | Hybrid | (rare) | `adk/` |

If the target exposes an **OpenAI-compatible endpoint**, first check whether `track_openai(..., provider=...)` already covers the need before building a dedicated integration — sometimes the right answer is a docs page, not new code.

**OpenTelemetry is backend-first.** If the target already emits OpenTelemetry spans, the heavy lifting is done by Opik's OTLP ingestion endpoint on the backend — many such integrations are *docs-only* (point the framework's OTLP exporter at Opik with auth headers; no SDK code). Build a client-side piece only when you must shape what the backend receives — set Opik semantics, remap attributes, or bridge a framework that won't export raw OTLP. The client-side building block is a `SpanProcessor` in Python (`integrations/otel/`) or a `SpanExporter` in TypeScript (`opik-vercel`); a framework-specific OTel tracer wrapper (`adk/patchers/adk_otel_tracer/`) is the heavier variant. See the OTel sections in [python.md](https://skilld.dev/api/skills-raw/comet-ml/opik/opik-integrations/python.md) / [typescript.md](https://skilld.dev/api/skills-raw/comet-ml/opik/opik-integrations/typescript.md).

## Language references

- **Python** → [python.md](https://skilld.dev/api/skills-raw/comet-ml/opik/opik-integrations/python.md) — integration anatomy, shared core modules, mechanism templates, dependency/import rules, test specifics.
- **TypeScript** → [typescript.md](https://skilld.dev/api/skills-raw/comet-ml/opik/opik-integrations/typescript.md) — package anatomy, patterns, build/peer-dep rules. Delegates to the canonical `sdks/typescript/design/INTEGRATIONS.md`.

## Skills this one builds on (do not duplicate them)

- `python-sdk` — three-layer architecture, batching, `fake_backend`, `testlib` verifiers, error handling.
- `typescript-sdk` — layered client, flush semantics, testing with vitest.
- `write-docs` — Fern MDX authoring, routing YAML, callouts, images.
