AgentAppGenerator raises ValueError when self-hosted has no AGENT_BACKEND_BASE_URL set
- Dominant language
- TypeScript
- Stars
- 156k
- Forks
- 24.6k
- Avg merge
- 22h 9m
- Merged PRs (30d)
- 610
Description
### Self Checks
- [x] I have read the [Contributing Guide](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md) and [Language Policy](https://github.com/langgenius/dify/issues/1542).
- [x] This is only for bug report, if you would like to ask a question, please head to [Discussions](https://github.com/langgenius/dify/discussions/categories/general).
- [x] I have searched for existing issues [search for existing issues](https://github.com/langgenius/dify/issues), including closed ones.
- [x] I confirm that I am using English to submit this report, otherwise it will be closed.
- [x] 【中文用户 & Non English User】请使用英语提交,否则会被关闭 :)
- [x] 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.
Contributor guide
Research direction
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.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api, backend
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 78/100