App Mode Configuration#

Dify routes every app through a mode-specific configuration source and generator. The AppMode enum defines all recognized modes; the central dispatcher is AppGenerateService._dispatch_generate().

Mode → Config Source Map#

1

Legacy EasyUI Modes (CHAT, AGENT_CHAT, COMPLETION)#

Configuration is read from the AppModelConfig ORM row — a flat database record storing model selection, system prompt (pre_prompt), agent strategy (agent_mode), and feature flag JSON columns. Mode-specific config managers (e.g., ChatAppConfigManager, AgentChatAppConfigManager) load this row and convert it into typed config entities 1.

Legacy promotion: Before dispatching, _dispatch_generate() computes an effective mode. If app_model_config.agent_mode has function_call or react strategy enabled, the app is silently promoted to AGENT_CHAT and the DB row is updated — transparently migrating old chat-with-agent apps without a manual migration 1.

ADVANCED_CHAT is the exception among legacy modes: it reads Workflow.features_dict through AdvancedChatAppConfigManager, not AppModelConfig 1.

AGENT Mode (Agent V2)#

AppMode.AGENT diverges entirely from AppModelConfig. Its configuration is a versioned JSON snapshot validated against AgentSoulConfig 1. Key top-level fields:

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

Validation gate: AgentAppGenerator._resolve_agent() calls AgentSoulConfig.model_validate(snapshot.config_snapshot_dict) before any LLM call. For debug runs it validates the draft; for published runs it validates the active snapshot. A missing agent or snapshot raises AgentAppGeneratorError 1.

Publish-time guard: AgentComposerService.publish_agent_app_draft() checks agent_soul_has_model() and raises AgentModelNotConfiguredError (HTTP 400, error_code: "agent_model_not_configured") if AgentSoulConfig.model is None 2.

Synthesizing Soul into the chat pipeline: AgentAppConfigManager.get_app_config() converts AgentSoulConfig into an AgentAppConfig (an EasyUIBasedAppConfig subclass) so the downstream pipeline handles persistence, feature flags, and prompt config identically to a regular chat app. 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, via merge_agent_app_features() 1.

Feature Availability Checks Per Mode#

Mode-gated feature checks live in MessageService.get_suggested_questions_after_answer(). The branching pattern is the canonical template for how mode-specific config is read at runtime 3:

• ADVANCED_CHAT → reads workflow.features_dict["suggested_questions_after_answer"] from the draft or published workflow 4.
• AGENT → delegates to MessageService._get_agent_suggested_questions_config(), which calls AgentRuntimeConfigService.resolve_conversation_soul() in this priority order 5:
  1. Debug draft (AgentConfigDraft) if invoke_from == InvokeFrom.DEBUGGER
  2. Conversation's bound snapshot via AgentWorkspaceBinding
  3. Current published Soul from AgentRosterService
  4. Legacy AppModelConfig (merged via merge_agent_app_features)
• CHAT / AGENT_CHAT / COMPLETION → reads AppModelConfig.suggested_questions_after_answer_dict directly; falls back to Conversation.model_config when override_model_configs is set 6.

Why the AGENT path is different: Agent debug conversations intentionally store app_model_config_id = NULL — their config comes from the Agent Soul, not an AppModelConfig row. Before PR #40963, the shared legacy lookup raised ValueError("did not find app model config"), producing HTTP 500. The AgentRuntimeConfigService resolution path was introduced to fix this 5.

Key Source Files#