Prompt deployment

Keep prompt content versioned separately from application releases. Ask for the version labeled for an environment, use its content, and attach its id to the model call so every trace shows which prompt version produced it.

Resolve a prompt

import { TracifyClient } from "tracify-sdk";

const client = new TracifyClient({ apiKey: process.env.TRACIFY_API_KEY });

const deployed = await client.getPrompt("support-agent", "production");
const content = deployed.version.content;

from tracify import TracifyClient

client = TracifyClient()

deployed = client.get_prompt("support-agent", "production")
content = deployed["version"]["content"]

The result contains the prompt (id, name, type of text or chat) and the resolved version (id, version, content, variables, labels and the optional model).

Connect the version to the trace

Pass the version id as promptVersionId when you record the model call:

await client.ingest({
  spanType: "llm",
  input: question,
  output: answer,
  promptVersionId: deployed.version.id,
});

client.ingest(
    spanType="llm",
    input=question,
    output=answer,
    promptVersionId=deployed["version"]["id"],
)

The trace viewer then lets you compare runs by prompt version, which is how you tell whether a prompt change helped.

Caching and fallbacks

Prompt responses are cached for 60 seconds by default, so a high-traffic agent does not call the API on every request. Tune it per call:

const deployed = await client.getPrompt("support-agent", "production", {
  cacheTtlMs: 0,
  fallback: lastKnownGoodPrompt,
});

deployed = client.get_prompt(
    "support-agent",
    "production",
    cache_ttl_seconds=0,
    fallback=last_known_good_prompt,
)

Pass cacheTtlMs: 0 in development to see edits immediately. Provide a fallback when the agent must keep working even if the prompt service cannot be reached.

Environments

Use development, staging and production labels to promote a version deliberately: move the label, not the code. Keep the API key on the server.