Agent Strategy Plugin Architecture#

Agent strategies — the reasoning engines that power Dify's Agent node in Workflows and Chatflows (agent_v2) — are not built into the API process. They are plugins resolved at runtime through the Plugin Daemon. This means strategy availability is entirely determined by which plugins are installed and whether the required services are running; it is not an intentional Cloud-vs-self-hosted feature restriction.

Two agent surfaces coexist: The legacy Agent-type app (mode: agent-chat) runs entirely in-process with hard-coded CoT/Function-Calling runners (BaseAgentRunner, CotAgentRunner, FunctionCallAgentRunner) and requires no additional services. The newer Workflow/Chatflow Agent node (agent_v2) uses the plugin-backed architecture described here. 1

Runtime Resolution Flow#

When an Agent node executes inside a workflow, the resolution chain is:

AgentNode._run()
  → AgentStrategyResolver.resolve(provider, strategy_name)
  → PluginAgentStrategy (wraps invocation)
  → PluginAgentClient (HTTP → Plugin Daemon :5002)
  → Plugin Daemon loads & executes the agent strategy plugin

1. AgentNode._run() resolves the configured strategy at execution time (not at workflow load), allowing plugins to be installed or updated without redeploying. 2

2. PluginAgentStrategy implements the strategy pattern, converting parameters to the plugin wire format and delegating invocation to PluginAgentClient. 3

3. PluginAgentClient makes HTTP calls to the Plugin Daemon 4:

   • List providers: GET /plugin/{tenant_id}/management/agent_strategy
   • Invoke: POST /plugin/{tenant_id}/dispatch/agent_strategy/invoke

4. AgentService.list_agent_providers() and get_agent_provider() expose the same PluginAgentClient calls as API endpoints for the UI.

The frontend AgentStrategySelector fetches available strategies via useStrategyProviders and renders them as a searchable picker. If a selected strategy's plugin is not installed, the selector shows a warning and optionally an install button. 5

Agent Strategy Plugin Structure#

An agent strategy plugin is a standard Dify plugin whose manifest.yaml has the agent_strategy key — automatically classified as PluginCategory.AgentStrategy by the PluginDeclaration model validator. 6 Installation sources follow the standard plugin model: Marketplace, GitHub, local package, or remote URL.

The dify-agent backend service (introduced in PR #36087) handles the actual async execution of agent runs, communicating with the Plugin Daemon to resolve LLM providers and tools. It is a FastAPI microservice distinct from the API process. 1

Availability: Cloud vs Self-Hosted#

The availability gap between Cloud and self-hosted is a deployment configuration difference, not a feature gate:

As of v1.16.0, agent_backend is a fully wired, non-optional service in docker/docker-compose.yaml, with api and worker depending on it at startup. Before v1.16.0, AGENT_BACKEND_BASE_URL was not set in the default stack, causing the Agent node to fail immediately with base_url is required when creating a real Agent backend client. 7

AGENT_BACKEND_USE_FAKE=true is a development stub that returns a hard-coded response without calling any LLM or tools. It is not a functional workaround. 7

Key Configuration & Source References#

Key source files: