Trace Import

Import agent traces from Langfuse and evaluate them, without writing an ATIF trajectory yourself

Agentic Evaluations expect one ATIF trajectory per task, which means whoever runs the agent also writes the conversion. If your agent is already traced in Langfuse, that step is unnecessary: elluminate reads the traces, converts them to ATIF on the server, and stores them as agent trial results in an Agentic experiment. The criteria then run against the converted trajectory exactly as they do for an upload you built yourself.

Two ways in, both from the same dialog:

• Integration: elluminate calls your Langfuse instance and fetches the newest traces.
• Upload file: you export the traces yourself and hand elluminate the JSON, so no connection between the two systems is needed.

What You Need

1. A Langfuse API key pair

The same key pair as for Dataset Integrations: a public key (pk-lf-…) and a secret key (sk-lf-…). The pull is read-only.

Langfuse v4 replaced the trace endpoints with an observations API, and a v3 instance does not serve that one. elluminate detects which of the two your instance answers and reads accordingly, so Langfuse Cloud, v4 and v3 all work with no setting to choose. On v4, scores are read from their own endpoint; if your keys cannot read them, the import still runs and the traces arrive without a reward.

Key scope

Langfuse API keys are project-scoped and have no read-only variant, so the pair you store here also permits writes in that Langfuse project. If your security policy does not allow that, use the Upload file path, which needs no credentials at all.

2. A reachable Langfuse URL

The base URL you configure has to be reachable from wherever elluminate runs.

Your setup	What applies
elluminate Cloud	Your Langfuse must be reachable over the public internet under a resolvable hostname. A URL that resolves to a private address is rejected. If your instance is behind an allowlist, contact support so the outbound addresses can be arranged.
Self-managed elluminate	An internal URL such as http://langfuse-web.langfuse.svc:3000 is supported, and traces never leave your network. Private addresses are rejected by default, so name the URL you intend to use to whoever operates your elluminate deployment and they permit it there.

3. Traces this converter can read

This is the requirement that decides whether an import produces transcripts or empty trials, and it depends on how your agent is instrumented:

• Prompts and completions must sit on GENERATION observations, in their input and output. Trace-level input and output are not read: on an instrumented function they hold the call's arguments and return value rather than messages. Any observation that is not a GENERATION (SPAN, EVENT, and the rest) is not turned into a transcript step, so a tool executed as a span shows up only through the tool call that requested it.
• Messages must be OpenAI-shaped: tool_calls on the assistant turn, and each result as a tool message carrying the matching tool_call_id. If you trace through OpenTelemetry, note that capturing message content is opt-in there; with content capture off, the traces arrive without anything to build a transcript from.
• Every trace needs a task identifier that matches a task in your collection. See below.

4. Task names that match your collection

An Agentic experiment holds one task per collection row, and every imported trace has to name the task it belongs to. The task name is read from one of name, sessionId, userId, id, or any metadata key (metadata.<key>), selected under Advanced → Task name from in the import dialog.

If your traces are named per request (POST /chat), add a stable value in your instrumentation, typically metadata.task_id, and point the import at it. Traces with no value there are reported and skipped rather than guessed at.

Importing Traces

Create the Agentic collection, criterion set, and experiment first, as described in the Agentic Evaluations UI walkthrough. Then:

Step 1: Add the Langfuse integration

On the Collections page, open Import and follow it to the Integrations page: the entry reads Configure Integration while the project has none and Manage Integrations once it has one. Add a Langfuse integration with your base URL and both keys, and use the connection test before saving. This is the same integration used for Dataset Integrations, so an existing one can be reused.

Step 2: Open the import dialog

Open the Agentic experiment and click the upload button. The dialog opens as Upload agent traces on the Upload file tab; switch to Integration and it becomes Import agent traces.

Step 3: Pull and preview

On Integration, select your Langfuse integration and click Preview. Nothing is written yet. Open Filter traces first to narrow what the pull reads, by trace name, session id, a from/to window, tags, and the maximum number of traces. Langfuse applies these before any trace is read, and editing one drops a preview you already have, because the traces it named would no longer be the ones the pull returns.

The preview reports:

• how many traces were read, and how many of them would be imported
• which task names matched a task of this experiment, and which matched none
• traces that carry no recoverable message content and would be stored without a trajectory
• the reason reported for every trace that would be skipped
• the converted ATIF of the first trace, so you can check the conversion before committing to it

For the Upload file tab, drag in a Langfuse export instead. Accepted shapes are the API envelope ({"data": [...]}), a bare array of traces, a single trace object, and JSONL with one trace per line. A v4 export holds observation rows rather than traces; those are grouped back into traces by their trace id. The format is detected from the file, and the same preview follows.

Step 4: Import

Leave Evaluate after upload on to have elluminate rate each criterion against the converted trajectory, and set the Epoch if you are importing a second run of the same tasks into the same experiment. Then click Import.

Each trace is stored under an identity derived from its Langfuse id, so re-running an import after a partial failure fills the gaps instead of duplicating what already arrived: the traces that already landed are skipped and reported, the rest are imported. If every trace in the pull was already imported there is nothing left to select, and the import fails with an error rather than reporting a silent success. To import the same traces again as a separate run, raise the epoch.

A trace whose task name matches no task of this experiment is a different case: the import succeeds, stores nothing for that trace, and lists the reason. The result panel then reads Nothing was stored with the count at zero, which is the same answer the direct ATIF upload gives for the same input.

What the Conversion Produces

Langfuse	ATIF trajectory
GENERATION observations, in wall-clock order	transcript steps; only the messages each generation adds on top of what earlier ones already showed, so a repeated history does not repeat in the transcript
assistant tool_calls	tool_calls on the step, with arguments parsed into structure
tool message with a tool_call_id	a result on the step whose call it answers
usageDetails and costDetails per generation, or the older usage and calculatedTotalCost	per-step prompt, completion, and cached token counts, plus cost
trace latency and total cost	trial duration and cost
the first numeric score between 0 and 1	the trial reward
ERROR-level observations	the trial's error, with the status message
every other observation type (SPAN, EVENT, …)	not steps; their count and types are recorded on the trajectory so a partial conversion is visible

Trace-level tags, environment, and the source trace id are kept on the trajectory, so an imported trial can always be traced back to the Langfuse trace it came from.

Not converted yet

Content blocks in the Anthropic shape (tool_use, tool_result), images, and audio are reported per trace rather than partially converted, so a trace carrying them is not silently reduced to text. If you need these, contact support with an example trace.

Limits

• A pull reads the newest 50 traces by default and at most 200. Filter traces in the dialog sets the max and the server-side filters (trace name, session id, a from/to window, tags); a blank field is not applied. These apply to a pull only, not to an uploaded export file.
• Fetching from Langfuse is bounded by one 60-second budget and a 64 MB total download, and a single trace's detail response may not exceed 25 MB. Traces still outstanding when a budget runs out are reported rather than waited on.
• An uploaded export file may hold up to 5000 traces and 50 MB.
• None of these is a path for backfilling months of history; import the runs you want to evaluate.

Troubleshooting

"carries no message content on any generation"

The trace has no GENERATION observation with message content, so no transcript can be built. The trial is still stored, with this reason attached, so the gap is visible in the experiment. Check whether your instrumentation records prompts and completions at all, and whether it records them on generations rather than on the trace or on spans.

No task name matched a task of this experiment

The values found at the selected source do not correspond to any task of this experiment. An experiment's task set is fixed when the experiment is created, so a row added to the collection afterwards is not one of its tasks and adding one now does not make the trace importable. Either pick a different source under Advanced → Task name from, or create a new experiment on the collection that holds these tasks.

"Langfuse rejected the integration's credentials"

The host answered but refused the keys. Re-key the integration; retrying will not help. Check that the keys belong to the Langfuse project holding the traces.

The base URL is rejected as non-public

The hostname resolves to a private or loopback address. On elluminate Cloud, expose Langfuse under a resolvable public hostname. On a self-managed deployment, an internal URL can be permitted: ask whoever operates the deployment to allow it.

The pull finds no traces, and you know the project has some

Check that the task-name source holds values your collection knows, since a trace whose name matches no task is reported and skipped. A pull reads whatever the integration's key pair can see in its Langfuse project, so also check that the keys belong to the project holding the traces.

The import reports a timeout or a download budget

The pull exceeded its 60-second or 64 MB budget. Traces still outstanding are reported rather than waited on, and nothing is lost: import a smaller batch, or use an export file, which needs no upstream requests.