Implementation:Langfuse Langfuse ParsePromptDependencyTags

Knowledge Sources	Langfuse
Domains	Prompt Management, Dependency Resolution
Last Updated	2026-02-14 00:00 GMT

Overview

Concrete tool for parsing prompt dependency tags and resolving dependency graphs provided by Langfuse. This implementation covers two closely related functions: parsePromptDependencyTags (tag extraction) and PromptService.buildAndResolvePromptGraph (graph traversal and content inlining).

Description

parsePromptDependencyTags is a pure function that extracts structured dependency descriptors from prompt content. It scans the JSON-stringified content for @@@langfusePrompt:...@@@ tags and returns an array of parsed dependencies, each specifying a prompt name and either a version number or a label.

buildAndResolvePromptGraph is a method on PromptService that takes a parent prompt and its parsed dependencies, then recursively traverses the dependency tree. It fetches each referenced prompt from the database, validates constraints (existence, text type, no cycles, depth limit), replaces dependency tags in the content with the resolved child content, and returns the fully expanded prompt along with an adjacency-list graph structure.

Together, these two functions implement the full dependency lifecycle: parse at write time (to store dependency records), and resolve at read time (to inline content).

Usage

Use parsePromptDependencyTags at prompt creation time to extract dependency metadata from user-authored content. The results are stored as PromptDependency records in the database and passed to buildAndResolvePromptGraph for validation.

Use buildAndResolvePromptGraph at both write time (to validate the graph is resolvable) and read time (inside resolvePrompt, which is called by getPrompt) to produce fully expanded prompt content.

Code Reference

Source Location

• Repository: langfuse
• File (parsePromptDependencyTags): packages/shared/src/features/prompts/parsePromptDependencyTags.ts
• Lines: 18-61
• File (buildAndResolvePromptGraph): packages/shared/src/server/services/PromptService/index.ts
• Lines: 274-419

Signature

// Tag parsing
export function parsePromptDependencyTags(
  content: string | object,
): ParsedPromptDependencyTag[]

// Graph resolution (PromptService method)
public async buildAndResolvePromptGraph(params: {
  projectId: string;
  parentPrompt: PartialPrompt;
  dependencies?: ParsedPromptDependencyTag[];
}): Promise<ResolvedPromptGraph>

Import

import { parsePromptDependencyTags } from "@langfuse/shared";
import { PromptService } from "@langfuse/shared/src/server";

I/O Contract

Inputs (parsePromptDependencyTags)

Name	Type	Required	Description
content	string | object	Yes	The prompt content to scan for dependency tags. Can be a plain string (Text prompt) or an array of chat message objects (Chat prompt). The function JSON-stringifies the input before scanning, so nested tags in message content fields are found.

Outputs (parsePromptDependencyTags)

Name	Type	Description
ParsedPromptDependencyTag[]	Array	An array of parsed dependency descriptors. Each element is one of two shapes: { name: string, type: "version", version: number } for version-pinned dependencies, or { name: string, type: "label", label: string } for label-based dependencies. Duplicates are removed (deduplication is based on the raw tag string).

Inputs (buildAndResolvePromptGraph)

Name	Type	Required	Description
projectId	string	Yes	The project ID scoping the dependency resolution.
parentPrompt	PartialPrompt	Yes	The root prompt to resolve. PartialPrompt includes: id, prompt (content), name, version, labels.
dependencies	ParsedPromptDependencyTag[]	No	Pre-parsed dependencies. If provided, skips the database lookup for the root prompt's dependencies. If omitted, dependencies are fetched from the PromptDependency table.

Outputs (buildAndResolvePromptGraph)

Name	Type	Description
graph	PromptGraph | null	An adjacency-list representation of the dependency tree. Contains a root reference (id, name, version) and a dependencies record mapping parent prompt IDs to arrays of child prompt references. Returns null if the prompt has no dependencies.
resolvedPrompt	Prompt["prompt"]	The fully expanded prompt content with all dependency tags replaced by the resolved content of the referenced prompts. The type matches the original prompt content type (string for text prompts, array for chat prompts).

Usage Examples

Parse Version-Pinned and Label-Based Dependencies

import { parsePromptDependencyTags } from "@langfuse/shared";

const content = `You are a helpful assistant.
@@@langfusePrompt:name=formatting-rules|version=3@@@
@@@langfusePrompt:name=safety-guidelines|label=production@@@
Please respond to the user.`;

const deps = parsePromptDependencyTags(content);
// Result:
// [
//   { name: "formatting-rules", type: "version", version: 3 },
//   { name: "safety-guidelines", type: "label", label: "production" }
// ]

Parse Dependencies from Chat Messages

const chatContent = [
  {
    role: "system",
    content: "@@@langfusePrompt:name=persona|label=latest@@@ Answer questions.",
  },
  { role: "user", content: "{{user_input}}" },
];

const deps = parsePromptDependencyTags(chatContent);
// Result:
// [
//   { name: "persona", type: "label", label: "latest" }
// ]

Resolve a Dependency Graph

import { PromptService } from "@langfuse/shared/src/server";

const promptService = new PromptService(prisma, redis);

const result = await promptService.buildAndResolvePromptGraph({
  projectId: "proj_abc123",
  parentPrompt: {
    id: "prompt_001",
    name: "main-prompt",
    version: 1,
    labels: ["latest"],
    prompt: "Instructions: @@@langfusePrompt:name=shared-rules|version=2@@@ Now answer: {{question}}",
  },
  dependencies: [
    { name: "shared-rules", type: "version", version: 2 },
  ],
});

// result.resolvedPrompt might be:
// "Instructions: Always be concise and factual. Now answer: {{question}}"
//
// result.graph might be:
// {
//   root: { id: "prompt_001", name: "main-prompt", version: 1 },
//   dependencies: {
//     "prompt_001": [{ id: "prompt_xyz", name: "shared-rules", version: 2 }]
//   }
// }

Handling Malformed Tags (Silently Skipped)

const content = `
@@@langfusePrompt:name=valid|version=1@@@
@@@langfusePrompt:version=1|name=wrong-order@@@
@@@langfusePrompt:name=missing-second-part@@@
@@@langfusePrompt:name=too|many|parts@@@
`;

const deps = parsePromptDependencyTags(content);
// Result: only the first tag is valid
// [
//   { name: "valid", type: "version", version: 1 }
// ]
// The others are silently skipped:
// - "wrong-order": name= is not the first parameter
// - "missing-second-part": only 1 part, needs exactly 2
// - "too|many|parts": 3 parts, needs exactly 2

Related Pages

Implements Principle

• Principle:Langfuse_Langfuse_Prompt_Dependency_Graph