fix: improve AGENT_BACKEND_BASE_URL error message with config guidance

The Agent node (agent_v2) in Workflow/Chatflow fails with a generic
'base_url is required' error when AGENT_BACKEND_BASE_URL is not set.
The standard docker/dify Compose stack doesn't include the Agent backend
service, so self-hosted users hit this error with no hint about what to
do. Replace the bare ValueError with a message that names the env var,
explains the service requirement, and suggests the classic Agent app
as an alternative.

Fixes #39161

api/clients/agent_backend/factory.py

@@ -27,7 +27,16 @@ def create_agent_backend_run_client(
     if use_fake:
         return FakeAgentBackendRunClient(scenario=FakeAgentBackendScenario(fake_scenario))
     if base_url is None:
-        raise ValueError("base_url is required when creating a real Agent backend client")
+        raise ValueError(
+            "AGENT_BACKEND_BASE_URL is not configured. The Chatflow/Workflow Agent node "
+            "requires a separately deployed Agent backend service. Set the "
+            "AGENT_BACKEND_BASE_URL environment variable to the service's URL, "
+            "or use the classic Agent-type app (mode: agent-chat) which runs "
+            "in-process and does not require this service."
+        )
+    headers: dict[str, str] = {}
+    if api_token:
+        headers["Authorization"] = f"Bearer {api_token}"
     return DifyAgentBackendRunClient(
         create_agent_backend_client(
             base_url=base_url,

api/tests/unit_tests/clients/agent_backend/test_factory.py

@@ -71,3 +71,22 @@ def test_default_agent_backend_clients_forward_authentication(
     factory()
 
     create_client.assert_called_once_with(base_url="http://agent-backend", api_token="secret-token")
+
+
+def test_missing_base_url_raises_helpful_error():
+    """When AGENT_BACKEND_BASE_URL is not set, the error should mention the
+    environment variable and suggest alternatives (issue #39161)."""
+    with pytest.raises(ValueError) as exc_info:
+        create_agent_backend_run_client(base_url=None)
+
+    message = str(exc_info.value)
+    # The error must mention the env var name so users know what to set.
+    assert "AGENT_BACKEND_BASE_URL" in message
+    # The error should hint at the classic Agent app as an alternative.
+    assert "agent-chat" in message
+
+
+def test_use_fake_does_not_require_base_url():
+    """The fake client path should not raise even when base_url is None."""
+    client = create_agent_backend_run_client(use_fake=True, base_url=None)
+    assert client is not None