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.

ChatPromptBuilder renders a chat prompt from a template. It constructs prompts using static or dynamic templates, which you can update for each pipeline run. The template is a list of ChatMessage objects provided in the ChatMessage format or as Jinja2 strings.

Template variables in the template are optional unless specified otherwise. If an optional variable isn't provided, it defaults to an empty string. Use variable and required_variables to define input types and required variables.

Key Features

• Renders chat prompts from Jinja2 templates in ChatMessage format.
• Supports both static and dynamic templates, which you can update per pipeline run.
• Supports images in prompts using the templatize_part filter.
• Compatible with all ChatGenerator components.
• Can receive ranked documents from a Ranker and include them in the prompt.

Configuration

1. Drag the ChatPromptBuilder component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the General tab:
   1. Enter the prompt template in ChatMessage format. The template must include at least one message with a _role (system, user, assistant, or tool) and _content. You can use Jinja2 variables in the content.
   2. Optionally, configure required_variables to specify which variables must be present at runtime.
4. Go to the Advanced tab to configure variables if you want to define additional input variable names beyond those inferred from the template.

ChatMessage format

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 %}

Connections

ChatPromptBuilder receives pipeline variables (such as query and documents) through its dynamic **kwargs input. It outputs a rendered list of ChatMessage objects through its prompt output, which you connect to a ChatGenerator's messages input. You can also connect a Ranker's documents output to ChatPromptBuilder to include retrieved documents in the prompt.

Source Code

To check this component's source code, open chat_prompt_builder.py in the Haystack repository.

Usage Examples

Basic Configuration

  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

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	Description
template	Optional[List[ChatMessage]]	An optional list of ChatMessage objects to send to the LLM.
template_variables	Optional[Dict[str, Any]]	An optional dictionary of variables to include in the template.
kwargs	Any	Pipeline variables used for rendering the prompt.

Outputs

Parameter	Type	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.