Manage prompts programmatically

You can use the LangSmith Python and TypeScript SDK to manage prompts programmatically.

Previously this functionality lived in the langchainhub package which is now deprecated. All functionality going forward will live in the langsmith package.

Install packages

In Python, you can directly use the LangSmith SDK (recommended, full functionality) or you can use through the LangChain package (limited to pushing and pulling prompts). In TypeScript, you must use the LangChain npm package for pulling prompts (it also allows pushing). For all other functionality, use the LangSmith package.

pip install -U langsmith # version >= 0.1.99

uv add langsmith  # version >= 0.1.99

yarn add langsmith langchain // langsmith version >= 0.1.99 and langchain version >= 0.2.14

Configure environment variables

If you already have LANGSMITH_API_KEY set to your current workspace’s api key from LangSmith, you can skip this step. Otherwise, get an API key for your workspace by navigating to Settings > API Keys > Create API Key in LangSmith. Set your environment variable.

export LANGSMITH_API_KEY="lsv2_..."

What we refer to as “prompts” used to be called “repos”, so any references to “repo” in the code are referring to a prompt.

Push a prompt

To create a new prompt or update an existing prompt, you can use the push prompt method.

from langsmith import Client
from langchain_core.prompts import ChatPromptTemplate

client = Client()
prompt = ChatPromptTemplate.from_template("tell me a joke about {topic}")
url = client.push_prompt("joke-generator", object=prompt)
# url is a link to the prompt in the UI
print(url)

from langchain_classic import hub as prompts
from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_template("tell me a joke about {topic}")
url = prompts.push("joke-generator", prompt)
# url is a link to the prompt in the UI
print(url)

import * as hub from "langchain/hub";
import { ChatPromptTemplate } from "@langchain/core/prompts";

const prompt = ChatPromptTemplate.fromTemplate("tell me a joke about {topic}");
const url = hub.push("joke-generator", {
  object: prompt,
});
// url is a link to the prompt in the UI
console.log(url);

You can also push a prompt as a RunnableSequence of a prompt and a model. This is useful for storing the model configuration you want to use with this prompt. The provider must be supported by the LangSmith playground. (see settings here: Supported Providers)

from langsmith import Client
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI

client = Client()
model = ChatOpenAI(model="gpt-4o-mini")
prompt = ChatPromptTemplate.from_template("tell me a joke about {topic}")
chain = prompt | model
client.push_prompt("joke-generator-with-model", object=chain)

from langchain_classic import hub as prompts
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI

model = ChatOpenAI(model="gpt-4o-mini")
prompt = ChatPromptTemplate.from_template("tell me a joke about {topic}")
chain = prompt | model
url = prompts.push("joke-generator-with-model", chain)
# url is a link to the prompt in the UI
print(url)

import * as hub from "langchain/hub";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { ChatOpenAI } from "@langchain/openai";

const model = new ChatOpenAI({ model: "gpt-4o-mini" });
const prompt = ChatPromptTemplate.fromTemplate("tell me a joke about {topic}");
const chain = prompt.pipe(model);
await hub.push("joke-generator-with-model", {
  object: chain,
});

Pull a prompt

To pull a prompt, you can use the pull prompt method, which returns a the prompt as a langchain PromptTemplate. To pull a private prompt you do not need to specify the owner handle (though you can, if you have one set). To pull a public prompt from the LangChain Hub, you need to specify the handle of the prompt’s author.

from langsmith import Client
from langchain_openai import ChatOpenAI

client = Client()
prompt = client.pull_prompt("joke-generator")
model = ChatOpenAI(model="gpt-4o-mini")
chain = prompt | model
chain.invoke({"topic": "cats"})

from langchain_classic import hub as prompts
from langchain_openai import ChatOpenAI

prompt = prompts.pull("joke-generator")
model = ChatOpenAI(model="gpt-4o-mini")
chain = prompt | model
chain.invoke({"topic": "cats"})

import * as hub from "langchain/hub";
import { ChatOpenAI } from "@langchain/openai";

const prompt = await hub.pull("joke-generator");
const model = new ChatOpenAI({ model: "gpt-4o-mini" });
const chain = prompt.pipe(model);
await chain.invoke({"topic": "cats"});

Similar to pushing a prompt, you can also pull a prompt as a RunnableSequence of a prompt and a model. Just specify include_model when pulling the prompt. If the stored prompt includes a model, it will be returned as a RunnableSequence. Make sure you have the proper environment variables set for the model you are using.

from langsmith import Client

client = Client()
chain = client.pull_prompt("joke-generator-with-model", include_model=True)
chain.invoke({"topic": "cats"})

from langchain_classic import hub as prompts

chain = prompts.pull("joke-generator-with-model", include_model=True)
chain.invoke({"topic": "cats"})

import * as hub from "langchain/hub";
import { Runnable } from "@langchain/core/runnables";

const chain = await hub.pull<Runnable>("joke-generator-with-model", { includeModel: true });
await chain.invoke({"topic": "cats"});

When pulling a prompt, you can also specify a specific commit hash or commit tag to pull a specific version of the prompt.

prompt = client.pull_prompt("joke-generator:12344e88")

prompt = prompts.pull("joke-generator:12344e88")

const prompt = await hub.pull("joke-generator:12344e88")

To pull a public prompt from the LangChain Hub, you need to specify the handle of the prompt’s author.

prompt = client.pull_prompt("efriis/my-first-prompt")

prompt = prompts.pull("efriis/my-first-prompt")

const prompt = await hub.pull("efriis/my-first-prompt")

For pulling prompts, if you are using Node.js or an environment that supports dynamic imports, we recommend using the langchain/hub/node entrypoint, as it handles deserialization of models associated with your prompt configuration automatically.If you are in a non-Node environment, “includeModel” is not supported for non-OpenAI models and you should use the base langchain/hub entrypoint.

Prompt caching

We recommend enabling prompt caching in production environments to reduce latency and API calls. The cache uses a stale-while-revalidate pattern, ensuring your application always gets a fast response while keeping prompts up-to-date in the background.

The LangSmith SDK includes built-in in-memory caching for prompts. When enabled, pulled prompts are cached in memory, reducing latency and API calls for frequently used prompts. The cache persists for the lifetime of the client instance. Requirements:

Python SDK: langsmith >= 0.6.1
TypeScript SDK: langsmith >= 0.4.5

Default behavior

Caching is disabled by default. When enabled, the default settings are:

Setting	Default	Description
`max_size`	100	Maximum number of prompts to cache
`ttl_seconds`	3600 (1 hour)	Time before a cached prompt is considered stale
`refresh_interval_seconds`	60	How often to check for stale prompts

Enabling the cache

Pass cache=True to enable caching with default settings, or pass a Cache instance for custom configuration:

from langsmith import Client, Cache

# Enable with default settings
client = Client(cache=True)

# Or configure custom cache settings
my_cache = Cache(
    max_size=100,
    ttl_seconds=3600,
)
client = Client(cache=my_cache)

# First pull - fetches from API and caches
prompt = client.pull_prompt("joke-generator")

# Subsequent pulls - returns cached version instantly
prompt = client.pull_prompt("joke-generator")

# Check cache metrics
print(f"Cache hits: {client.cache.metrics.hits}")
print(f"Cache misses: {client.cache.metrics.misses}")
print(f"Hit rate: {client.cache.metrics.hit_rate:.1%}")

import { Client, Cache } from "langsmith";

// Enable with default settings
const client = new Client({ cache: true });

// Or configure custom cache settings
const myCache = new Cache({
  maxSize: 100,
  ttlSeconds: 3600,
});
const client2 = new Client({ cache: myCache });

// First pull - fetches from API and caches
const prompt = await client.pullPrompt("joke-generator");

// Subsequent pulls - returns cached version instantly
const prompt2 = await client.pullPrompt("joke-generator");

// Check cache metrics
console.log(`Cache hits: ${client.cache?.metrics.hits}`);
console.log(`Cache misses: ${client.cache?.metrics.misses}`);
console.log(`Hit rate: ${(client.cache?.hitRate ?? 0 * 100).toFixed(1)}%`);

Skipping the cache

To bypass the cache and fetch a fresh prompt from the API, use the skip_cache parameter:

# Force a fresh fetch, ignoring any cached version
prompt = client.pull_prompt("joke-generator", skip_cache=True)

// Force a fresh fetch, ignoring any cached version
const prompt = await client.pullPrompt("joke-generator", { skipCache: true });

This is useful when you need to ensure you have the latest version of a prompt, such as after making changes in the LangSmith UI.

Offline mode

For environments with limited or no network connectivity, you can pre-populate the cache and use it offline. Set ttl_seconds to None (Python) or null (TypeScript) to prevent cache entries from expiring. Step 1: Export your prompts to a cache file (while online)

from langsmith import Client, Cache

# Create client with caching enabled
client = Client(cache=True)

# Pull the prompts you need
client.pull_prompt("prompt-1")
client.pull_prompt("prompt-2")
client.pull_prompt("prompt-3")

# Export cache to a file
client.cache.dump("prompts_cache.json")
client.cleanup()

import { Client } from "langsmith";

// Create client with caching enabled
const client = new Client({ cache: true });

// Pull the prompts you need
await client.pullPrompt("prompt-1");
await client.pullPrompt("prompt-2");
await client.pullPrompt("prompt-3");

// Export cache to a file
client.cache?.dump("prompts_cache.json");
client.cleanup();

Step 2: Load the cache file in your offline environment

from langsmith import Client, Cache

# Create cache with infinite TTL (never expire)
my_cache = Cache(ttl_seconds=None)
my_cache.load("prompts_cache.json")

client = Client(cache=my_cache)

# Uses cached version without any API calls
prompt = client.pull_prompt("prompt-1")

import { Client, Cache } from "langsmith";

// Create cache with infinite TTL (never expire)
const myCache = new Cache({ ttlSeconds: null });
myCache.load("prompts_cache.json");

const client = new Client({ cache: myCache });

// Uses cached version without any API calls
const prompt = await client.pullPrompt("prompt-1");

Cleanup

When you’re done using the client, call cleanup() to stop the background refresh task:

client.cleanup()

client.cleanup();

Use a prompt without LangChain

If you want to store your prompts in LangSmith but use them directly with a model provider’s API, you can use our conversion methods. These convert your prompt into the payload required for the OpenAI or Anthropic API. These conversion methods rely on logic from within LangChain integration packages, and you will need to install the appropriate package as a dependency in addition to your official SDK of choice. Here are some examples:

OpenAI

pip install -U langchain_openai

yarn add @langchain/openai @langchain/core // @langchain/openai version >= 0.3.2

from openai import OpenAI
from langsmith.client import Client, convert_prompt_to_openai_format

# langsmith client
client = Client()
# openai client
oai_client = OpenAI()

# pull prompt and invoke to populate the variables
prompt = client.pull_prompt("joke-generator")
prompt_value = prompt.invoke({"topic": "cats"})
openai_payload = convert_prompt_to_openai_format(prompt_value)
openai_response = oai_client.chat.completions.create(**openai_payload)

import * as hub from "langchain/hub";
import { convertPromptToOpenAI } from "@langchain/openai";
import OpenAI from "openai";

const prompt = await hub.pull("jacob/joke-generator");
const formattedPrompt = await prompt.invoke({
  topic: "cats",
});
const { messages } = convertPromptToOpenAI(formattedPrompt);

const openAIClient = new OpenAI();
const openAIResponse = await openAIClient.chat.completions.create({
  model: "gpt-4o-mini",
  messages,
});

Anthropic

pip install -U langchain_anthropic

yarn add @langchain/anthropic @langchain/core // @langchain/anthropic version >= 0.3.3

from anthropic import Anthropic
from langsmith.client import Client, convert_prompt_to_anthropic_format

# langsmith client
client = Client()
# anthropic client
anthropic_client = Anthropic()

# pull prompt and invoke to populate the variables
prompt = client.pull_prompt("joke-generator")
prompt_value = prompt.invoke({"topic": "cats"})
anthropic_payload = convert_prompt_to_anthropic_format(prompt_value)
anthropic_response = anthropic_client.messages.create(**anthropic_payload)

import * as hub from "langchain/hub";
import { convertPromptToAnthropic } from "@langchain/anthropic";
import Anthropic from "@anthropic-ai/sdk";

const prompt = await hub.pull("jacob/joke-generator");
const formattedPrompt = await prompt.invoke({
  topic: "cats",
});
const { messages, system } = convertPromptToAnthropic(formattedPrompt);

const anthropicClient = new Anthropic();
const anthropicResponse = await anthropicClient.messages.create({
  model: "claude-haiku-4-5-20251001",
  system,
  messages,
  max_tokens: 1024,
  stream: false,
});

List, delete, and like prompts

You can also list, delete, and like/unlike prompts using the list prompts, delete prompt, like prompt and unlike prompt methods. See the LangSmith SDK client for extensive documentation on these methods.

# List all prompts in my workspace
prompts = client.list_prompts()

# List my private prompts that include "joke"
prompts = client.list_prompts(query="joke", is_public=False)

# Delete a prompt
client.delete_prompt("joke-generator")

# Like a prompt
client.like_prompt("efriis/my-first-prompt")

# Unlike a prompt
client.unlike_prompt("efriis/my-first-prompt")

// List all prompts in my workspace
import Client from "langsmith";

const client = new Client({ apiKey: "lsv2_..." });
const prompts = client.listPrompts();

for await (const prompt of prompts) {
  console.log(prompt);
}

// List my private prompts that include "joke"
const private_joke_prompts = client.listPrompts({ query: "joke", isPublic: false});

// Delete a prompt
client.deletePrompt("joke-generator");

// Like a prompt
client.likePrompt("efriis/my-first-prompt");

// Unlike a prompt
client.unlikePrompt("efriis/my-first-prompt");

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Create and update prompts

Tutorials

Manage prompts programmatically

Install packages

Configure environment variables

Push a prompt

Pull a prompt

Prompt caching

Default behavior

Enabling the cache

Skipping the cache

Offline mode

Cleanup

Use a prompt without LangChain

OpenAI

Anthropic

List, delete, and like prompts

​Install packages

​Configure environment variables

​Push a prompt

​Pull a prompt

​Prompt caching

​Default behavior

​Enabling the cache

​Skipping the cache

​Offline mode

​Cleanup

​Use a prompt without LangChain

​OpenAI

​Anthropic

​List, delete, and like prompts

Install packages

Configure environment variables

Push a prompt

Pull a prompt

Prompt caching

Default behavior

Enabling the cache

Skipping the cache

Offline mode

Cleanup

Use a prompt without LangChain

OpenAI

Anthropic

List, delete, and like prompts