refactor!: Remove user_prompt and system_prompt from Agent.run

[sjrl]

Related Issues

• WIP just experimenting

Proposed Changes:

Remove the user_prompt and system_prompt from the Agent's run method to reduce the complexity of how the Agent can be called. With these changes it becomes more obvious that new runtime content should either be passed through into messages param or any of the kwargs that are exposed via prompt template variables from the system_prompt and user_prompt passed in at init time.

The original motivation for exposing the user and system prompts as runtime variables was to enable the Prompt Explorer in our cloud platform which needed these runtime params to easily update/explore different prompts. However, they will no longer be needed to enable that feature in the near future.

How did you test it?

Notes for the reviewer

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	Apr 28, 2026 10:38am

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
haystack/components/agents
agent.py
haystack/human_in_the_loop
strategies.py
Project Total

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

[anakin87]

Just dropping here a more radical (untested) idea

• allow only system_prompt in the __init__
• let users pass messages as list[ChatMessage] | str in run to allow Jinja 2 interpolation
• improve ChatPromptBuilder handling, which is messy right now

WDYT?

[sjrl]

Just dropping here a more radical (untested) idea

• allow only system_prompt in the __init__
• let users pass messages as list[ChatMessage] | str in run to allow Jinja 2 interpolation
• improve ChatPromptBuilder handling, which is messy right now

WDYT?

Interesting idea. Only thing I can think of as a potential problem is that if user prompt can only be at runtime then we would lose the ability to connect user prompt variables when building the pipeline.

Maybe rename user_prompt to user_prompt_template to help emphasize it's meant to be for templating and not be a normal user message?

[sjrl]

Or maybe more radical we throw away system and user prompt at init time and just a generic messages_template which would be a jinja2 template that would default to {{messages}} which serves as a placeholder for the messages provided at runtime. Then users could add a system message and or a user message around the messages placeholder. Would have to think this through more but wdyt?

[anakin87]

Or maybe more radical we throw away system and user prompt at init time and just a generic messages_template which would be a jinja2 template that would default to {{messages}} which serves as a placeholder for the messages provided at runtime. Then users could add a system message and or a user message around the messages placeholder. Would have to think this through more but wdyt?

Not a bad idea.

In general, I thought that keeping system_prompt in __init__ can be convenient for users.

But feel free to explore your idea further...

[sjrl]

Or maybe more radical we throw away system and user prompt at init time and just a generic messages_template which would be a jinja2 template that would default to {{messages}} which serves as a placeholder for the messages provided at runtime. Then users could add a system message and or a user message around the messages placeholder. Would have to think this through more but wdyt?

Not a bad idea.

In general, I thought that keeping system_prompt in __init__ can be convenient for users.

But feel free to explore your idea further...

That's fair about system_prompt. I'll note this idea down in our notion page and aim to tackle it in a future PR. For now I think we can move forward with this simplification and revisit this idea.