Chatflow/Workflow "Agent" node (agent_v2) is unusable in the standard `docker/dify` deployment — requires an undeployed "Agent backend" service
- 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
1.15.0
### Cloud or Self Hosted
Self Hosted (Docker)
### Steps to reproduce
## Steps to reproduce
### Summary
In the standard self-hosted Docker deployment, the **Agent node (`agent_v2`)** in Workflow/Chatflow cannot be executed. Every run fails immediately with:
```
base_url is required when creating a real Agent backend client
```
The Agent node delegates execution to a separate **"Agent backend"** service whose location is configured via the `AGENT_BACKEND_BASE_URL` environment variable. However, the standard `docker/dify` Compose stack **does not include this service and does not set this variable**, so the node fails *before* any request reaches the LLM. As a result, the Agent node is effectively non-functional out of the box, and the failure is not attributable to the model, MCP, or agent-strategy configuration.
### Environment
- Deployment: self-hosted, standard `docker/dify` Docker Compose stack
- `dify-api` version: `1.15.0` series
- OS: Linux (Docker CE)
- Node in question: Chatflow/Workflow **Agent** node (`agent_v2`)
### Steps
1. Deploy Dify using the standard `docker/dify` Docker Compose stack (no custom services added).
2. Create a Chatflow (or Workflow).
3. Add an **Agent** node (`agent_v2`) to the flow.
4. Configure a valid, verified model provider and (optionally) MCP tools.
5. Run the flow.
### ✔️ Expected Behavior
## ✔️ Expected Behavior
The Agent node executes using the configured model and tools, in the same way other LLM-backed nodes work in the standard deployment — without requiring an additional service to be manually deployed.
### ❌ Actual Behavior
## ❌ Actual Behavior
The node fails immediately with the following error:
```
base_url is required when creating a real Agent backend client
```
This error is raised by `clients/agent_backend/factory.py` and occurs **before the request reaches the LLM**. The Agent node relies on a separate "Agent backend" service addressed by `AGENT_BACKEND_BASE_URL`, which is neither included nor configured in the standard `docker/dify` stack.
### Investigation / what we ruled out
While building a demo in which Dify calls MySQL through the Docker MCP Gateway (Dify → MCP Gateway → `database-server` → MySQL), we needed an agent capable of calling MCP tools. We initially tried the Chatflow Agent node and traced the failure as follows:
- The error originates in Dify core (`clients/agent_backend/factory.py`) and is thrown at client-construction time, **before** any model call.
- Because the failure is upstream of the LLM, the following changes had **no effect** — the identical error persists in every case:
- Switching model providers / models
- Changing or removing MCP server settings
- Changing the agent-strategy plugin (e.g. `junjiem` / `hjlarry`)
- Therefore the root cause is the **missing/unconfigured Agent backend service**, not any of the above settings.
### Workaround we adopted
We switched to the classic **"Agent"-type app** (`mode: agent-chat`) instead of a Chatflow Agent node. That app type runs entirely **inside the `api` container** and does **not** require the Agent backend service or an agent-strategy plugin. It can use already-registered/authorized MCP tools directly (Function Calling), and works reliably in the standard deployment. This confirms the model/MCP configuration itself is fine; only the Chatflow/Workflow Agent node path is blocked.
### Impact
- The Agent node appears as an available node in Chatflow/Workflow, but is unusable in the standard self-hosted deployment, which is confusing for users.
- The error message (`base_url is required when creating a real Agent backend client`) does not indicate that a separate service must be deployed, so users spend time investigating unrelated settings (model, MCP, strategy plugin).
### Suggested resolution (any of the following)
1. **Documentation:** Clearly document that the Chatflow/Workflow Agent node requires a separately deployed "Agent backend" service and the `AGENT_BACKEND_BASE_URL` variable, and that neither is present in the standard `docker/dify` stack. Point users to the "Agent"-type app as the supported path when the backend is not deployed.
2. **Compose:** Optionally include the Agent backend service (and a default `AGENT_BACKEND_BASE_URL`) in the standard `docker/dify` stack, or provide an opt-in override file for it.
3. **UX / error message:** Improve the error to state that the Agent backend service is not configured/deployed, and either disable or clearly flag the Agent node when `AGENT_BACKEND_BASE_URL` is unset.
Contributor guide
Research direction
Start with clients/agent_backend/factory.py and the standard docker/dify Compose files, then reproduce the failure by running the stack and executing an agent_v2 node. Trace how AGENT_BACKEND_BASE_URL is read and confirm whether the Agent backend service is included. Done means the accepted resolution is verified for a standard deployment, including a clear outcome for the missing-service case.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, docker-compose, python
- Domain
- api, backend, devops
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100