Agent Model Settings#

Overview#

Agent model settings govern how an LLM is configured when an agent run is dispatched to the Agent backend. The canonical storage model is AgentSoulModelSettings inside AgentSoulModelConfig, which nests under AgentSoulConfig.model. Settings flow from there through two filtering stages before reaching DifyPluginLLMLayerConfig inside the run request.

Stage 1 — Pydantic Validation (extra='allow')#

AgentSoulModelSettings inherits from AgentFlexibleConfig (which uses extra="allow"), so plugin-declared model parameters beyond the explicit schema — such as Qwen/Tongyi's enable_thinking — are preserved during validation and round-trip through persistence 1. The typed fields are:

This first stage ensures plugin-specific parameters survive the save/publish round trip, addressing issue #40144 where parameters like enable_thinking were being silently dropped.

Stage 2 — Runtime Whitelist (_agent_model_settings)#

When building a run request, both the standalone Agent App builder and the Workflow Agent V2 builder call:

model_settings=agent_soul.model.model_settings.model_dump(mode="json", exclude_none=True)

That serialized dict is passed into _agent_model_settings() inside api/clients/agent_backend/request_builder.py. This function applies a whitelist before the payload reaches DifyPluginLLMLayerConfig 2:

_AGENT_MODEL_SETTINGS_PASSTHROUGH_KEYS = (
    "temperature", "top_p", "presence_penalty", "frequency_penalty", "max_tokens"
)

These five keys, plus any parameter not in the known set (temperature, top_p, presence_penalty, frequency_penalty, max_tokens, stop, response_format), are forwarded 3. Plugin-specific parameters (those outside the known set) are placed into an extra_body dict, which is the escape hatch provided by pydantic_ai's ModelSettings TypedDict for provider-specific settings. Additionally, the stop list is remapped: a non-empty stop becomes stop_sequences in the LLM layer config 4. The response_format field does not pass through — it is consumed at the soul level only.

The motivation, documented in a code comment, is that DifyPluginLLMLayerConfig.model_settings is pydantic_ai's ModelSettings TypedDict, which rejects unknown top-level keys — so plugin parameters are forwarded via extra_body rather than discarded 5.

Schema Evolution — PR #37210 and PR #40163#

PR #37210 ("fix(agent-v2): complete console API contract schemas", merged 2026-06-09) tightened AgentSoulModelSettings from extra="allow" to extra="ignore" 6. The broader goal of the PR was to ensure generated API contracts (TypeScript/Zod schemas) don't expose loose { [key: string]: unknown } objects. Several other config models (WorkflowNodeJobMetadata, AgentSoulDifyToolConfig, etc.) received the same treatment.

PR #40163 ("fix(agent): preserve plugin-declared model parameters through Agent Soul", merged 2026-08-09) reversed this decision for AgentSoulModelSettings, changing it from extra="ignore" to extra="allow" (via AgentFlexibleConfig inheritance) to fix issue #40144 7. This change ensures that plugin-declared model parameters (e.g. Qwen's enable_thinking) are preserved during save/publish and forwarded to the backend via extra_body, rather than being silently dropped. The _agent_model_settings() function was also updated to forward unknown parameters into extra_body.

Flow Summary#

AgentSoulConfig.model.model_settings (AgentSoulModelSettings, extra="allow")
        │
        │ .model_dump(mode="json", exclude_none=True)
        ▼
AgentBackendModelConfig.model_settings (dict[str, JsonValue])
        │
        │ _agent_model_settings() ← passthrough whitelist + stop→stop_sequences + extra→extra_body
        ▼
DifyPluginLLMLayerConfig.model_settings (sent to plugin daemon)

Key Files#

Related Topics#

• Plugin Daemon Model Parameter Handling — covers the completion_params bug (issue #39274) in legacy V1 Agent nodes where completion_params was empty, and the fix in PR #39590 that populates defaults from model_schema.parameter_rules (see knowledge base page).
• Agent Node Data Models — Pydantic schemas for workflow node fields; distinct from the soul-level model settings described here.