Agent Strategy Plugin Architecture#

Agent strategies — the reasoning engines powering the Agent node (agent_v2) in Dify Workflows and Chatflows — are not built into the API process. They are plugins resolved at runtime through the Plugin Daemon, meaning strategy availability is determined entirely by which plugins are installed and whether required services are running. This is a deployment configuration difference, not an intentional Cloud-vs-self-hosted feature restriction. 1

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

Runtime Resolution Flow#

dify-agent microservice: The actual async execution of agent runs is handled by a dedicated FastAPI microservice (dify-agent) — distinct from the main API process — which communicates with the Plugin Daemon to resolve LLM providers and tools. It was introduced in PR #36087. 1

When an Agent node executes, the call chain is:

AgentNode._run()
  → AgentStrategyResolver.resolve(provider, strategy_name)
  → PluginAgentStrategy (parameter adapter)
  → 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 — so plugins can be installed or updated without redeploying. 2

2. PluginAgentStrategy is the strategy-pattern adapter. It holds the tenant_id and AgentStrategyEntity declaration, converts parameters to the plugin wire format, and delegates invocation to PluginAgentClient. 3

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

   • List providers: GET /plugin/{tenant_id}/management/agent_strategies
   • Invoke: POST /plugin/{tenant_id}/dispatch/agent_strategy/invoke
   • Responses are streamed as AgentInvokeMessage objects via SSE.

4. AgentService.list_agent_providers() and get_agent_provider() surface the same PluginAgentClient calls as REST endpoints for the UI. 5

5. The frontend AgentStrategySelector fetches available strategies via useStrategyProviders and renders a searchable picker. If a strategy's plugin is not installed, it shows a warning and an install button. 1

Plugin Structure & Installation#

An agent strategy plugin is a standard Dify plugin whose manifest.yaml includes the agent_strategy key. This automatically classifies it as PluginCategory.AgentStrategy in the PluginDeclaration model validator. 1

Installation sources follow the standard plugin model: Marketplace, GitHub, local package, or remote URL. Agent Skill plugins installed this way can be used inside both Workflow and Agent nodes.

Availability: Cloud vs Self-Hosted#

As of v1.16.0, agent_backend is a required service in docker/docker-compose.yaml, with api and worker depending on it at startup. Before v1.16.0, AGENT_BACKEND_BASE_URL was absent from the default stack, causing the Agent node to fail with base_url is required when creating a real Agent backend client. 1

In v1.16.1, Agent V2 nodes appear only in Workflow mode in the frontend node palette — Chatflow does not yet expose the Agent V2 node in the UI, though the backend supports both. Setting NEXT_PUBLIC_ENABLE_AGENT_V2=false restores the legacy Agent node for Chatflows. 6

Key Configuration Variables#

Defined in api/configs/extra/agent_backend_config.py 7:

The client factory at api/clients/agent_backend/factory.py instantiates either the real or fake backend client based on these settings.

Key Source Files#