Agent App Architecture#

The standalone Agent app (AppMode.AGENT, value "agent") is Dify's next-generation agent surface. It differs from the legacy AGENT_CHAT mode in two key ways: (1) its configuration comes from a versioned AgentSoulConfig JSON snapshot stored per-version in AgentConfigVersion.config_snapshot, not from a flat AppModelConfig row; and (2) execution is fully delegated to the dify-agent FastAPI microservice (Agent V2 backend) rather than running an in-process ReAct or function-calling loop 1.

The Agent app reuses Dify's existing EasyUI chat pipeline — conversation/message persistence, SSE streaming, annotation replies, content moderation — through a thin adapter layer. The agent backend produces the answer; the standard pipeline delivers and persists it. See also: Agent V2 Architecture for the backend internals.

HTTP request
    │
    ▼
AppGenerateService._dispatch_generate() ← routes AppMode.AGENT
    │
    ▼
AgentAppGenerator.generate() ← api/core/app/apps/agent_app/app_generator.py
    ├── _resolve_agent() ← loads AgentSoulConfig snapshot/draft
    ├── AgentAppConfigManager ← synthesizes EasyUI AppConfig for pipeline
    ├── MessageBasedAppQueueManager ← SSE queue
    └── worker thread → AgentAppRunner.run()
            ├── AgentAppWorkspaceStore ← load/create AgentWorkspaceBinding
            ├── AgentAppRuntimeRequestBuilder ← builds CreateRunRequest
            ├── agent_backend_client.create_run() → dify-agent service
            ├── _consume_stream() ← adapts backend SSE to queue events
            └── _save_session() ← saves CompositorSessionSnapshot to binding

Entry Point and Config Resolution#

AgentAppGenerator.generate() is the entry point. It only supports streaming mode 2 and orchestrates the following steps:

1. Resolve agent + soul: _resolve_agent() loads the correct AgentSoulConfig based on invoke context:

   • DEBUGGER invokes: resolves an AgentConfigDraft (type DRAFT or DEBUG_BUILD)
   • Published runs (new conversation): uses agent.active_config_snapshot_id
   • Existing conversations: reads conversation.agent_workspace_binding_id → AgentWorkspaceBinding.agent_config_version_id to guarantee the conversation always uses the config it started with, even after a publish

2. Synthesize EasyUI config: AgentAppConfigManager.get_app_config() converts the AgentSoulConfig into an AgentAppConfig (an EasyUIBasedAppConfig subclass) so the downstream chat pipeline can handle usage persistence, feature flags, and prompt config identically to a regular chat app.

3. Initialize records: _init_generate_records() creates the Conversation and Message DB rows, then spawns a worker thread that calls _generate_worker().

4. Input guards (in worker, skipped on resume): content moderation and annotation reply checks run before the backend call. An annotation hit publishes the answer and returns early without reaching the agent backend 3.

The agent_session_scope_config_version_id field (passed as session_scope_snapshot_id to the runner) scopes workspace binding reuse: draft runs use the draft row ID; published runs use the immutable snapshot ID. This prevents state leakage between draft/published surfaces 4.

Session State: Workspace Binding and Session Snapshots#

Multi-turn memory is managed through AgentAppWorkspaceStore, which resolves a persistent AgentWorkspaceBinding that connects the conversation (or build draft) to the agent's workspace.

Dual persistence: each conversation turn writes to two places:

1. Standard Dify tables (Conversation, Message, MessageAgentThought): handled by the EasyUI pipeline as usual.
2. AgentWorkspaceBinding.session_snapshot: a serialized CompositorSessionSnapshot JSON blob that captures the agenton layer state (including PydanticAIHistoryLayer message history) for cross-turn LLM context continuity 5.

Load or create flow (load_or_create()):

• Looks up the caller object (a Conversation or AgentConfigDraft) by agent_workspace_binding_id.
• If None (first turn): calls AgentWorkspaceService.create_binding() to allocate a new participant with physical backend resources, then writes the new binding ID back to the caller.
• Existing binding: validated via AgentWorkspaceService.validate_binding_generation() to ensure the generation (config version + home snapshot) matches.

Snapshot save (save_active_snapshot()): after each run completes (successfully, failed, or cancelled), the terminal event's session_snapshot is serialized and persisted to AgentWorkspaceBinding.session_snapshot via AgentWorkspaceService.save_binding_session_snapshot(). A None snapshot—when compositor entry failed or layer exit did not complete—leaves the previous snapshot untouched. Only snapshots from runs that reached compositor exit are persisted, enabling resumption from the last valid state even after failures or cancellations.

The AgentAppSessionScope dataclass encodes the full scope key: (tenant_id, app_id, conversation_id, agent_id, agent_config_snapshot_id). When build_draft_id is set, the owner type switches to BUILD_DRAFT instead of CONVERSATION 6.

Runtime Request Building#

AgentAppRuntimeRequestBuilder.build() assembles the CreateRunRequest sent to the dify-agent backend. Key aspects:

• Model credentials: NOT passed to the agent backend. The dify-agent runtime calls back to Dify API through /inner/api/agent/llm/invoke, which owns credential resolution and billing/quota metering. System-hosted model calls are charged through CreditPoolService; custom credentials remain non-billable. The agent invocation ID is reused as the billing request ID for idempotent retries 7.
• Tool layers: plugin tools → dify.plugin.tools; builtin/API/workflow/MCP tools → dify.core.tools 8.
• Model settings: agent_soul.model.model_settings is passed through a whitelist (temperature, top_p, presence_penalty, frequency_penalty, max_tokens, stop_sequences) 9.
• Session snapshot: the CompositorSessionSnapshot from the loaded binding is forwarded as session_snapshot in the run request, enabling the dify-agent service to restore the previous turn's history layer 10.
  • Snapshot compatibility validation: before calling the agent backend, the system validates that the retained session snapshot still matches the current composition via _validate_session_snapshot_layers(). The method compares the ordered layer names from request.composition.layers against session_snapshot.layers. If the topology has changed (layers added, removed, or reordered), the system raises AgentSessionSnapshotIncompatibleError (HTTP 409 with code "agent_session_configuration_changed"). Draft rows are updated in place, so their IDs cannot prove that a retained snapshot still belongs to the current composition. Configuration value changes (e.g., prompt edits) WITHOUT topology changes preserve session reuse.
• backend_binding_ref: the participant identity string from AgentWorkspaceBinding, required by the agent backend for workspace/resource lookup 11.
• Prompt mentions: expand_prompt_mentions() resolves slash-menu {{#...#}} tokens before the system prompt reaches the model 12.
• Deferred tool results: set when resuming after an ask_human pause 13.
• Multimodal file handling: uploaded files are parsed into access-controlled Dify File objects via file_factory.build_from_mapping() in AgentAppGenerator.generate() before reaching the runtime builder. The builder detects whether the selected model supports vision capabilities by calling resolve_model_supports_vision() from core.app.llm.model_access, which inspects the credential-bound model schema for the ModelFeature.VISION feature flag. Image files are sent as native multimodal content through the new DifyUserPromptLayerConfig layer when vision is supported; the system converts image URLs to Pydantic AI ImageUrl content and inline Base64 images to BinaryContent. Non-image files and models without vision support fall back to the dify-agent file download mechanism (shell-based download instructions appended to the user prompt text).

The builder shares helper functions with the workflow AgentV2 node (e.g., build_knowledge_layer_config, build_shell_layer_config, build_ask_human_layer_config) imported from api/core/workflow/nodes/agent_v2/runtime_request_builder.py.

AgentAppRunner: Stream Consumption and Process Recording#

AgentAppRunner.run() orchestrates a single conversation turn:

1. Load/create workspace session → obtain backend_binding_ref and prior session_snapshot.
2. Build AgentAppRuntimeRequest (including deferred tool results if resuming from ask_human).
3. POST to the agent backend via create_run() → receive run_id.
4. _consume_stream(): consume SSE events until a terminal event arrives. The method tracks last_event_id from each public event and passes session_scope and binding_id to enable session-aware cancellation:
   • Text deltas (AgentBackendAgentMessageDeltaInternalEvent): buffered by _TextDeltaDebouncer to avoid per-character SSE frames, then published as QueueAgentMessageEvent 14.
   • Process events (AgentBackendStreamInternalEvent): handled by _AgentProcessRecorder — writes MessageAgentThought DB rows (tool calls, thinking, observations) and fires QueueAgentThoughtEvent 14.
   • Stop signal: if queue_manager.is_stopped(), calls _cancel_run(run_id, after=last_event_id, session_scope, binding_id) to notify the backend, waits for cleanup to complete and persists any returned snapshot, then raises GenerateTaskStoppedError 15.
5. On AgentBackendRunSucceededInternalEvent: publish final answer → _save_session() persists the snapshot.
6. On AgentBackendDeferredToolCallInternalEvent: _pause_for_ask_human() (see HITL section).
7. On AgentBackendRunFailedInternalEvent or AgentBackendRunCancelledInternalEvent: checks for a non-None session_snapshot and persists it before translating reason to an InvokeError subclass via _agent_backend_failure_to_exception().

Error handling in _generate_worker(): AgentSessionSnapshotIncompatibleError is caught and published to the queue manager. This expected topology mismatch (HTTP 409 with code "agent_session_configuration_changed" and message "The Agent configuration changed after this conversation started. Start a new conversation to continue.") is logged at info level rather than triggering an unknown error traceback. The client receives the user-facing instruction as an error event.

The runner emits only four queue event types: QueueAgentMessageEvent, QueueAgentThoughtEvent, QueueLLMChunkEvent, QueueMessageEndEvent. QueueRetrieverResourcesEvent is intentionally absent — retrieval citations are not surfaced in the Agent App SSE stream 14.

HITL / ask_human Flow#

When the agent calls dify.ask_human, the backend emits AgentBackendDeferredToolCallInternalEvent instead of a success terminal. The runner handles this in _pause_for_ask_human():

1. Creates a conversation-owned HITL form (keyed by message_id as node_id).
2. Persists session_snapshot, pending_form_id, and pending_tool_call_id on the AgentWorkspaceBinding via _save_session().
3. Publishes the agent's question as the turn answer, ending the chat turn from the client's perspective.

Resume: AgentAppGenerator.resume_after_form_submission() is triggered (by a background task) after the user submits the form:

• Re-resolves the agent/soul for the correct draft type using _resolve_resume_draft() 16.
• Runs _generate_worker(is_resume=True) — input guards are skipped to avoid short-circuiting the resume with moderation or annotation matching on the replayed query 17.
• The original turn's query is re-sent (not as new user input) to satisfy the agent backend's requirement that layer names in the composition match the suspended snapshot 18.
• Inside the runner, _resolve_pending_ask_human() reads the stored pending_form_id, fetches the submitted form result, and builds a DeferredToolResultsPayload. This is forwarded with the session snapshot in the CreateRunRequest to resume the paused backend run.

Key Source Files#