Langfuse round-trip end to end

This guide wires the optional path that lands a uservane.satisfaction session score in your Langfuse project without giving UserVane your Langfuse credentials.

Prerequisites: a UserVane project (publishable + secret keys), a Langfuse project, and an agent route that can set sessionId.

1. One session id for the run

On the server that runs the model:

const sessionId = crypto.randomUUID();

await propagateAttributes({ sessionId }, async () => {
  // generateText / streamText ...
});

That is the id Langfuse will attach to the session. Reuse it for UserVane minting.

2. Mint a bound show-token

Still on the server, with the UserVane secret key:

import { mintFeedbackToken } from "@uservane/vercel-ai/server";

const { tokens } = await mintFeedbackToken({
  secretKey: process.env.USERVANE_SECRET_KEY!,
  respondentId: userId,
  sessionId,
  surveyId: surveyIdFromYourConfig,
});

const showToken = tokens[surveyIdFromYourConfig];

Return sessionId, surveyId, and showToken to the client (stream data part, JSON field, etc.). If tokens is empty, skip showing feedback for this run (gated).

3. Client bind + resolve

const { bind, resolveTask } = useUserVane();

bind({ surveyId, showToken, sessionId });

// when the user's outcome is actually done:
resolveTask({ outcome: "completed" });

User rates via InlineFeedback (or headless complete). Submit includes the attested session id.

4. Cron: push pending scores

import { pushPendingScores } from "@uservane/langfuse-push";

export async function runPush() {
  return pushPendingScores({
    uservane: { secretKey: process.env.USERVANE_SECRET_KEY! },
    langfuse: {
      publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
      secretKey: process.env.LANGFUSE_SECRET_KEY!,
    },
  });
}

Schedule it (Vercel cron, Cloudflare Cron Trigger, k8s CronJob, …). Re-run with includeFailed: true after fixing Langfuse credentials.

5. Verify in Langfuse

Open the session that used your sessionId. You should see a session-level score named uservane.satisfaction (unless you overrode scoreName) with the rating value and optional comment.

Failure modes

Symptom	Likely cause
Score never appears	Adapter not running; or response was unlinked (no `bind`)
`failed` count rises	Langfuse auth/host error; fix env, then `includeFailed: true`
401 on mint or poll	Secret key wrong, or publishable key used by mistake
401 on submit with session	Client `sessionId` does not match token-attested value