| 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. |
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. At a glance:
- Prepare — install/resolve the target library, locate credentials (without printing them), pick a backend the MCP can read.
- Investigate the target library (API surface, hooks/callbacks, streaming shape, usage/token format, errors).
- Collect findings + a minimal runnable example script.
- Design — pick the pattern, file layout, entrypoint. (Interactive mode pauses for approval here; autonomous mode records it in the report.)
- Implement by cloning the closest existing same-pattern integration.
- Verify the logged data through the Opik MCP (
read/list the trace & spans).
- Test with the language's integration-test harness.
- Document the Fern page and wire its routing.
- 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 / typescript.md.
Language references
- Python → python.md — integration anatomy, shared core modules, mechanism templates, dependency/import rules, test specifics.
- TypeScript → 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.
