Agent prompts

defineLangfuseInstructions() loads a Langfuse text prompt into an Eve instructions slot. The integration records the resolved prompt name and version so the model generations can link back to it in Langfuse.

Main agent prompt

Create a text prompt such as agent/base in Langfuse. Then place the resolver in the root agent's instructions directory:

import { defineLangfuseInstructions } from "@vantezzen/langfuse-eve/instructions";

export default defineLangfuseInstructions("agent/base", {
  fallback: "You are a concise support agent.",
  label: process.env.LANGFUSE_PROMPT_LABEL ?? "production",
});

This becomes a system instruction and is included in every model call for the root agent. Using agent/instructions/identity.ts also lets it coexist with other files in agent/instructions/.

Supporting prompts

An agent can load several instruction files. Mark supporting prompts as non-primary so the main identity prompt receives Langfuse's native prompt link. Every resolved prompt remains available in trace metadata.

import { defineLangfuseInstructions } from "@vantezzen/langfuse-eve/instructions";

export default defineLangfuseInstructions("shared/compliance", {
  key: "compliance",
  primary: false,
});

Declared subagent prompt

Declared subagents have their own Eve directory and do not use the root agent's authored instructions. Put a prompt resolver inside each subagent that needs a separate identity:

import { defineAgent } from "eve";

export default defineAgent({
  description: "Research questions before the parent agent answers.",
  model: "openai/gpt-5.4-mini",
});

import { defineLangfuseInstructions } from "@vantezzen/langfuse-eve/instructions";

export default defineLangfuseInstructions("agents/researcher", {
  fallback: "Research the question and separate sourced facts from inference.",
  label: process.env.LANGFUSE_PROMPT_LABEL ?? "production",
});

The root agent's generations link to agents/support; the researcher's generations link to agents/researcher. Eve parent lineage keeps both agents in the same Langfuse session.

Children created through Eve's built-in agent tool are copies of the root agent, so they use the root instructions. The separate prompt file is needed for declared subagents.

Prompt variables

Return string variables from the Eve resolve context. Langfuse compiles them with its native {{variable}} syntax:

export default defineLangfuseInstructions("agents/account-analyst", {
  label: "production",
  variables: ({ channel, session }) => ({
    accountId:
      session.auth.current?.attributes.accountId?.toString() ?? "unknown",
    channel: channel.kind,
  }),
});

Refresh and caching

Prompts resolve when a session starts by default. Use turn refresh for long-lived sessions that should pick up label changes between turns:

defineLangfuseInstructions("agents/support", {
  cacheTtlSeconds: 60,
  refresh: "turn",
});

refresh controls when Eve asks the Langfuse client. cacheTtlSeconds controls whether that request reaches Langfuse or uses the client's cache.

Fallbacks

A fallback keeps the agent available if Langfuse cannot return the prompt:

defineLangfuseInstructions("agents/support", {
  fallback: "You are a concise support agent.",
});

Fallback content is identified in trace metadata, but it does not receive a native prompt version link because it is not a stored Langfuse prompt version.

Custom prompt loading

When application code fetches a prompt directly, record it while an Eve context is active:

import { trackLangfusePrompt } from "@vantezzen/langfuse-eve/instructions";

const prompt = await langfuse.prompt.get("agents/custom");
trackLangfusePrompt(prompt, { key: "custom", primary: true });