AgentAppGenerator raises ValueError when self-hosted has no AGENT_BACKEND_BASE_URL set

Start in api/clients/agent_backend/factory.py and trace create_agent_backend_run_client(), then review the existing FakeAgentBackendRunClient and DifyAgentBackendRunClient test suites. Reproduce the default self-hosted configuration with Agent V2 enabled, add coverage for a missing or blank AGENT_BACKEND_BASE_URL, and verify that configured real and explicit fake clients remain unchanged.

Self Checks

• I have read the Contributing Guide and Language Policy.
• This is only for bug report, if you would like to ask a question, please head to Discussions.
• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report, otherwise it will be closed.
• 【中文用户 & Non English User】请使用英语提交，否则会被关闭 ：）
• Please do not modify this template :) and fill in all the required fields.

Dify version

main branch (uncommitted)

Cloud or Self Hosted

Self Hosted (Source)

Steps to reproduce

Discovered by peaks-loop code-sweep on 2026-07-02.

1. Install Dify v1.15.0 self-hosted (Docker) with default config. Confirm AGENT_BACKEND_BASE_URL is unset (defaults to None in configs/extra/agent_backend_config.py).
2. Enable Agent V2 (AGENT_STRATEGY=function_call or cot) in .env.
3. Open an Agent app and send any chat message.
4. Observe HTTP 500 with the body {"error": "base_url is required when creating a real agent backend client"}. The full stack trace points at clients/agent_backend/factory.py:21.

✔️ Expected Behavior

A self-hosted deployment without AGENT_BACKEND_BASE_URL should automatically fall back to the in-process fake client (FakeAgentBackendRunClient(scenario=fake_scenario)), which is the documented behavior for users who do not configure an explicit agent backend. No HTTP 500.

❌ Actual Behavior

In Dify v1.15.0 with Agent V2 enabled, AgentAppGenerator raises ValueError("base_url is required when creating a real agent backend client") from clients/agent_backend/factory.py:21 when a self-hosted deployment has not set AGENT_BACKEND_BASE_URL (which defaults to None in configs/extra/agent_backend_config.py).

The raise is unhelpful for default-config users: it surfaces at request time inside _generate_worker (core/app/apps/agent_app/app_generator.py:331) and aborts every Agent app call with HTTP 500, even though the in-process fake client is perfectly capable of serving the request end-to-end.

Proposed change: In api/clients/agent_backend/factory.py, create_agent_backend_run_client() should treat a missing or empty base_url the same as use_fake=True — return a FakeAgentBackendRunClient(scenario=fake_scenario) instead of raising.

• Self-hosted deployments that want the real backend: set AGENT_BACKEND_BASE_URL to a non-empty value (they implicitly disable the fake by providing a real URL).
• Self-hosted deployments that want the fake explicitly: pass use_fake=True, unchanged.
• Tests the existing FakeAgentBackendRunClient and DifyAgentBackendRunClient test suites still apply (one new branch covered, no existing test should regress).

Risk: When base_url is provided, the function still constructs a real DifyAgentBackendRunClient — unchanged. When use_fake=True, the function still returns the fake client — unchanged. The new behavior only activates when base_url is None or not base_url.strip(). Self-hosted deployments that intentionally want the real backend must provide a real URL — which is what AGENT_BACKEND_BASE_URL already documents. No schema, migration, controller, or frontend changes.