App Mode Configuration#

Dify supports multiple app modes, each with a distinct configuration source, dispatch path, and feature validation logic. The AppMode enum 1 defines all recognized modes.

The most important architectural boundary: legacy modes (chat, agent-chat, advanced-chat) read configuration from AppModelConfig or Workflow.features_dict; the newer agent mode reads from an AgentSoulConfig JSON snapshot stored per-version in AgentConfigVersion.config_snapshot.

Dispatch: AppGenerateService#

AppGenerateService._dispatch_generate() is the central router. Before the match/case branch, it computes an effective mode that handles legacy promotion 2:

effective_mode = (
    AppMode.AGENT_CHAT
    if app_model.is_agent_with_session(session=session) and app_model.mode != AppMode.AGENT_CHAT
    else app_model.mode
)

is_agent_with_session() checks whether app_model_config.agent_mode has function_call or react strategy enabled. If so, it auto-updates the database row to AGENT_CHAT and returns True — transparently migrating legacy chat-with-agent apps without a manual migration 3.

Legacy EasyUI Modes: AppModelConfig#

For CHAT, AGENT_CHAT, and COMPLETION, configuration comes from the AppModelConfig ORM model 4 — a flat database row storing model selection, system prompt (pre_prompt), agent mode settings (agent_mode), and feature flags. Mode-specific config managers (ChatAppConfigManager, AgentChatAppConfigManager) load this row and convert it into typed config entities.

ADVANCED_CHAT is the exception: it never reads AppModelConfig. Instead, AdvancedChatAppConfigManager reads Workflow.features_dict from a linked workflow and returns a WorkflowUIBasedAppConfig.

Feature availability checks in MessageService reflect this multi-mode split. For suggested questions after answer, get_suggested_questions_after_answer() dispatches based on mode 5:

• ADVANCED_CHAT: reads from workflow.features_dict
• AGENT: resolves via AgentRuntimeConfigService (introduced in PR #40963 to fix #39681), following a fallback chain:
  1. Debug draft (AgentConfigDraft) if invoke_from == InvokeFrom.DEBUGGER
  2. Conversation's bound snapshot (AgentConfigSnapshot or AgentConfigDraft via AgentWorkspaceBinding)
  3. Current published Soul from AgentRosterService
  4. Legacy AppModelConfig (merged via merge_agent_app_features)
• Other modes (CHAT, AGENT_CHAT, COMPLETION): read from app_model_config.suggested_questions_after_answer_dict

Agent debug Conversations intentionally persist app_model_config_id = NULL because their configuration comes from the Agent Soul; the resolution service allows them to locate their draft config without a legacy AppModelConfig lookup.

AGENT Mode: AgentSoulConfig#

The AGENT mode (app type introduced alongside Agent V2) diverges entirely from AppModelConfig. Its configuration is a versioned JSON snapshot validated against AgentSoulConfig 6:

AgentSoulConfig uses extra="forbid", so any unknown field in the stored JSON causes a hard validation error 7.

Validation gate: AgentAppGenerator._resolve_agent() calls AgentSoulConfig.model_validate(snapshot.config_snapshot_dict) before allowing generation 8. For draft/debug runs it validates against the draft snapshot; for published runs it validates the active snapshot. If the agent or snapshot is missing, an AgentAppGeneratorError is raised before any LLM call.

Publish-time guard: AgentComposerService.publish_agent_app_draft() additionally checks agent_soul_has_model() and raises AgentModelNotConfiguredError (HTTP 400, error code agent_model_not_configured) if AgentSoulConfig.model is None 9.

Synthesizing Soul into the Chat Pipeline#

The AGENT mode reuses the existing chat/SSE pipeline through an adapter layer. AgentAppConfigManager.get_app_config() 10 synthesizes an app_model_config-shaped dict from the Agent Soul:

• Model + prompt always come from the Agent Soul — AgentSoulConfig.model maps to the model key; agent_soul.prompt.system_prompt populates pre_prompt 11.
• Feature flags are merged: if a legacy AppModelConfig row exists, its flags are loaded first, then AgentSoulConfig.app_features is applied on top — Soul fields win on conflict 12 13.
• User input form is built from app_variables via agent_app_variables_to_user_input_form() 14.

The result (AgentAppConfig) is an EasyUIBasedAppConfig subclass that downstream chat pipeline components handle identically to a regular chat app.

Key Source Files#