chore: Moving some agent utils to utils file

[sjrl]

Related Issues

• fixes #issue-number

Proposed Changes:

Some maintenance work to move some of the accumulated util functions in the agents.py to the utils.py file. The methods are all private so no risk of breaking imports.

How did you test it?

Moved tests as well to test_utils.py

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	Aug 4, 2026 1:59pm

[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
utils.py					80, 276
Project Total

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

[julian-risch]

Changes look good to me in general. Only thing is that now no tests check that Agent still calls _validate_prompt_message_blocks.

I suggest that we add the following two tests back to TestPrompts in test_agent.py. Up to you if we just check for ValueError raised or if we match the message too. WDYT?

def test_prompt_wrong_role_raises_at_init(self, make_agent):
    with pytest.raises(ValueError, match="system_prompt message block must have role 'system'"):
        make_agent(system_prompt=_user_msg("This is a user message, not system."))
    with pytest.raises(ValueError, match="user_prompt message block must have role 'user'"):
        make_agent(user_prompt=_sys_msg("This is a system message, not user."))

def test_dynamic_prompt_role_raises_at_runtime(self, make_agent):
    agent = make_agent(user_prompt="{% message role=role_name %}Q: {{question}}{% endmessage %}")
    with pytest.raises(ValueError, match="user_prompt must render to a user message"):
        agent.run(messages=[], role_name="assistant", question="Will it snow?")