Prompts

Purpose and Scope

Prompts are the part of a LangChain application where natural-language instructions, examples, context, and dynamic user inputs are assembled before a language model call. In LangChain Core, prompt objects are not just string helpers: the base prompt type is a serializable runnable that accepts a dictionary of inputs and returns a PromptValue, which can be either a string-oriented value or a chat-oriented value. That design lets prompts participate in the same invocation, tracing, configuration, and composition workflows as other runnables while keeping model-facing formatting logic explicit and reusable.

Sources: libs/core/langchain_core/prompts/base.py, libs/core/langchain_core/prompts/prompt.py

The official LangChain and LangSmith docs distinguish between prompts, which are the concrete messages or text sent to a model, and prompt templates, which are reusable structures with placeholders. The source code reflects that distinction. PromptTemplate represents completion-style string prompts, while ChatPromptTemplate and related message prompt classes represent modern chat prompts as ordered messages with roles such as system, human, and AI. New applications should generally prefer chat prompts because they preserve conversational structure and map more directly to current model provider APIs.

Sources: libs/core/langchain_core/prompts/chat.py, libs/core/langchain_core/prompts/prompt.py

Relevant Source Files

• libs/core/langchain_core/prompts/base.py - Defines BasePromptTemplate, the shared runnable base for prompt templates, including input variables, optional variables, partial variables, output parsers, metadata, tags, validation rules, and serialization-related behavior.
• libs/core/langchain_core/prompts/chat.py - Defines chat prompt behavior, including message placeholders, message conversion, chat prompt values, role-oriented messages, and support for message-like representations used by agents and chat models.
• libs/core/langchain_core/prompts/prompt.py - Defines PromptTemplate, the completion-style string prompt template with f-string, mustache, and jinja2 formatting support plus template-variable inference and validation.
• libs/core/langchain_core/prompts/few_shot.py - Defines few-shot prompt templates and the shared mixin that enforces the choice between static examples and a dynamic example selector.
• libs/core/langchain_core/prompts/structured.py - Defines beta StructuredPrompt, a chat prompt variant that carries an output schema and composes with models capable of structured output.

Core Concepts

BasePromptTemplate is the common contract behind the prompt family. It declares required input_variables, inferred or declared optional_variables, optional input_types, an optional output_parser, partial_variables, and tracing-oriented metadata and tags. It also validates that reserved names are not used as prompt inputs: stop is rejected because it is used internally, and a variable cannot appear in both input_variables and partial_variables. These checks matter because prompt templates are usually reused across chains, agents, tests, and production traces, where ambiguous variable names can become difficult to diagnose.

Sources: libs/core/langchain_core/prompts/base.py

PromptTemplate is the direct string-template implementation for completion-style prompting. It stores a template, a template_format, and a validate_template flag. The supported formats are f-string, mustache, and jinja2, with f-string as the default. During model validation, the class infers input_variables from the template and excludes variables already supplied through partial_variables. If validation is requested, it checks consistency between the template and declared inputs, while mustache validation is explicitly disallowed. The implementation also carries a security warning for jinja2: sandboxing is best effort, so untrusted jinja2 templates should be avoided.

Sources: libs/core/langchain_core/prompts/prompt.py

Chat prompts are built around messages rather than a single string. chat.py imports concrete message classes such as SystemMessage, HumanMessage, AIMessage, ChatMessage, and BaseMessage, and returns ChatPromptValue instances after formatting. The important reader-facing primitive is MessagesPlaceholder, which represents a variable that is already a list of messages, commonly named something like history. A placeholder can be required or optional, and it can limit the number of retained messages with n_messages, making it useful for chat history windows and agent state handoff.

Sources: libs/core/langchain_core/prompts/chat.py

Few-shot prompting adds examples to the rendered prompt so the model can imitate a pattern. LangChain separates the example source from the formatting behavior. The shared few-shot mixin accepts either a static examples list or an example_selector, but not both and not neither. At formatting time, _get_examples returns the static examples or calls select_examples on the selector; the async version uses aselect_examples. This gives applications a stable prompt surface while allowing example selection to become dynamic, similarity-based, context-sensitive, or otherwise dependent on invocation inputs.

Sources: libs/core/langchain_core/prompts/few_shot.py

StructuredPrompt extends chat prompting for cases where the model should produce data conforming to a schema. It is marked beta and requires a non-empty schema_, which may be a dictionary or a Pydantic model type. Extra constructor keyword arguments that are not fields on the prompt are collected into structured_output_kwargs, allowing prompt authors to pass model-structured-output options alongside the messages and schema. This class is useful when the prompt and the expected shape of the answer should travel together through the runnable pipeline.

Sources: libs/core/langchain_core/prompts/structured.py

System-to-Code Mapping

Authoring Flow

A practical prompt authoring flow starts with deciding whether the model call should be chat-style or completion-style. For new work, use a chat prompt when possible: put persistent behavior in a system message, user-specific input in a human message, and prior interaction state in MessagesPlaceholder. If the model or integration expects a plain text prompt, use PromptTemplate and keep the template format conservative. The code supports jinja2 and mustache, but the safer default is f-string formatting, especially when templates might come from configuration, user input, or a shared prompt registry.

Sources: libs/core/langchain_core/prompts/chat.py, libs/core/langchain_core/prompts/prompt.py

After choosing the prompt type, define the variable contract. Required variables belong in input_variables, optional message placeholders may be inferred as optional_variables, and stable values belong in partial_variables. Avoid using stop as a variable name, because BasePromptTemplate rejects it for both required and partial variables. Also avoid duplicating a name across required and partial inputs. These constraints make prompt invocation predictable: each runtime call supplies only the values that truly vary, while the prompt object itself carries reusable defaults, tracing metadata, tags, and any output parser.

Sources: libs/core/langchain_core/prompts/base.py

For prompts that need examples, decide whether the examples should be fixed or selected at runtime. Static examples are easy to review and version, which makes them useful for deterministic tests or product-approved wording. An example_selector is better when the best examples depend on the input, such as choosing demonstrations that match a domain, intent, or similarity search result. LangChain enforces this choice at construction time so a prompt does not accidentally mix two competing example sources. Async selection is also part of the contract, which matters when examples come from a remote store or vector index.

Sources: libs/core/langchain_core/prompts/few_shot.py

When the expected answer shape is part of the application contract, use a structured prompt or pair a normal prompt with a structured-output-capable model. StructuredPrompt keeps the messages, schema, and structured-output options together, and its constructor fails fast if no schema is provided. This is different from merely asking the model to “return JSON” in text: the schema becomes part of the object-level configuration that can be composed with a BaseLanguageModel and other runnables. Treat this as a schema-first prompt authoring pattern for extraction, routing, classification, and typed tool-like responses.

Sources: libs/core/langchain_core/prompts/structured.py

Compact API Reference

from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
 
prompt = ChatPromptTemplate.from_messages(
    [
        ("system", "You are a careful assistant."),
        MessagesPlaceholder("history", optional=True),
        ("human", "Answer this question: {question}"),
    ]
)
 
value = prompt.invoke({"question": "What should I test first?"})

This pattern keeps instructions, chat history, and user input separate. The placeholder can later receive real conversation history without changing the template, and the invocation remains a normal runnable call that can be composed with a chat model. For a completion model, the equivalent starting point is PromptTemplate.from_template("Answer this question: {question}"); for typed responses, start with StructuredPrompt and a Pydantic schema. The next page to read depends on where the prompt goes: language model pages explain invocation and streaming, while structured output pages explain parsing and model-native schemas.

Sources: libs/core/langchain_core/prompts/chat.py, libs/core/langchain_core/prompts/prompt.py, libs/core/langchain_core/prompts/structured.py