Migration Skills

Overview

The migration Agent Skills teach your coding agent how to move an AI application's traces from another observability platform to Confident AI's OpenTelemetry endpoint. The agent finds every integration with the old platform in your codebase, works out which SDK version each service runs, and then takes one of two routes:

• Switch to confident-trace (the default): replace the old SDK with the Python or TypeScript confident-trace SDK, rewriting its calls to init(), span, update_trace(), and update_span() while keeping the same span names, nesting, users, sessions, tags, and metadata.
• Export over OpenTelemetry: when the old SDK is built on OpenTelemetry and you want to keep it for now, add an OTLP exporter that sends the spans it already creates to Confident AI, without rewriting your instrumentation.

There's one skill per platform you're migrating from:

Installation

npx skills add confident-ai/confident-skills --skill "confident-migrate-langfuse"

/plugin marketplace add confident-ai/confident-skills
/plugin install confident-trace@confident-skills
/reload-plugins

git clone https://github.com/confident-ai/confident-skills
cp -r confident-skills/plugins/confident-trace/skills/confident-migrate-langfuse .claude/skills/

Prerequisites

• Python 3.10+ or Node.js 22+
• A project-scoped CONFIDENT_API_KEY for export to Confident AI

Langfuse

The confident-migrate-langfuse skill moves tracing from Langfuse to Confident AI. What changes depends on the Langfuse SDK version in your app, not the Langfuse server version, and every version can move straight to confident-trace, so there's no need to upgrade Langfuse first.

When It Triggers

Migrate this app from Langfuse to Confident AI.
Replace @observe and langfuse_context with confident-trace.
Swap our observeOpenAI wrapper and Langfuse CallbackHandler for confident-trace.
Keep our Langfuse instrumentation but also export the spans to Confident AI.

Choosing a Method

The skill defaults to a full switch and only keeps Langfuse in place when you ask it to:

Langfuse v1, v2, and TypeScript v3 send traces through Langfuse's own ingestion API rather than OpenTelemetry, so they only support the full switch.

For the OpenTelemetry method, the agent adds a span processor to the tracer provider Langfuse already uses, next to Langfuse's own export:

import os

from langfuse import get_client
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import BatchSpanProcessor

langfuse = get_client()

trace.get_tracer_provider().add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(
            endpoint="https://otel.confident-ai.com/v1/traces",
            headers={"x-confident-api-key": os.environ["CONFIDENT_API_KEY"]},
        )
    )
)

import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";

const sdk = new NodeSDK({
  spanProcessors: [
    new LangfuseSpanProcessor(),
    new BatchSpanProcessor(
      new OTLPTraceExporter({
        url: "https://otel.confident-ai.com/v1/traces",
        headers: { "x-confident-api-key": process.env.CONFIDENT_API_KEY! },
      }),
    ),
  ],
});
sdk.start();

When you're ready to cut over in Python, Langfuse(blocked_instrumentation_scopes=["langfuse-sdk"]) stops the export to Langfuse while spans keep reaching Confident AI.

The agent explains this method's limits before using it:

• The Langfuse keys must stay set in Python, because Langfuse creates no spans without them.
• Langfuse's sampling and masking also shape what Confident AI receives in Python. In TypeScript, masking belongs to LangfuseSpanProcessor, so data masked for Langfuse reaches Confident AI unmasked.
• Every span on the provider is exported, including HTTP client and database spans from other instrumentations.
• Scores, prompts, and datasets aren't sent over OpenTelemetry.

What Changes in Your Codebase

1. Find every Langfuse integration

   The agent searches for langfuse and @langfuse/* imports, @observe, langfuse_context, get_client(), langfuse.trace(), trace.generation(), langfuse.openai, observeOpenAI, LangfuseMedia, LangfuseSpanProcessor, the Langfuse LangChain CallbackHandler, and LANGFUSE_* environment variables.

   Migrate this app from Langfuse to Confident AI.

2. Confirm the SDK version

   It runs pip show langfuse, npm ls langfuse, or npm ls @langfuse/tracing for each service, since Python and TypeScript services in one repository can be on different versions, and stops to ask if the version is unclear.

3. Rewrite the tracing code

   For the full switch, following the reference for that version, the agent calls init() once, swaps provider wrappers for the plain client, renames @observe to @span, and moves trace and span fields onto update_trace() and update_span(). A Langfuse session ID becomes a thread ID.

   Python example (Langfuse v3)

   from langfuse import get_client, observe
   
   langfuse = get_client()
   
   @observe()
   def support_chat(question: str) -> str:
       langfuse.update_current_trace(
           name="support-chat",
           user_id="user-7",
           session_id="session-42",
           tags=["support"],
       )
       return answer(question)

   from confident_trace import span, update_trace
   
   @span
   def support_chat(question: str) -> str:
       update_trace(
           name="support-chat",
           user_id="user-7",
           thread_id="session-42",
           tags=["support"],
       )
       return answer(question)

   Generations around model calls that automatic instrumentation already covers are dropped; the agent keeps an LLM span only for model calls it doesn't cover.

4. Point the export at Confident AI

   Both routes send to Confident AI's OTLP/HTTP traces endpoint, and the agent swaps the Langfuse settings for Confident AI's:

   Langfuse	Confident AI
   LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY	CONFIDENT_API_KEY
   LANGFUSE_HOST, LANGFUSE_BASEURL, LANGFUSE_BASE_URL	Nothing for US projects, CONFIDENT_OTEL_ENDPOINT for EU or self-hosted

   US projects export to https://otel.confident-ai.com/v1/traces by default. EU projects set CONFIDENT_OTEL_ENDPOINT to https://eu.otel.confident-ai.com/v1/traces, and self-hosted deployments set it to their own OTLP/HTTP traces URL. To compare both platforms during the switch, point CONFIDENT_OTEL_ENDPOINT at an OpenTelemetry Collector that sends to both.

5. Leave prompt, dataset, and score calls alone

   Calls like get_prompt(), create_dataset(), create_dataset_item(), and score() use the Langfuse API, not tracing. The agent doesn't delete or rewrite them; it lists them for you and keeps the langfuse package installed if any remain.

6. Verify and report

   The agent runs the app once and confirms the trace appears in your project's Observatory, then summarizes every change and what's left for you: setting CONFIDENT_API_KEY, an EU or self-hosted endpoint, any model calls it couldn't map, and the Langfuse API calls it left in place.

   export CONFIDENT_API_KEY="confident_us_proj_..."
   python main.py

To do the same migration by hand, follow the guide for your SDK version: v1, v2, v3, or v4.

FAQs

Next Steps

Last updated on October 20, 2026