Trace-Import

Importieren Sie Agent-Traces aus Langfuse und evaluieren Sie sie, ohne selbst eine ATIF-Trajectory zu schreiben

Agentic Evaluations erwarten pro Task eine ATIF-Trajectory. Wer den Agenten ausführt, schreibt damit auch die Konvertierung. Läuft Ihr Agent bereits mit Langfuse-Tracing, entfällt dieser Schritt: elluminate liest die Traces, konvertiert sie serverseitig nach ATIF und legt sie als Agent-Trial-Ergebnisse in einem Agentic-Experiment ab. Die Kriterien werten anschließend die konvertierte Trajectory aus, genau wie bei einem Upload, den Sie selbst erzeugt haben.

Zwei Wege, ein Dialog:

• Integration: elluminate ruft Ihre Langfuse-Instanz auf und holt die neuesten Traces.
• Datei hochladen: Sie exportieren die Traces selbst und übergeben elluminate das JSON. Zwischen beiden Systemen ist dann keine Verbindung nötig.

Was Sie benötigen

1. Ein Langfuse-API-Key-Paar

Dasselbe Key-Paar wie für die Dataset Integrations: einen Public Key (pk-lf-…) und einen Secret Key (sk-lf-…). Der Pull liest nur.

Langfuse v4 hat die Trace-Endpoints durch eine Observations-API ersetzt, die eine v3-Instanz nicht bedient. elluminate erkennt, welche der beiden Ihre Instanz beantwortet, und liest entsprechend. Langfuse Cloud, v4 und v3 funktionieren also ohne Einstellung. Unter v4 kommen Scores von einem eigenen Endpoint: Dürfen Ihre Keys ihn nicht lesen, läuft der Import trotzdem, die Traces kommen dann ohne Reward an.

Gültigkeitsbereich der Keys

Langfuse-API-Keys gelten für ein ganzes Projekt und existieren nicht als Read-only-Variante. Das hier gespeicherte Paar erlaubt also auch Schreibzugriffe in diesem Langfuse-Projekt. Lässt Ihre Sicherheitsrichtlinie das nicht zu, nutzen Sie Datei hochladen, dieser Weg braucht keine Credentials.

2. Eine erreichbare Langfuse-URL

Die konfigurierte Base URL muss von dort aus erreichbar sein, wo elluminate läuft.

Ihr Setup	Was gilt
elluminate Cloud	Ihre Langfuse-Instanz muss über einen auflösbaren Hostnamen aus dem Internet erreichbar sein. Eine URL, die auf eine private Adresse auflöst, wird abgewiesen. Steht Ihre Instanz hinter einer Allowlist, wenden Sie sich an den Support, damit die ausgehenden Adressen hinterlegt werden können.
elluminate On-Premise	Eine interne URL wie http://langfuse-web.langfuse.svc:3000 wird unterstützt, und die Traces verlassen Ihr Netz nicht. Private Adressen sind standardmäßig abgewiesen. Nennen Sie die vorgesehene URL denjenigen, die Ihr elluminate-Deployment betreiben, damit sie dort freigegeben wird.

3. Traces, die dieser Konverter lesen kann

Diese Voraussetzung entscheidet, ob ein Import Transkripte oder leere Trials erzeugt, und hängt daran, wie Ihr Agent instrumentiert ist:

• Prompts und Completions müssen auf GENERATION-Observations liegen, in deren input und output. Input und Output auf Trace-Ebene werden nicht gelesen: bei einer instrumentierten Funktion stehen dort Aufrufargumente und Rückgabewert, keine Messages. Jede Observation, die keine GENERATION ist (SPAN, EVENT und die übrigen), wird nicht zu einem Transkript-Schritt. Ein Tool, das als Span läuft, erscheint deshalb nur über den Tool-Aufruf, der es angefordert hat.
• Messages müssen der OpenAI-Form folgen: tool_calls am Assistant-Turn, jedes Ergebnis als tool-Message mit passender tool_call_id. Wenn Sie über OpenTelemetry tracen: das Erfassen von Message-Inhalten ist dort Opt-in. Ist es aus, kommen die Traces ohne Material für ein Transkript an.
• Jeder Trace braucht eine Task-Kennung, die zu einem Task Ihrer Collection passt. Siehe unten.

4. Task-Namen, die zu Ihrer Collection passen

Ein Agentic-Experiment hält pro Collection-Zeile einen Task, und jeder importierte Trace muss den Task benennen, zu dem er gehört. Der Task-Name wird aus name, sessionId, userId, id oder einem beliebigen Metadaten-Schlüssel (metadata.<key>) gelesen, auswählbar im Import-Dialog unter Erweitert → Task-Name aus.

Sind Ihre Traces pro Request benannt (POST /chat), hinterlegen Sie in der Instrumentierung einen stabilen Wert, üblicherweise metadata.task_id, und richten den Import darauf aus. Traces ohne Wert an dieser Stelle werden gemeldet und übersprungen, nicht geraten.

Traces importieren

Legen Sie zuerst Agentic-Collection, Criterion Set und Experiment an, wie im UI-Walkthrough der Agentic Evaluations beschrieben. Dann:

Schritt 1: Langfuse-Integration hinzufügen

Öffnen Sie auf der Collections-Seite Importieren und folgen Sie dem Eintrag zur Seite Integrationen: er heißt Integration konfigurieren, solange das Projekt keine hat, und Integrationen verwalten, sobald eine existiert. Fügen Sie dort eine Langfuse-Integration mit Base URL und beiden Keys hinzu und nutzen Sie vor dem Speichern den Verbindungstest. Es ist dieselbe Integration wie bei den Dataset Integrations, eine bestehende können Sie also weiterverwenden.

Schritt 2: Import-Dialog öffnen

Öffnen Sie das Agentic-Experiment und klicken Sie auf den Upload-Button. Der Dialog öffnet als Agent-Traces hochladen im Tab Datei hochladen. Wechseln Sie auf Integration, dann heißt er Agent-Traces importieren.

Schritt 3: Pull und Vorschau

Wählen Sie unter Integration Ihre Langfuse-Integration und klicken Sie auf Vorschau. Geschrieben wird dabei nichts. Öffnen Sie vorher Traces filtern, um einzugrenzen, was der Pull liest: Trace-Name, Session-ID, Zeitfenster von/bis, Tags und die maximale Anzahl Traces. Langfuse wendet diese an, bevor ein Trace gelesen wird, und das Ändern eines Filters verwirft eine bestehende Vorschau, da die dort genannten Traces nicht mehr die wären, die der Pull liefert.

Die Vorschau zeigt:

• wie viele Traces gelesen wurden und wie viele davon importiert würden
• welche Task-Namen zu einem Task dieses Experiments passen und welche zu keinem
• Traces ohne verwertbaren Message-Inhalt, die ohne Trajectory gespeichert würden
• den gemeldeten Grund für jeden Trace, der übersprungen würde
• die konvertierte ATIF-Trajectory des ersten Traces, sodass Sie die Konvertierung prüfen können, bevor Sie sie übernehmen

Im Tab Datei hochladen ziehen Sie stattdessen einen Langfuse-Export hinein. Akzeptiert werden die API-Hülle ({"data": [...]}), ein reines Array von Traces, ein einzelnes Trace-Objekt und JSONL mit einem Trace pro Zeile. Ein v4-Export enthält Observation-Zeilen statt Traces; diese werden anhand ihrer Trace-ID wieder zu Traces gruppiert. Das Format wird aus der Datei erkannt, danach folgt dieselbe Vorschau.

Schritt 4: Import

Lassen Sie Nach dem Hochladen bewerten aktiv, damit elluminate jedes Kriterium an der konvertierten Trajectory auswertet, und setzen Sie die Epoche, wenn Sie einen zweiten Durchlauf derselben Tasks in dasselbe Experiment importieren. Dann klicken Sie auf Importieren.

Jeder Trace wird unter einer Identität abgelegt, die aus seiner Langfuse-ID abgeleitet ist. Ein Import, der nach einem Teilausfall erneut läuft, füllt so die Lücken statt bereits Angekommenes zu verdoppeln: bereits importierte Traces werden übersprungen und gemeldet, der Rest wird importiert. Waren alle Traces des Pulls schon importiert, bleibt nichts zu übernehmen, und der Import schlägt mit einem Fehler fehl statt einen stillen Erfolg zu melden. Für einen zweiten Durchlauf derselben Traces erhöhen Sie die Epoche.

Ein Trace, dessen Task-Name zu keinem Task dieses Experiments passt, ist ein anderer Fall: Der Import läuft erfolgreich durch, speichert für diesen Trace nichts und nennt den Grund. Die Ergebnisanzeige meldet dann Nichts gespeichert mit Anzahl null, also dieselbe Antwort, die der direkte ATIF-Upload bei gleicher Eingabe gibt.

Was die Konvertierung erzeugt

Langfuse	ATIF-Trajectory
GENERATION-Observations in zeitlicher Reihenfolge	Transkript-Schritte, und zwar nur die Messages, die eine Generation gegenüber den vorherigen ergänzt. Eine wiederholte History wiederholt sich damit nicht im Transkript
tool_calls am Assistant-Turn	tool_calls am Schritt, Argumente als Struktur geparst
tool-Message mit tool_call_id	Ergebnis am Schritt, dessen Aufruf sie beantwortet
usageDetails und costDetails pro Generation, alternativ die älteren usage und calculatedTotalCost	Prompt-, Completion- und Cached-Token pro Schritt, dazu die Kosten
Trace-Latenz und Gesamtkosten	Dauer und Kosten des Trials
der erste numerische Score zwischen 0 und 1	Reward des Trials
Observations auf Level ERROR	Fehler des Trials, mit Statusmeldung
jeder andere Observation-Typ (SPAN, EVENT, …)	keine Schritte. Anzahl und Typen werden an der Trajectory festgehalten, damit eine unvollständige Konvertierung sichtbar bleibt

Tags, Environment und die Quell-Trace-ID bleiben an der Trajectory erhalten. Ein importierter Trial lässt sich damit immer auf den Langfuse-Trace zurückführen, aus dem er entstanden ist.

Noch nicht konvertiert

Content-Blöcke in der Anthropic-Form (tool_use, tool_result), Bilder und Audio werden pro Trace gemeldet statt teilweise konvertiert. Ein Trace mit solchen Inhalten wird also nicht stillschweigend auf Text reduziert. Wenn Sie das benötigen, wenden Sie sich mit einem Beispiel-Trace an den Support.

Grenzen

• Ein Pull liest standardmäßig die 50 neuesten Traces und höchstens 200. Über Traces filtern im Dialog setzen Sie das Maximum und die serverseitigen Filter (Trace-Name, Session-ID, Zeitfenster von/bis, Tags); leere Felder werden nicht angewendet. Das gilt nur für den Pull, nicht für eine hochgeladene Exportdatei.
• Das Abrufen aus Langfuse ist durch ein Zeitbudget von 60 Sekunden und 64 MB Gesamtdownload begrenzt, und die Detailantwort eines einzelnen Traces darf 25 MB nicht überschreiten. Traces, die bei Ablauf eines Budgets noch offen sind, werden gemeldet statt abgewartet.
• Eine hochgeladene Exportdatei darf bis zu 5000 Traces und 50 MB umfassen.
• Für das Nachladen monatelanger Historie ist keiner dieser Wege gedacht: importieren Sie die Durchläufe, die Sie evaluieren wollen.

Fehlerbehebung

„carries no message content on any generation"

Der Trace hat keine GENERATION-Observation mit Message-Inhalt, ein Transkript ist daraus nicht zu bauen. Der Trial wird trotzdem gespeichert, mit diesem Grund, sodass die Lücke im Experiment sichtbar bleibt. Prüfen Sie, ob Ihre Instrumentierung Prompts und Completions überhaupt erfasst und ob sie das an Generations tut statt am Trace oder an Spans.

Kein Task-Name passt zu einem Task dieses Experiments

Die Werte an der gewählten Quelle entsprechen keinem Task dieses Experiments. Die Task-Menge eines Experiments steht mit seiner Erstellung fest: eine später zur Collection hinzugefügte Zeile ist keiner seiner Tasks, und sie jetzt aufzunehmen macht den Trace nicht importierbar. Wählen Sie unter Erweitert → Task-Name aus eine andere Quelle oder legen Sie ein neues Experiment auf der Collection an, die diese Tasks enthält.

„Langfuse rejected the integration's credentials"

Der Host hat geantwortet, die Keys aber abgelehnt. Hinterlegen Sie neue Keys in der Integration, ein erneuter Versuch hilft nicht. Prüfen Sie, ob die Keys zu dem Langfuse-Projekt gehören, in dem die Traces liegen.

Die Base URL wird als nicht öffentlich abgewiesen

Der Hostname löst auf eine private oder Loopback-Adresse auf. In elluminate Cloud stellen Sie Langfuse unter einem auflösbaren öffentlichen Hostnamen bereit. In einem On-Premise-Deployment ist eine interne URL freigebbar: wenden Sie sich an diejenigen, die das Deployment betreiben.

Der Pull findet keine Traces, obwohl das Projekt welche hat

Prüfen Sie, ob an der gewählten Task-Namen-Quelle Werte stehen, die Ihre Collection kennt: ein Trace, dessen Name zu keinem Task passt, wird gemeldet und übersprungen. Ein Pull liest, was das Key-Paar der Integration in seinem Langfuse-Projekt sehen kann. Prüfen Sie daher auch, ob die Keys zu dem Projekt gehören, in dem die Traces liegen.

Der Import meldet ein Timeout oder ein Download-Budget

Der Pull hat sein Budget von 60 Sekunden oder 64 MB überschritten. Noch offene Traces werden gemeldet statt abgewartet, verloren geht nichts: importieren Sie ein kleineres Paket oder nutzen Sie eine Exportdatei, die keine Anfragen an Langfuse braucht.