Prompts

Step 1: Read the Prompts CLI Docs

See CLI Setup.

Then specifically read the Prompts CLI guide:

langwatch docs prompt-management/cli

CRITICAL: Do NOT guess how to use the Prompts CLI. Read the docs first.

Step 2: Initialize Prompts in the Project

langwatch prompt init

Creates a prompts.json config and a prompts/ directory in the project root.

Step 3: Create a Managed Prompt for Each Hardcoded Prompt

Scan the codebase for hardcoded prompt strings (system messages, instructions). For each:

langwatch prompt create <name>

Edit the generated .prompt.yaml file to match the original prompt content.

Step 4: Update Application Code

Replace every hardcoded prompt string with a call to langwatch.prompts.get().

Python (BAD → GOOD):

agent = Agent(instructions="You are a helpful assistant.")

import langwatch
prompt = langwatch.prompts.get("my-agent")
agent = Agent(instructions=prompt.compile().messages[0]["content"])

TypeScript (BAD → GOOD):

const systemPrompt = "You are a helpful assistant.";

const langwatch = new LangWatch();
const prompt = await langwatch.prompts.get("my-agent");

CRITICAL: Do NOT wrap langwatch.prompts.get() in a try/catch with a hardcoded fallback string. The whole point of prompt versioning is that prompts are managed externally. A fallback defeats this by silently reverting to a stale hardcoded copy.

Step 5: Sync to the Platform

langwatch prompt sync

Step 6: Tag Versions for Deployment

Three built-in tags: latest (auto-assigned), production, staging. Update code to fetch by tag:

prompt = langwatch.prompts.get("my-agent", tag="production")

const prompt = await langwatch.prompts.get("my-agent", { tag: "production" });

Assign tags via the CLI (or the Deploy dialog in the LangWatch UI):

langwatch prompt tag assign my-agent production

For canary or blue/green deployments, create custom tags with langwatch prompt tag create.

Step 7: Verify

Run langwatch prompt list to confirm everything synced, or open the Prompts section in the LangWatch app.

Common Mistakes

• Do NOT hardcode prompts — always fetch via langwatch.prompts.get()
• Do NOT add a hardcoded fallback string in a try/catch — that silently defeats versioning
• Do NOT manually edit prompts.json — use the CLI
• Do NOT skip langwatch prompt sync after creating prompts