PromptBuilder

Render a prompt filling in any variables and send it to a Generator.

Key Features

• Renders Jinja2 templates by filling in variables with values from the pipeline.
• Variables in the template become optional inputs unless marked as required.
• Supports required_variables to enforce that specific variables are provided.
• Allows runtime template override by passing a template string at query time.
• Works with string-based generators like OpenAIGenerator and AmazonBedrockGenerator.

Configuration

1. Drag the PromptBuilder component onto the canvas from the Component Library.
2. Click the component to open the configuration panel.
3. On the General tab:
   1. Enter the Jinja2 template string. Variables in the template (for example, {{ query }} and {{ documents }}) automatically become inputs for this component.
4. Go to the Advanced tab to configure required variables.

Connections

PromptBuilder receives documents from a Retriever or Ranker, and accepts any pipeline variables as inputs based on the template. It outputs a rendered prompt string. Connect its prompt output to a Generator like OpenAIGenerator. For chat-based generators, use ChatPromptBuilder instead.

Usage Example

This is a RAG pipeline that uses PromptBuilder with OpenAIGenerator:

components:
  bm25_retriever:
    type: haystack_integrations.components.retrievers.opensearch.bm25_retriever.OpenSearchBM25Retriever
    init_parameters:
      document_store:
        type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
        init_parameters:
          hosts:
            - ${OPENSEARCH_HOST}
          http_auth:
            - ${OPENSEARCH_USER}
            - ${OPENSEARCH_PASSWORD}
          use_ssl: true
          verify_certs: false
      top_k: 20

  query_embedder:
    type: haystack.components.embedders.sentence_transformers_text_embedder.SentenceTransformersTextEmbedder
    init_parameters:
      model: intfloat/e5-base-v2

  embedding_retriever:
    type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
    init_parameters:
      document_store:
        type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
        init_parameters:
          hosts:
            - ${OPENSEARCH_HOST}
          http_auth:
            - ${OPENSEARCH_USER}
            - ${OPENSEARCH_PASSWORD}
          use_ssl: true
          verify_certs: false
      top_k: 20

  document_joiner:
    type: haystack.components.joiners.document_joiner.DocumentJoiner
    init_parameters:
      join_mode: concatenate

  ranker:
    type: haystack.components.rankers.transformers_similarity.TransformersSimilarityRanker
    init_parameters:
      model: intfloat/simlm-msmarco-reranker
      top_k: 8

  prompt_builder:
    type: haystack.components.builders.prompt_builder.PromptBuilder
    init_parameters:
      template: |-
        You are a technical expert.
        You answer questions truthfully based on provided documents.
        Ignore typing errors in the question.
        For each document check whether it is related to the question.
        Only use documents that are related to the question to answer it.
        Ignore documents that are not related to the question.
        If the answer exists in several documents, summarize them.
        Only answer based on the documents provided. Don't make things up.
        Just output the structured, informative and precise answer and nothing else.
        If the documents can't answer the question, say so.
        Always use references in the form [NUMBER OF DOCUMENT] when using information from a document, e.g. [3] for Document[3].
        Never name the documents, only enter a number in square brackets as a reference.
        The reference must only refer to the number that comes in square brackets after the document.
        Otherwise, do not use brackets in your answer and reference ONLY the number of the document without mentioning the word document.

        These are the documents:
        {% for document in documents %}
        Document[{{ loop.index }}]:
        {{ document.content }}
        {% endfor %}

        Question: {{ question }}
        Answer:

  llm:
    type: haystack.components.generators.openai.OpenAIGenerator
    init_parameters:
      api_key: {"type": "env_var", "env_vars": ["OPENAI_API_KEY"], "strict": False}
      model: "gpt-4o"
      generation_kwargs:
        max_tokens: 400
        temperature: 0.0
        seed: 0

  answer_builder:
    type: haystack.components.builders.answer_builder.AnswerBuilder
    init_parameters: {}

connections:
  - sender: bm25_retriever.documents
    receiver: document_joiner.documents
  - sender: query_embedder.embedding
    receiver: embedding_retriever.query_embedding
  - sender: embedding_retriever.documents
    receiver: document_joiner.documents
  - sender: document_joiner.documents
    receiver: ranker.documents
  - sender: ranker.documents
    receiver: prompt_builder.documents
  - sender: ranker.documents
    receiver: answer_builder.documents
  - sender: prompt_builder.prompt
    receiver: answer_builder.prompt
  - sender: prompt_builder.prompt
    receiver: llm.prompt
  - sender: llm.replies
    receiver: answer_builder.replies

max_runs_per_component: 100

inputs:
  query:
    - bm25_retriever.query
    - query_embedder.text
    - ranker.query
    - prompt_builder.question
    - answer_builder.query
  filters:
    - bm25_retriever.filters
    - embedding_retriever.filters

outputs:
  documents: ranker.documents
  answers: answer_builder.answers

metadata: {}

Parameters

Inputs

Parameter	Type	Default	Description
template	Optional[str]	None	An optional string template to overwrite PromptBuilder's default template.
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.

Outputs

Parameter	Type	Default	Description
prompt	str		The updated prompt text after rendering the prompt template.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
template	str		A prompt template that uses Jinja2 syntax to add variables. For example: "Summarize this document: {{ documents[0].content }}\nSummary:". Variables in the default template are inputs for PromptBuilder and are all optional, unless explicitly specified. If an optional variable is not provided, it's replaced with an empty string in the rendered prompt.
required_variables	Optional[Union[List[str], Literal['*']]]	None	List variables that must be provided as input to PromptBuilder. If a variable listed as required is not provided, an exception is raised. If set to "*", all variables found in the prompt are required.
variables	Optional[List[str]]	None	List 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[str]	None	An optional string template to overwrite PromptBuilder'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.