ChatPromptBuilder

Use ChatPromptBuilder to send a prompt to a ChatGenerator. It renders chat prompts from static or dynamic templates using the ChatMessage format or Jinja2 strings.

Key Features

• Renders chat prompts from a list of ChatMessage objects or Jinja2 template strings.
• Supports dynamic templates that can be updated at each pipeline run.
• Accepts template variables from the pipeline, making prompts flexible and reusable.
• Supports images in prompts through the templatize_part filter.
• Allows defining required variables to enforce that certain inputs are always provided.

Configuration

1. Drag the ChatPromptBuilder component onto the canvas from the Component Library.
2. Click the component to open the configuration panel.
3. Configure the parameters as needed.

Connections

ChatPromptBuilder accepts an optional template (a list of ChatMessage objects), optional template_variables, and pipeline variables (kwargs). It outputs a prompt as a list of ChatMessage objects.

Connect a Ranker or document retriever to provide documents as a template variable. Connect the prompt output to a ChatGenerator such as OpenAIChatGenerator or AnthropicChatGenerator.

Usage Example

Initializing the Component

components:
  ChatPromptBuilder:
    type: components.builders.chat_prompt_builder.ChatPromptBuilder
    init_parameters:
      template:
      - _content:
        - text: |
            You are a helpful assistant answering the user's questions.
            If the answer is not in the documents, rely on the web_search tool to find information.
            Do not use your own knowledge.
        _role: system

Using the Component in a Pipeline

Using the ChatMessage Format

ChatPromptBuilder sends the instructions to a ChatGenerator in the form of a list of ChatMessage objects. You pass the instructions in the template parameter, which must follow the ChatMessage format:

- content: 
    - content_type:  # replace this with the content type, supported content types are: text, tool_call, tool_call_result
      # content may contain variables
  role: role # supported roles are: user, system, assistant, tool`

For example:

- _content:
    - text: |
        You are a helpful assistant answering the user's questions.
        If the answer is not in the documents, rely on the web_search tool to find information.
        Do not use your own knowledge.
  _role: system
- _content:
    - text: |
        Question: {{ query }}
  _role: user

You can also pass documents in the prompt, like this:

- _content:
    - text: |
        Here are the results that your last search yielded.
        {% for doc in documents %}
        {{doc.content}}
        {% endfor %}
        
        Question: {{ query }}
  _role: user

ChatPromptBuilder also supports passing images in prompts using the templatize_part filter:

- _content:
    - text: |
     What's the difference between the following images?
     {% for image in images %}
     {{ image | templatize_part }}
     {% endfor %}
     {% endmessage %}
  _role: user

Using the Jinja2 Template Syntax

You can use Jinja2 strings in ChatPromptBuilder's template parameter through the {% message %} tag. This makes it possible to create structured ChatMessages with mixed content types, such as images and text. For example, this ChatPromptBuilder contains instructions for follow up question classification and rewriting queries at the start of the pipeline. There are two chat messages, one with role "system" and another one with role "assistant". It also includes chat history.

components:
  ChatPromptBuilder:
    type: haystack.components.builders.chat_prompt_builder.ChatPromptBuilder
    init_parameters:
      template: |
        {% message role="system" %}
        You are an excellent labeling tool.
        You receive a chat history.
        If the last user question is asking for information from a database, output "QUESTION".
        This is also the case when something needs to be explained.

        If the last user question contains instructions for working with a given passage, output "PASSAGE".
        If the chat history is empty, the label "PASSAGE" cannot be used.

        Example questions referring to the passage are:
        "write a summary of this", "in bullet points", or "rephrase as an email".

        For the "QUESTION" label, you additionally output a "query".
        The "query" must be in natural language, since it will be processed by a hybrid of keyword and semantic search. Therefore, be as explicit as possible with the keywords.
        If both X and Y are asked about, only include Y in the "query" and do not repeat X.
        Abbreviations such as "ArbVG", "BVwG", or "Abs", as well as all paragraphs, must remain unchanged and must not be reformulated in the "query".
        If the question does not need context from the chat history, output it unchanged in the "query".

        For the "PASSAGE" label, you output NOTHING additional.
        Simply: "PASSAGE".
        {% endmessage %}

        {% for message in chat_history %}
        {% message role=message.role %}
        {{ message.text }}
        {% endmessage %}
        {% endfor %}

        {% message role="assistant" %}
        {% endmessage %}

ChatMessage

ChatMessage is a data class that represents a message in a chat. It contains the following fields:

• role: The role of the message. Available roles are system, user, tool,and assistant.
• content: The content of the message.
• metadata: The metadata of the message.

In the template parameter, you can pass a list of ChatMessage objects in the following format:

- _content:
    - content_type: | #replace this with the content type, supported types are text, image, tool_call, and tool_call_result
        Type the prompt here, it may contain Jinja2 variables.
  _role: role # supported roles are system, user, tool, and assistant
  _metadata:
    - key: value # optional metadata

For example:

- _content:
    - text: |
        You are a helpful assistant answering the user's questions.
        If the answer is not in the documents, rely on the web_search tool to find information.
        Do not use your own knowledge.
  _role: system
- _content:
    - text: |
        Question: {{ query }}
  _role: user

You can also pass the same content as a Jinja2 string using the {% message %} tag:

ChaMessages in Prompt Explorer

Prompt Explorer only supports prompts with the {% message %} tag. Use the ChatMessage string format if you want to test your prompt in Prompt Explorer.

{% message role="system" %}
You are a helpful assistant answering the user's questions.
If the answer is not in the documents, rely on the web_search tool to find information.
Do not use your own knowledge.
{% endmessage %}

{% message role="user" %}
Question: {{ query }}
{% endmessage %}

Parameters

Inputs

Parameter	Type	Default	Description
template	Optional[List[ChatMessage]]	None	An optional list of ChatMessage objects to send to the LLM.
template_variables	Optional[Dict[str, Any]]	None	An optional dictionary of variables to include in the template.
kwargs	Any		Pipeline variables used for rendering the prompt.

Outputs

Parameter	Type	Default	Description
prompt	List[ChatMessage]		The updated list of ChatMessage objects after rendering the templates.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
template	Optional[List[ChatMessage]]	None	A list of ChatMessage objects. The component looks for Jinja2 template syntax and renders the prompt with the provided variables.
required_variables	Optional[Union[List[str], Literal['*']]]	None	A list of variables that ChatPromptBuilder must receive as input. If a variable listed as required is not provided, an exception is raised. If set to "*", all variables in the prompt are required.
variables	Optional[List[str]]	None	A list of input variables to use in prompt templates instead of the ones inferred from the template parameter. For example, to use more variables during prompt engineering than the ones present in the default template, you can provide them here.

Run Method Parameters

These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see Modify Pipeline Parameters at Query Time.

Parameter	Type	Default	Description
template	Optional[List[ChatMessage]]	None	An optional list of ChatMessage objects to overwrite ChatPromptBuilder's default template. If None, the default template provided at initialization is used.
template_variables	Optional[Dict[str, Any]]	None	An optional dictionary of template variables to overwrite the pipeline variables.
kwargs	Any		Pipeline variables used for rendering the prompt.