In Traccia, a prompt is a named, versioned artifact: the system and user messages (or free-form text) your models see. You edit it in the app, pin a version as live for production, and your services fetch that pin at runtime. Bad outputs in Traces then connect back to the exact prompt version that produced them, so you can fix the wording and promote with confidence.

Where To Start In The App

Open Evaluate → Prompts. Create a prompt, save versions as you iterate, try changes in the Prompt Playground, then use Promote To Production when a version is ready for live traffic.

Why Version Prompts?

Copying prompts into source control (or Slack) works until someone updates production without telling the rest of the team. A registry gives you a single place to answer: what is live right now?, what changed?, and who shipped it?

Immutable versions: every save creates a new version with a version note. Past versions are never overwritten. To change content, save again; the history rail keeps every snapshot.
Version notes: short messages that describe what changed in that save (similar to a commit message). Use these to explain the delta between versions.
Tags: optional labels on the prompt itself (for example support) so you can find and group prompts in the library.
Deploy labels: pointers like production or latest that name which version is live for that purpose. Moving a label is how you promote or roll back.
Protected production: only people with promote access can move the production label.

Create And Edit

Click New Prompt and give it a clear name (for example "Support Reply"). Traccia stores a stable id derived from that name for use in code.
Optionally add tags for filtering. Choose Chat Messages or Single Text.
Write the content. Use placeholders like {{question}} for values your app fills in at runtime.
Add a version note, then Save As New Version. Each save appends to the left-hand history with a timestamp.

Can't Edit An Old Version In Place?

That's intentional. Opening an older version loads it into the editor as a starting point; saving always creates a new version so you never lose what ran in production.

Promote, Duplicate, Delete

Promote To Production: points the production label at the selected version. Prefer attaching an experiment as evidence. You can also choose Promote Without Evidence and enter an override reason (audited). Apps that load by that label pick it up on their next cache refresh.
Delete: trash icon on the Prompts library list (with confirm). Also available under the header ⋮ menu on the prompt detail page.
Duplicate Prompt: from the header ⋮ menu on the detail page. Creates a separate prompt from a chosen version (use this instead of branching).
Rollback: promote an older version again. Same gesture as promote; no redeploy required.

Variables

Templates use double-brace placeholders only, for example {{customer_name}}. At compile time, missing required variables fail loudly; unexpected extras are ignored with a warning. Conditional Mustache-style logic is not supported.

Metrics

Prompt detail is organized into tabs: Editor, Metrics, and Connections. On Metrics you get summary cards (total calls, cost, tokens, typical latency), By Version, and Recent Calls that deep-link into Traces. Lists paginate when you have many versions or calls.

Usage comes from traced LLM generation spans. After load and compile in the SDK, those spans include traccia.prompt.id and traccia.prompt.version_id, so Metrics can group cost, tokens, and latency by version for this prompt.

Connections And Share

Linked agents: on the Connections tab, optionally link one or more agents. In Prompt Playground, Policy Sandbox then prefers policies scoped to those agents (cost, latency, tokens, model).
AI system registry: optionally attach the prompt to an AI system in Governance Hub so evidence packs can list which prompts belong to that system.
Download all prompts: from the Prompts library, download a JSON backup of prompts, versions, and labels (secrets in tools or config are stripped). Hover the button for a short explanation.
Auditor packet: after promote (or anytime from prompt detail), download JSON with version diff, experiment evidence or override reason, and who promoted. Useful for compliance reviews.

Load In Your App

Python and TypeScript SDKs fetch by name and label with a short TTL cache, stale-while-revalidate, and an optional fallback body for outages. Compiling stamps the active span with traccia.prompt.* identity attributes.

Full guide: Prompts in the SDK

Try Before You Promote

Use the Prompt Playground to compare wording and models side by side (with latency, tokens, and cost), then save a new version here and promote when you are ready.

Related: Prompt Playground · SDK Prompts · Traces · Governance Hub