feat: Extend ChatPromptBuilder with insert tag

[sjrl]

Related Issues

• Part of resolving this idea refactor!: Remove user_prompt and system_prompt from Agent and LLM run methods #11209 (comment)
• Part of https://github.com/deepset-ai/haystack-private/issues/331

Proposed Changes:

Add a new messages tag in our ChatPromptBuilder ({% messages %}) to support building prompts like

{% message role="system" %}You are a helpful assistant.{% endmessage %}
{% messages %}
{% message role="user" %}{{ query }}{% endmessage %}

so users can interleave a list of chat messages into their prompt.

I also added support for subscripting (e.g. {% messages[0] %}, {% messages[-1:] %}) to allow users to select which of the incoming messages they would like to include or not.

How did you test it?

Added new unit tests.

Notes for the reviewer

The immediate use case for this would be to use this new format for Agent. So get rid of system_prompt and user_prompt from Agent's init method and replace it with a singular messages_template (or prompt_template) variable. The default prompt_template would be {% messages %} which translates to the Agent expecting the messages variable to be provided at runtime. Then if users want to customize and add new additional messages like a system message they can easily update the prompt_template to

{% message role="system" %}You are a helpful assistant.{% endmessage %}
{% messages %}

and any new jinja2 params added would then be expected runtime params.

Checklist

• I have read the contributors guidelines and the code of conduct.
• I have updated the related issue with new insights and changes.
• I have added unit tests and updated the docstrings.
• I've used one of the conventional commit types for my PR title: fix:, feat:, build:, chore:, ci:, docs:, style:, refactor:, perf:, test: and added ! in case the PR includes breaking changes.
• I have documented my code.
• I have added a release note file, following the contributors guidelines.
• I have run pre-commit hooks and fixed any issue.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
haystack-docs	Ignored	Preview	Jun 3, 2026 9:47am

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
haystack/utils
jinja2_chat_extension.py
Project Total

This report was generated by python-coverage-comment-action

[sjrl]

@anakin87 I'd appreciate your review on this when you're back since it modifies the Jinja2 extension you built.

[anakin87]

I left some minor comments. Looks good in general

I am just a little afraid of using {% messages %} (very similar to {% message %}). WDYT?
We might also decide to use something like {% insert messages %}

[sjrl]

I left some minor comments. Looks good in general

I am just a little afraid of using {% messages %} (very similar to {% message %}). WDYT? We might also decide to use something like {% insert messages %}

Done in e98c8cf

I agree that it's better it also allows for more customization by not requiring the param name to be messages

[anakin87]

Thank you!