chore!: make required_variables all on by default for Agent (#12027)

Author: sjrl

MIGRATION.md

@@ -477,6 +477,58 @@ pipeline.run(data={"retriever": {"query": query}, "agent": {"messages": [], "que
 If the prompt itself must still be assembled per run, build `ChatMessage` objects before the `Agent` (e.g. with a `ChatPromptBuilder`) and pass them through the `messages` input.
 For a runtime system prompt, construct an `Agent` without `system_prompt` or `user_prompt` and include a system message at the start of `messages`.
 
+#### Prompt template variables are required by default
+
+**What changed:** `Agent` now treats every Jinja2 template variable in `user_prompt` and `system_prompt` as required by default. The `required_variables` parameter's default has been changed from `None` (all optional) to `"*"` (all required). Previously, missing variables were silently rendered as empty strings. Passing `required_variables=None` explicitly still opts into the old "all optional" behavior.
+
+**Why:** Avoids silent rendering bugs where a missing variable produces an unexpectedly empty section of the prompt. Aligns `Agent` with `LLM`, `PromptBuilder`, and `ChatPromptBuilder`, which already require all variables by default in v3.0.
+
+**How to migrate:**
+
+Before (v2.x):
+```python
+from haystack.components.agents import Agent
+
+# All variables were optional by default; missing values rendered as "".
+agent = Agent(
+    chat_generator=...,
+    tools=[...],
+    user_prompt="Answer {{query}} in {{language}}.",
+)
+agent.run(messages=[], query="What is NLP?")  # language silently becomes ""
+```
+
+After (v3.0):
+```python
+from haystack.components.agents import Agent
+
+# Option 1: provide every variable (matches the new safe default).
+agent = Agent(
+    chat_generator=...,
+    tools=[...],
+    user_prompt="Answer {{query}} in {{language}}.",
+)
+agent.run(messages=[], query="What is NLP?", language="English")
+
+# Option 2: declare which variables are required; everything else stays optional.
+agent = Agent(
+    chat_generator=...,
+    tools=[...],
+    user_prompt="Answer {{query}} in {{language}}.",
+    required_variables=["query"],
+)
+agent.run(messages=[], query="What is NLP?")  # language renders as ""
+
+# Option 3: restore the old "all optional" behavior.
+agent = Agent(
+    chat_generator=...,
+    tools=[...],
+    user_prompt="Answer {{query}} in {{language}}.",
+    required_variables=None,
+)
+agent.run(messages=[], query="What is NLP?")  # language renders as ""
+```
+
 #### Tools must declare `inputs_from_state` to read from `State` by name
 
 **What changed:** A tool now reads a value from the Agent's `State` by name only when it declares an explicit `inputs_from_state` mapping. Previously, a tool without `inputs_from_state` had every parameter implicitly treated as a potential `State` key: any parameter whose name matched a `State` key (and that the LLM did not supply) was silently filled from `State`. This implicit name-matching has been removed. It applies to every tool type, since `ComponentTool`, `PipelineTool`, `MCPTool`, and others all derive from the base `Tool` class.

docs-website/docs/overview/migration.mdx

@@ -251,6 +251,10 @@ The agent-specific breakpoint API (`AgentBreakpoint`, `ToolBreakpoint`, `AgentSn
 
 `Agent.run` and `Agent.run_async` no longer accept `system_prompt` or `user_prompt`; both must be set at initialization time. If a prompt must still be assembled per run, build `ChatMessage` objects before the Agent (for example, with a `ChatPromptBuilder`) and pass them through the `messages` input — a system message at the start of `messages` acts as a runtime system prompt. The same change applies to the `LLM` component.
 
+### Prompt template variables are required by default
+
+`Agent` now treats every Jinja2 template variable in `user_prompt` and `system_prompt` as required, in line with the [prompt builders](#prompt-builders-template-variables-are-required-by-default): the `required_variables` parameter's default changed from `None` (all optional) to `"*"` (all required). Previously, missing variables were silently rendered as empty strings. Pass `required_variables=["var1", "var2"]` to require only a subset, or `required_variables=None` to restore the old "all optional" behavior.
+
 ### Tools must declare `inputs_from_state` to read from `State` by name
 
 A tool now reads a value from the Agent's [`State`](../pipeline-components/agents-1/state.mdx) by name only when it declares an explicit `inputs_from_state` mapping. The old implicit behavior — any tool parameter whose name matched a `State` key was silently filled from `State` — has been removed. Add `inputs_from_state={"state_key": "parameter_name"}` to any tool that should read from `State`. Tools that take the full `State` object via a `State`-annotated parameter are unaffected.

haystack/components/agents/agent.py

@@ -473,7 +473,6 @@ def translate(
         user_prompt=\"\"\"{% message role="user"%}
     Translate the following document to {{ language }}: {{ document }}
     {% endmessage %}\"\"\",
-        required_variables=["language", "document"],
     )
 
     # The template variables 'language' and 'document' become inputs to the run method
@@ -544,7 +543,7 @@ def __init__(  # noqa: PLR0913
         tools: ToolsType | None = None,
         system_prompt: str | None = None,
         user_prompt: str | None = None,
-        required_variables: list[str] | Literal["*"] | None = None,
+        required_variables: list[str] | Literal["*"] | None = "*",
         exit_conditions: list[str] | None = None,
         state_schema: dict[str, Any] | None = None,
         max_agent_steps: int = 100,
@@ -569,7 +568,8 @@ def __init__(  # noqa: PLR0913
         :param required_variables:
             Lists the variables that must be provided as inputs to `user_prompt` or `system_prompt`.
             If a required variable is not provided at run time, an exception is raised.
-            If set to `"*"`, all variables found in the prompts are required. Optional.
+            If set to `"*"`, all variables found in the prompts are required. Defaults to `"*"`.
+            Set to `None` to make all variables optional; missing ones render as empty strings.
         :param exit_conditions: List of conditions that will cause the agent to return.
             Can include "text" if the agent should return when it generates a message without tool calls,
             or tool names that will cause the agent to return once the tool was executed. Defaults to ["text"].
@@ -711,7 +711,7 @@ def _register_prompt_variables(self) -> None:
         prompt_builders = [
             builder for builder in (self._system_chat_prompt_builder, self._user_chat_prompt_builder) if builder
         ]
-        if required_variables is not None and not any(builder.variables for builder in prompt_builders):
+        if isinstance(required_variables, list) and not any(builder.variables for builder in prompt_builders):
             logger.warning(
                 "The parameter required_variables is provided but neither user_prompt nor system_prompt "
                 "contains template variables. Either provide a prompt with Jinja2 template variables "

releasenotes/notes/agent-required-variables-by-default-4d3e97dd76710fec.yaml

@@ -0,0 +1,25 @@
+---
+upgrade:
+  - |
+    ``Agent`` now treats every Jinja2 template variable in ``user_prompt`` and ``system_prompt`` as
+    **required by default**. The default of the ``required_variables`` init parameter has changed from
+    ``None`` (all variables optional) to ``"*"`` (all variables required). This aligns ``Agent`` with
+    ``LLM``, ``PromptBuilder``, and ``ChatPromptBuilder``.
+
+    To check if you're affected: look for ``Agent(...)`` calls that pass a ``user_prompt`` or
+    ``system_prompt`` containing template variables without passing ``required_variables``. If those
+    Agents relied on missing variables being silently rendered as empty strings, the behavior depends on
+    how the missing variable was reaching the Agent:
+
+    - Calling ``agent.run()`` directly without providing a required variable now raises ``ValueError``.
+    - In a pipeline, if a required variable is neither provided as a user input nor connected from another
+      component, ``Pipeline.run`` raises ``ValueError("Missing mandatory input '<var>' for component '<name>'.")``.
+    - In a pipeline, if a required variable is connected to a sender that never produces output on a given run
+      (for example, a loop-fed input on the first iteration or a conditional branch that isn't taken), the
+      pipeline cannot make progress and raises ``PipelineComponentsBlockedError``.
+
+    Migration options:
+
+    - To require only a subset of variables, pass ``required_variables=["var1", "var2"]``.
+    - To preserve the previous "all optional" behavior, explicitly pass ``required_variables=None``.
+    - To require everything (the new default), no change is needed.

test/components/agents/test_agent.py

@@ -303,7 +303,7 @@ def test_to_dict(self, weather_tool, component_tool, monkeypatch):
                 ],
                 "system_prompt": None,
                 "user_prompt": None,
-                "required_variables": None,
+                "required_variables": "*",
                 "exit_conditions": ["text", "weather_tool"],
                 "state_schema": {"foo": {"type": "str"}},
                 "max_agent_steps": 100,
@@ -370,7 +370,7 @@ def test_to_dict_with_toolset(self, monkeypatch, weather_tool):
                 },
                 "system_prompt": None,
                 "user_prompt": None,
-                "required_variables": None,
+                "required_variables": "*",
                 "exit_conditions": ["text"],
                 "state_schema": {},
                 "max_agent_steps": 100,
@@ -1766,6 +1766,23 @@ def test_register_prompt_variables_warning_when_no_prompt_and_required_variables
         make_agent(required_variables=["name"])
         assert "The parameter required_variables is provided but neither" in caplog.text
 
+    def test_register_prompt_variables_no_warning_when_no_prompt_and_default(self, make_agent, caplog):
+        make_agent()
+        assert "The parameter required_variables is provided but neither" not in caplog.text
+
+    def test_register_prompt_variables_all_required_by_default(self, make_agent):
+        agent = make_agent(user_prompt=_user_msg("Question: {{question}}"))
+        assert agent._user_chat_prompt_builder.required_variables == "*"
+
+        socket = agent.__haystack_input__._sockets_dict["question"]
+        assert socket.is_mandatory
+
+    def test_register_prompt_variables_all_optional_with_none(self, make_agent):
+        agent = make_agent(user_prompt=_user_msg("Question: {{question}}"), required_variables=None)
+
+        socket = agent.__haystack_input__._sockets_dict["question"]
+        assert not socket.is_mandatory
+
     def test_register_prompt_variables_set_all_variables_as_required(self, make_agent):
         agent = make_agent(user_prompt=_user_msg("Question: {{question}}"), required_variables="*")
         assert agent._user_chat_prompt_builder.required_variables == "*"

test/components/agents/test_agent_hitl.py

@@ -119,7 +119,7 @@ def test_to_dict(self, tools, confirmation_hook, monkeypatch):
                 "raise_on_tool_invocation_failure": False,
                 "tool_concurrency_limit": 4,
                 "tool_streaming_callback_passthrough": False,
-                "required_variables": None,
+                "required_variables": "*",
                 "user_prompt": None,
                 "hooks": {
                     "before_tool": [