Relay docs

Prompt library

A Langfuse-style, versioned prompt library. Author prompts once, version every change, label a version as production, and fetch or compile them from any app — or attach them to agents.

#Model

  • A Prompt is the stable container, addressed by a unique name. It has a description, tags and an enabled flag.
  • Each save creates an immutable PromptVersion (version 1, 2, 3, …). A version is either:
    • text — a single Content template, or
    • chat — an array of { role, content } messages.
  • Both can embed {{variables}} (mustache-style). Detected variable names are cached on the version.

#Labels

Labels are movable pointers to a single version:

  • production — the version your apps should use by default. Setting it on a new version moves it off the old one.
  • latest — computed, always the highest version (not assignable).

When resolving a prompt, Relay picks (in order): an explicit version, then a label, then production, then latest.

Tags and labels answer different questions and are filtered separately in the API: a tag is on the prompt and says what it is for; a label is on a version and says which revision to use. GET /v1/prompts accepts ?tag= and ?label= — see the Prompts API.

#Variables & compilation

Compilation replaces provided {{variables}} and leaves unprovided ones intact, so callers can see what's missing:

Template : "You are a support agent for {{company}}. Greet {{customer}}."
Variables: { "company": "Spinneys" }
Result   : "You are a support agent for Spinneys. Greet {{customer}}."
Missing  : ["customer"]

#Authoring in the panel

Prompts lists every prompt with its version count, type, production version, when the latest version was made and how many generations used it in the last 30 days. A / in a name files the prompt in a folder (support/greeting sits in support/); folders list first, and searching or filtering shows matches from every folder by full name.

Opening a prompt shows its versions as a timeline on the left, each with its labels, commit message, age and author. The selected version has five tabs:

  • Prompt — the template, with {{variables}} highlighted; chat prompts show one card per message.
  • Config — the version's optional JSON config.
  • Test — fill in variables and see the compiled result as you type; unset variables stay highlighted.
  • Diff — line diff against another version (the previous one by default).
  • Use prompt — cURL, Python and JavaScript snippets for the fetch and compile endpoints.

Labels are edited in place on the version: + Label adds one (it moves off whichever version had it), × removes one, and Promote to production moves production. New version, Edit from here and Duplicate open the full-page editor, seeded from the selected version. The Metrics tab has per-version volume, cost, latency, errors and scores, and Used by lists the agents that reference the prompt.

#Using prompts

  • From an app — fetch or compile via the Prompts API.
  • From an agent — attach the prompt to an agent; it's resolved (production → latest) and compiled server-side each run, so the agent stays in sync when you publish a new version.