How to beginner · 3 min read

How to version prompts with LangSmith

Q: How to version prompts with LangSmith

Use the langsmith Python SDK to create and manage prompt versions by saving prompt templates as tracked artifacts. Each version is stored with metadata, enabling easy retrieval and comparison. This approach ensures reproducibility and organized prompt evolution in your AI workflows.

Quick answer

Use the langsmith Python SDK to create and manage prompt versions by saving prompt templates as tracked artifacts. Each version is stored with metadata, enabling easy retrieval and comparison. This approach ensures reproducibility and organized prompt evolution in your AI workflows.

PREREQUISITES

Python 3.8+
LangSmith API key
pip install langsmith

Setup

Install the langsmith Python package and set your API key as an environment variable to authenticate your requests.

bash

pip install langsmith

Step by step

This example demonstrates how to create a prompt version in LangSmith by saving a prompt template as an artifact. You can update the prompt content and create new versions to track changes over time.

python

import os
from langsmith import Client, PromptTemplate

# Initialize LangSmith client with API key from environment
client = Client(api_key=os.environ["LANGSMITH_API_KEY"])

# Define your prompt template content
prompt_content_v1 = "Translate the following English text to French: {text}"

# Create a prompt template artifact (version 1)
prompt_v1 = PromptTemplate(name="English to French Translator", template=prompt_content_v1)

# Save the prompt template to LangSmith (creates version 1)
prompt_v1 = client.create_prompt_template(prompt_v1)
print(f"Created prompt version 1 with ID: {prompt_v1.id}")

# Update prompt content for version 2
prompt_content_v2 = "Translate the following English text to French accurately and naturally: {text}"

# Create a new prompt template object with updated content
prompt_v2 = PromptTemplate(name="English to French Translator", template=prompt_content_v2)

# Save the new version (LangSmith tracks versions by name)
prompt_v2 = client.create_prompt_template(prompt_v2)
print(f"Created prompt version 2 with ID: {prompt_v2.id}")

# Retrieve all versions by name
versions = client.list_prompt_templates(name="English to French Translator")
print(f"Total versions: {len(versions)}")
for v in versions:
    print(f"Version ID: {v.id}, Template: {v.template}")

output

Created prompt version 1 with ID: prompt_abc123
Created prompt version 2 with ID: prompt_def456
Total versions: 2
Version ID: prompt_abc123, Template: Translate the following English text to French: {text}
Version ID: prompt_def456, Template: Translate the following English text to French accurately and naturally: {text}

Common variations

Use client.get_prompt_template(id) to fetch a specific prompt version by its ID.
Integrate prompt versioning with LangChain by exporting prompt templates from LangSmith.
Use asynchronous calls with LangSmith client if your application requires concurrency.

Troubleshooting

If you see authentication errors, verify your LANGSMITH_API_KEY environment variable is set correctly.
If prompt versions do not appear, ensure you use consistent name fields when creating prompt templates.
Check network connectivity if API calls time out or fail.

✅

Key Takeaways

Use PromptTemplate objects with consistent names to version prompts in LangSmith.
Save each prompt iteration via client.create_prompt_template() to track versions automatically.
Retrieve and compare prompt versions using client.list_prompt_templates(name=...).
Set LANGSMITH_API_KEY in your environment to authenticate API calls.
Versioning prompts improves reproducibility and collaboration in AI projects.

Verified 2026-04

Verify ↗