fix(api): tighten agent v2 generated contracts (#36989)

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

api/controllers/console/app/agent_app_feature.py

@@ -9,8 +9,6 @@ persists them onto the app's ``app_model_config`` without touching anything the
 Soul owns.
 """
 
-from typing import Any
-
 from flask_restx import Resource
 from pydantic import BaseModel, Field
 
@@ -25,13 +23,20 @@ from controllers.console.wraps import (
     with_current_user,
 )
 from events.app_event import app_model_config_was_updated
+from libs.helper import dump_response
 from libs.login import login_required
 from models import Account
+from models.agent_config_entities import (
+    AgentFeatureToggleConfig,
+    AgentSensitiveWordAvoidanceFeatureConfig,
+    AgentSuggestedQuestionsAfterAnswerFeatureConfig,
+    AgentTextToSpeechFeatureConfig,
+)
 from models.model import App, AppMode
 from services.agent_app_feature_service import AgentAppFeatureConfigService
 
 
-class AgentAppFeaturesRequest(BaseModel):
+class AgentAppFeaturesPayload(BaseModel):
     """Presentation features configurable on an Agent App.
 
     All fields are optional; an omitted field is reset to its disabled/empty
@@ -42,18 +47,20 @@ class AgentAppFeaturesRequest(BaseModel):
     suggested_questions: list[str] | None = Field(
         default=None, description="Preset questions shown alongside the opener"
     )
-    suggested_questions_after_answer: dict[str, Any] | None = Field(
+    suggested_questions_after_answer: AgentSuggestedQuestionsAfterAnswerFeatureConfig | None = Field(
         default=None, description="Follow-up suggestions config, e.g. {'enabled': true}"
     )
-    speech_to_text: dict[str, Any] | None = Field(default=None, description="Speech-to-text config")
-    text_to_speech: dict[str, Any] | None = Field(default=None, description="Text-to-speech config")
-    retriever_resource: dict[str, Any] | None = Field(
+    speech_to_text: AgentFeatureToggleConfig | None = Field(default=None, description="Speech-to-text config")
+    text_to_speech: AgentTextToSpeechFeatureConfig | None = Field(default=None, description="Text-to-speech config")
+    retriever_resource: AgentFeatureToggleConfig | None = Field(
         default=None, description="Citations / attributions config, e.g. {'enabled': true}"
     )
-    sensitive_word_avoidance: dict[str, Any] | None = Field(default=None, description="Content moderation config")
+    sensitive_word_avoidance: AgentSensitiveWordAvoidanceFeatureConfig | None = Field(
+        default=None, description="Content moderation config"
+    )
 
 
-register_schema_models(console_ns, AgentAppFeaturesRequest)
+register_schema_models(console_ns, AgentAppFeaturesPayload)
 register_response_schema_models(console_ns, SimpleResultResponse)
 
 
@@ -62,7 +69,7 @@ class AgentAppFeatureConfigResource(Resource):
     @console_ns.doc("update_agent_app_features")
     @console_ns.doc(description="Update an Agent App's presentation features (opener, follow-up, citations, ...)")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[AgentAppFeaturesRequest.__name__])
+    @console_ns.expect(console_ns.models[AgentAppFeaturesPayload.__name__])
     @console_ns.response(200, "Features updated successfully", console_ns.models[SimpleResultResponse.__name__])
     @console_ns.response(400, "Invalid configuration")
     @console_ns.response(404, "App not found")
@@ -73,7 +80,7 @@ class AgentAppFeatureConfigResource(Resource):
     @get_app_model(mode=[AppMode.AGENT])
     @with_current_user
     def post(self, current_user: Account, app_model: App):
-        args = AgentAppFeaturesRequest.model_validate(console_ns.payload)
+        args = AgentAppFeaturesPayload.model_validate(console_ns.payload or {})
 
         new_app_model_config = AgentAppFeatureConfigService.update_features(
             app_model=app_model,
@@ -83,4 +90,4 @@ class AgentAppFeatureConfigResource(Resource):
 
         app_model_config_was_updated.send(app_model, app_model_config=new_app_model_config)
 
-        return {"result": "success"}
+        return dump_response(SimpleResultResponse, {"result": "success"})

api/core/app/apps/agent_app/app_config_manager.py

@@ -91,7 +91,7 @@ class AgentAppConfigManager(BaseAppConfigManager):
                 "provider": model.model_provider,
                 "name": model.model,
                 "mode": "chat",
-                "completion_params": dict(model.model_settings or {}),
+                "completion_params": model.model_settings.model_dump(mode="json", exclude_none=True),
             }
         # The Agent Soul system prompt rides the EasyUI "simple" prompt slot; the
         # agent backend is the real prompt authority, this only feeds the chat

api/core/app/apps/agent_app/runtime_request_builder.py

@@ -112,7 +112,7 @@ class AgentAppRuntimeRequestBuilder:
                     model_provider=self._plugin_daemon_provider_name(agent_soul.model.model_provider),
                     model=agent_soul.model.model,
                     credentials=self._normalize_credentials(credentials),
-                    model_settings=agent_soul.model.model_settings,
+                    model_settings=agent_soul.model.model_settings.model_dump(mode="json", exclude_none=True),
                 ),
                 execution_context=DifyExecutionContextLayerConfig(
                     tenant_id=context.dify_context.tenant_id,

api/core/workflow/nodes/agent_v2/runtime_feature_manifest.py

@@ -31,7 +31,7 @@ RESERVED_AGENT_BACKEND_FEATURES = frozenset(
 def build_runtime_feature_manifest(agent_soul: AgentSoulConfig) -> dict[str, Any]:
     """Describe PRD capabilities that are persisted but not executed in phase 3."""
     warnings: list[dict[str, str]] = []
-    soul_dump = agent_soul.model_dump(mode="json")
+    soul_dump = agent_soul.model_dump(mode="json", exclude_none=True, exclude_defaults=True)
     for section in sorted(RESERVED_AGENT_BACKEND_FEATURES):
         value = _get_nested(soul_dump, section)
         has_value = bool(value)

api/core/workflow/nodes/agent_v2/runtime_request_builder.py

@@ -25,6 +25,7 @@ from models.agent_config_entities import (
     DeclaredOutputConfig,
     DeclaredOutputType,
     WorkflowNodeJobConfig,
+    WorkflowPreviousNodeOutputRef,
 )
 from models.agent_config_entities import (
     effective_declared_outputs as _effective_declared_outputs,
@@ -139,7 +140,7 @@ class WorkflowAgentRuntimeRequestBuilder:
                     model_provider=self._plugin_daemon_provider_name(agent_soul.model.model_provider),
                     model=agent_soul.model.model,
                     credentials=self._normalize_credentials(credentials),
-                    model_settings=agent_soul.model.model_settings,
+                    model_settings=agent_soul.model.model_settings.model_dump(mode="json", exclude_none=True),
                 ),
                 # The execution-context layer is now the only public protocol
                 # carrier for Dify tenant/user/run identifiers. ``user_id`` must
@@ -253,7 +254,7 @@ class WorkflowAgentRuntimeRequestBuilder:
     def _resolve_previous_node_outputs(
         self,
         variable_pool: VariablePoolReader,
-        refs: Sequence[Mapping[str, Any]],
+        refs: Sequence[WorkflowPreviousNodeOutputRef],
     ) -> list[dict[str, Any]]:
         resolved: list[dict[str, Any]] = []
         for ref in refs:
@@ -279,7 +280,7 @@ class WorkflowAgentRuntimeRequestBuilder:
         return resolved
 
     @staticmethod
-    def _selector_from_ref(ref: Mapping[str, Any]) -> list[str] | None:
+    def _selector_from_ref(ref: WorkflowPreviousNodeOutputRef) -> list[str] | None:
         for key in ("selector", "variable_selector", "value_selector"):
             value = ref.get(key)
             if isinstance(value, list) and all(isinstance(item, str) for item in value):

api/core/workflow/nodes/agent_v2/validators.py

@@ -9,7 +9,13 @@ from sqlalchemy.orm import Session
 
 from graphon.enums import BuiltinNodeTypes
 from models.agent import Agent, AgentConfigSnapshot, AgentStatus, WorkflowAgentNodeBinding
-from models.agent_config_entities import AgentSoulConfig, WorkflowNodeJobConfig
+from models.agent_config_entities import (
+    AgentFileRefConfig,
+    AgentHumanContactConfig,
+    AgentSoulConfig,
+    WorkflowNodeJobConfig,
+    WorkflowPreviousNodeOutputRef,
+)
 from models.model import UploadFile
 from models.workflow import Workflow
 
@@ -183,16 +189,15 @@ class WorkflowAgentNodeValidator:
         for human_ref in node_job.human_contacts:
             cls._validate_human_ref(binding=binding, human_ref=human_ref)
 
-        file_refs = node_job.metadata.get("file_refs")
+        file_refs = node_job.metadata.file_refs
         if isinstance(file_refs, list):
             for file_ref in file_refs:
-                if isinstance(file_ref, Mapping):
-                    cls._validate_file_ref(
-                        session=session,
-                        binding=binding,
-                        file_ref=file_ref,
-                        ref_context="metadata file ref",
-                    )
+                cls._validate_file_ref(
+                    session=session,
+                    binding=binding,
+                    file_ref=file_ref,
+                    ref_context="metadata file ref",
+                )
 
     @staticmethod
     def iter_agent_v2_nodes(graph_dict: Mapping[str, Any]) -> Iterator[tuple[str, Mapping[str, Any]]]:
@@ -210,7 +215,7 @@ class WorkflowAgentNodeValidator:
                 yield node_id, node_data
 
     @staticmethod
-    def selector_from_ref(ref: Mapping[str, Any]) -> list[str] | None:
+    def selector_from_ref(ref: WorkflowPreviousNodeOutputRef) -> list[str] | None:
         for key in ("selector", "variable_selector", "value_selector"):
             value = ref.get(key)
             if isinstance(value, list) and all(isinstance(item, str) for item in value):
@@ -237,7 +242,7 @@ class WorkflowAgentNodeValidator:
         binding: WorkflowAgentNodeBinding,
         node_job: WorkflowNodeJobConfig,
     ) -> None:
-        forbidden_paths = cls._find_locked_agent_soul_paths(node_job.metadata)
+        forbidden_paths = cls._find_locked_agent_soul_paths(node_job.metadata.model_dump(mode="python"))
         if forbidden_paths:
             raise WorkflowAgentNodeValidationError(
                 f"Workflow Agent node {binding.node_id} cannot override locked Agent Soul fields: "
@@ -261,7 +266,7 @@ class WorkflowAgentNodeValidator:
         cls,
         *,
         binding: WorkflowAgentNodeBinding,
-        human_ref: Mapping[str, Any],
+        human_ref: AgentHumanContactConfig,
     ) -> None:
         contact_id = human_ref.get("contact_id") or human_ref.get("human_id") or human_ref.get("id")
         if not isinstance(contact_id, str) or not contact_id:
@@ -306,7 +311,7 @@ class WorkflowAgentNodeValidator:
         *,
         session: Session,
         binding: WorkflowAgentNodeBinding,
-        file_ref: Mapping[str, Any],
+        file_ref: AgentFileRefConfig,
         ref_context: str,
     ) -> None:
         tenant_id = file_ref.get("tenant_id")

api/fields/agent_fields.py

@@ -1,4 +1,4 @@
-from typing import Any, Literal
+from typing import Literal
 
 from pydantic import Field
 
@@ -13,10 +13,15 @@ from models.agent import (
     WorkflowAgentBindingType,
 )
 from models.agent_config_entities import (
+    AgentCliToolConfig,
+    AgentHumanContactConfig,
+    AgentKnowledgeDatasetConfig,
+    AgentSkillRefConfig,
     AgentSoulConfig,
     DeclaredOutputConfig,
     DeclaredOutputType,
     WorkflowNodeJobConfig,
+    WorkflowPreviousNodeOutputRef,
 )
 from services.entities.agent_entities import (
     ComposerCandidateCapabilities,
@@ -167,18 +172,27 @@ class AgentComposerValidateResponse(ResponseModel):
     errors: list[str] = Field(default_factory=list)
 
 
+class AgentComposerDifyToolCandidateResponse(ResponseModel):
+    id: str | None = None
+    name: str | None = None
+    description: str | None = None
+    provider: str | None = None
+    provider_id: str | None = None
+    plugin_id: str | None = None
+
+
 class AgentComposerNodeJobCandidatesResponse(ResponseModel):
-    previous_node_outputs: list[dict[str, Any]] = Field(default_factory=list)
+    previous_node_outputs: list[WorkflowPreviousNodeOutputRef] = Field(default_factory=list)
     declare_output_types: list[DeclaredOutputType] = Field(default_factory=list)
-    human_contacts: list[dict[str, Any]] = Field(default_factory=list)
+    human_contacts: list[AgentHumanContactConfig] = Field(default_factory=list)
 
 
 class AgentComposerSoulCandidatesResponse(ResponseModel):
-    skills_files: list[dict[str, Any]] = Field(default_factory=list)
-    dify_tools: list[dict[str, Any]] = Field(default_factory=list)
-    cli_tools: list[dict[str, Any]] = Field(default_factory=list)
-    knowledge_datasets: list[dict[str, Any]] = Field(default_factory=list)
-    human_contacts: list[dict[str, Any]] = Field(default_factory=list)
+    skills_files: list[AgentSkillRefConfig] = Field(default_factory=list)
+    dify_tools: list[AgentComposerDifyToolCandidateResponse] = Field(default_factory=list)
+    cli_tools: list[AgentCliToolConfig] = Field(default_factory=list)
+    knowledge_datasets: list[AgentKnowledgeDatasetConfig] = Field(default_factory=list)
+    human_contacts: list[AgentHumanContactConfig] = Field(default_factory=list)
 
 
 class AgentComposerCandidatesResponse(ResponseModel):

api/models/agent_config_entities.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import re
 from enum import StrEnum
 from typing import Any, Final, Literal
@@ -40,14 +42,182 @@ class OutputErrorStrategy(StrEnum):
 # JSON-schema-friendly name pattern. Stage 4 §3.1 / §10.1.
 _OUTPUT_NAME_PATTERN: Final[re.Pattern[str]] = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
 
+JsonPrimitive = str | int | float | bool | None
+RuntimeParameterValue = JsonPrimitive | list[str] | list[int] | list[float] | list[bool]
+
+
+class AgentFlexibleConfig(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.model_dump(mode="python").get(key, default)
+
+    def items(self):
+        return self.model_dump(mode="python").items()
+
+    def __bool__(self) -> bool:
+        return bool(self.model_dump(mode="python", exclude_none=True, exclude_defaults=True))
+
+
+class AgentFileRefConfig(AgentFlexibleConfig):
+    id: str | None = Field(default=None, max_length=255)
+    name: str | None = Field(default=None, max_length=255)
+    type: str | None = Field(default=None, max_length=64)
+    transfer_method: str | None = Field(default=None, max_length=64)
+    url: str | None = None
+
+
+class AgentSkillRefConfig(AgentFlexibleConfig):
+    id: str | None = Field(default=None, max_length=255)
+    name: str | None = Field(default=None, max_length=255)
+    description: str | None = None
+    file_id: str | None = Field(default=None, max_length=255)
+    path: str | None = None
+
+
+class AgentCliToolConfig(AgentFlexibleConfig):
+    enabled: bool = True
+    name: str | None = Field(default=None, max_length=255)
+    description: str | None = None
+    command: str | None = None
+
+
+class AgentKnowledgeDatasetConfig(AgentFlexibleConfig):
+    id: str | None = Field(default=None, max_length=255)
+    name: str | None = Field(default=None, max_length=255)
+    description: str | None = None
+
+
+class AgentKnowledgeQueryConfig(AgentFlexibleConfig):
+    query: str | None = None
+    top_k: int | None = Field(default=None, ge=1)
+    score_threshold: float | None = Field(default=None, ge=0, le=1)
+    score_threshold_enabled: bool | None = None
+
+
+class AgentHumanContactConfig(AgentFlexibleConfig):
+    id: str | None = Field(default=None, max_length=255)
+    contact_id: str | None = Field(default=None, max_length=255)
+    human_id: str | None = Field(default=None, max_length=255)
+    name: str | None = Field(default=None, max_length=255)
+    email: str | None = Field(default=None, max_length=255)
+
+
+class AgentHumanToolConfig(AgentFlexibleConfig):
+    enabled: bool = True
+    name: str | None = Field(default=None, max_length=255)
+    description: str | None = None
+
+
+class AgentEnvVariableConfig(AgentFlexibleConfig):
+    name: str | None = Field(default=None, max_length=255)
+    type: str | None = Field(default=None, max_length=64)
+    value: RuntimeParameterValue = None
+    required: bool = False
+
+
+class AgentSecretRefConfig(AgentFlexibleConfig):
+    name: str | None = Field(default=None, max_length=255)
+    type: str | None = Field(default=None, max_length=64)
+    id: str | None = Field(default=None, max_length=255)
+    provider: str | None = Field(default=None, max_length=255)
+
+
+class AgentSandboxProviderConfig(AgentFlexibleConfig):
+    image: str | None = None
+    working_dir: str | None = None
+    env: list[AgentEnvVariableConfig] = Field(default_factory=list)
+
+
+class AgentMemoryArtifactConfig(AgentFlexibleConfig):
+    id: str | None = Field(default=None, max_length=255)
+    type: str | None = Field(default=None, max_length=64)
+    name: str | None = Field(default=None, max_length=255)
+    url: str | None = None
+
+
+class AgentModelResponseFormatConfig(AgentFlexibleConfig):
+    type: str | None = Field(default=None, max_length=64)
+
+
+class AgentSoulModelSettings(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    temperature: float | None = None
+    top_p: float | None = None
+    presence_penalty: float | None = None
+    frequency_penalty: float | None = None
+    max_tokens: int | None = None
+    stop: list[str] | None = None
+    response_format: AgentModelResponseFormatConfig | None = None
+
+
+class AgentFeatureToggleConfig(AgentFlexibleConfig):
+    enabled: bool = False
+
+
+class AgentTextToSpeechFeatureConfig(AgentFeatureToggleConfig):
+    language: str | None = None
+    voice: str | None = None
+    autoPlay: str | None = None
+
+
+class AgentSuggestedQuestionsAfterAnswerFeatureConfig(AgentFeatureToggleConfig):
+    prompt: str | None = None
+    model: AgentSoulModelConfig | None = None
+
+
+class AgentModerationIOConfig(AgentFlexibleConfig):
+    enabled: bool = False
+    preset_response: str | None = None
+
+
+class AgentModerationProviderConfig(AgentFlexibleConfig):
+    keywords: str | None = None
+    api_based_extension_id: str | None = None
+    inputs_config: AgentModerationIOConfig | None = None
+    outputs_config: AgentModerationIOConfig | None = None
+
+
+class AgentSensitiveWordAvoidanceFeatureConfig(AgentFeatureToggleConfig):
+    type: str | None = None
+    config: AgentModerationProviderConfig | None = None
+
+
+class AgentSoulAppFeaturesConfig(AgentFlexibleConfig):
+    opening_statement: str | None = None
+    suggested_questions: list[str] | None = None
+    suggested_questions_after_answer: AgentSuggestedQuestionsAfterAnswerFeatureConfig | None = None
+    speech_to_text: AgentFeatureToggleConfig | None = None
+    text_to_speech: AgentTextToSpeechFeatureConfig | None = None
+    retriever_resource: AgentFeatureToggleConfig | None = None
+    sensitive_word_avoidance: AgentSensitiveWordAvoidanceFeatureConfig | None = None
+
+
+class WorkflowPreviousNodeOutputRef(AgentFlexibleConfig):
+    selector: list[JsonPrimitive] | None = None
+    variable_selector: list[JsonPrimitive] | None = None
+    value_selector: list[JsonPrimitive] | None = None
+    node_id: str | None = Field(default=None, max_length=255)
+    output: str | None = Field(default=None, max_length=255)
+    name: str | None = Field(default=None, max_length=255)
+    variable: str | None = Field(default=None, max_length=255)
+    key: str | None = Field(default=None, max_length=255)
+
+
+class WorkflowNodeJobMetadata(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    file_refs: list[AgentFileRefConfig] | None = None
+
 
 class AgentSoulPromptConfig(BaseModel):
     system_prompt: str = ""
 
 
 class AgentSoulSkillsFilesConfig(BaseModel):
-    files: list[dict[str, Any]] = Field(default_factory=list)
-    skills: list[dict[str, Any]] = Field(default_factory=list)
+    files: list[AgentFileRefConfig] = Field(default_factory=list)
+    skills: list[AgentSkillRefConfig] = Field(default_factory=list)
 
 
 class AgentSoulDifyToolCredentialRef(BaseModel):
@@ -97,7 +267,7 @@ class AgentSoulDifyToolConfig(BaseModel):
     # (see :meth:`_validate_provider_and_credentials`).
     name: str | None = Field(default=None, max_length=255)
     description: str | None = None
-    runtime_parameters: dict[str, Any] = Field(default_factory=dict)
+    runtime_parameters: dict[str, RuntimeParameterValue] = Field(default_factory=dict)
 
     @model_validator(mode="before")
     @classmethod
@@ -118,7 +288,7 @@ class AgentSoulDifyToolConfig(BaseModel):
         return normalized
 
     @model_validator(mode="after")
-    def _validate_provider_and_credentials(self) -> "AgentSoulDifyToolConfig":
+    def _validate_provider_and_credentials(self) -> AgentSoulDifyToolConfig:
         if not self.provider_id and not (self.plugin_id and self.provider):
             raise ValueError("Dify tool requires provider_id or plugin_id + provider")
         if self.credential_type != "unauthorized" and (self.credential_ref is None or not self.credential_ref.id):
@@ -134,34 +304,34 @@ class AgentSoulDifyToolConfig(BaseModel):
 
 class AgentSoulToolsConfig(BaseModel):
     dify_tools: list[AgentSoulDifyToolConfig] = Field(default_factory=list)
-    cli_tools: list[dict[str, Any]] = Field(default_factory=list)
+    cli_tools: list[AgentCliToolConfig] = Field(default_factory=list)
 
 
 class AgentSoulKnowledgeConfig(BaseModel):
-    datasets: list[dict[str, Any]] = Field(default_factory=list)
+    datasets: list[AgentKnowledgeDatasetConfig] = Field(default_factory=list)
     query_mode: AgentKnowledgeQueryMode | None = None
-    query_config: dict[str, Any] = Field(default_factory=dict)
+    query_config: AgentKnowledgeQueryConfig = Field(default_factory=AgentKnowledgeQueryConfig)
 
 
 class AgentSoulHumanConfig(BaseModel):
-    contacts: list[dict[str, Any]] = Field(default_factory=list)
-    tools: list[dict[str, Any]] = Field(default_factory=list)
+    contacts: list[AgentHumanContactConfig] = Field(default_factory=list)
+    tools: list[AgentHumanToolConfig] = Field(default_factory=list)
 
 
 class AgentSoulEnvConfig(BaseModel):
-    variables: list[dict[str, Any]] = Field(default_factory=list)
-    secret_refs: list[dict[str, Any]] = Field(default_factory=list)
+    variables: list[AgentEnvVariableConfig] = Field(default_factory=list)
+    secret_refs: list[AgentSecretRefConfig] = Field(default_factory=list)
 
 
 class AgentSoulSandboxConfig(BaseModel):
     provider: str | None = None
-    config: dict[str, Any] = Field(default_factory=dict)
+    config: AgentSandboxProviderConfig = Field(default_factory=AgentSandboxProviderConfig)
 
 
 class AgentSoulMemoryConfig(BaseModel):
     scope: str | None = None
     budget: str | None = None
-    artifacts: list[dict[str, Any]] = Field(default_factory=list)
+    artifacts: list[AgentMemoryArtifactConfig] = Field(default_factory=list)
 
 
 class AgentSoulModelCredentialRef(BaseModel):
@@ -179,7 +349,7 @@ class AgentSoulModelConfig(BaseModel):
     model_provider: str = Field(min_length=1, max_length=255)
     model: str = Field(min_length=1, max_length=255)
     credential_ref: AgentSoulModelCredentialRef | None = None
-    model_settings: dict[str, Any] = Field(default_factory=dict)
+    model_settings: AgentSoulModelSettings = Field(default_factory=AgentSoulModelSettings)
 
 
 class AppVariableConfig(BaseModel):
@@ -202,9 +372,9 @@ class AgentSoulConfig(BaseModel):
     sandbox: AgentSoulSandboxConfig = Field(default_factory=AgentSoulSandboxConfig)
     memory: AgentSoulMemoryConfig = Field(default_factory=AgentSoulMemoryConfig)
     model: AgentSoulModelConfig | None = None
-    app_features: dict[str, Any] = Field(default_factory=dict)
+    app_features: AgentSoulAppFeaturesConfig = Field(default_factory=AgentSoulAppFeaturesConfig)
     app_variables: list[AppVariableConfig] = Field(default_factory=list)
-    misc_legacy: dict[str, Any] = Field(default_factory=dict)
+    misc_legacy: AgentSoulAppFeaturesConfig = Field(default_factory=AgentSoulAppFeaturesConfig)
 
 
 class DeclaredOutputFileConfig(BaseModel):
@@ -230,7 +400,7 @@ class DeclaredArrayItem(BaseModel):
     description: str | None = None
 
     @model_validator(mode="after")
-    def _reject_nested_array(self) -> "DeclaredArrayItem":
+    def _reject_nested_array(self) -> DeclaredArrayItem:
         if self.type == DeclaredOutputType.ARRAY:
             raise ValueError("nested arrays are not supported as array_item.type")
         return self
@@ -246,13 +416,13 @@ class DeclaredOutputCheckConfig(BaseModel):
 
     enabled: bool = False
     prompt: str | None = None
-    benchmark_file_ref: dict[str, Any] | None = None
+    benchmark_file_ref: AgentFileRefConfig | None = None
     # Reserved for stage 4.1: pick a different model than Agent Soul's for the check.
     # Stage 4 leaves this Optional and unused by FileOutputCheckExecutor.
-    model_ref: dict[str, Any] | None = None
+    model_ref: AgentSoulModelConfig | None = None
 
     @model_validator(mode="after")
-    def _require_prompt_and_benchmark_when_enabled(self) -> "DeclaredOutputCheckConfig":
+    def _require_prompt_and_benchmark_when_enabled(self) -> DeclaredOutputCheckConfig:
         if self.enabled:
             if not self.prompt or not self.prompt.strip():
                 raise ValueError("prompt is required when output check is enabled")
@@ -288,7 +458,7 @@ class DeclaredOutputFailureStrategy(BaseModel):
     default_value: Any = None
 
     @model_validator(mode="after")
-    def _require_default_value_when_default_strategy(self) -> "DeclaredOutputFailureStrategy":
+    def _require_default_value_when_default_strategy(self) -> DeclaredOutputFailureStrategy:
         if self.on_failure == OutputErrorStrategy.DEFAULT_VALUE and self.default_value is None:
             raise ValueError(
                 "default_value must be provided when on_failure=default_value; None is reserved for 'not set'."
@@ -326,7 +496,7 @@ class DeclaredOutputConfig(BaseModel):
         return value
 
     @model_validator(mode="after")
-    def _validate_shape(self) -> "DeclaredOutputConfig":
+    def _validate_shape(self) -> DeclaredOutputConfig:
         if not _OUTPUT_NAME_PATTERN.fullmatch(self.name):
             raise ValueError(
                 f"output name {self.name!r} must match {_OUTPUT_NAME_PATTERN.pattern} (JSON-schema-friendly identifier)"
@@ -427,7 +597,7 @@ class WorkflowNodeJobConfig(BaseModel):
     schema_version: int = 1
     mode: WorkflowNodeJobMode = WorkflowNodeJobMode.TELL_AGENT_WHAT_TO_DO
     workflow_prompt: str = ""
-    previous_node_output_refs: list[dict[str, Any]] = Field(default_factory=list)
+    previous_node_output_refs: list[WorkflowPreviousNodeOutputRef] = Field(default_factory=list)
     declared_outputs: list[DeclaredOutputConfig] = Field(default_factory=list)
-    human_contacts: list[dict[str, Any]] = Field(default_factory=list)
-    metadata: dict[str, Any] = Field(default_factory=dict)
+    human_contacts: list[AgentHumanContactConfig] = Field(default_factory=list)
+    metadata: WorkflowNodeJobMetadata = Field(default_factory=WorkflowNodeJobMetadata)

api/openapi/markdown/console-swagger.md

@@ -1072,7 +1072,7 @@ Update an Agent App's presentation features (opener, follow-up, citations, ...)
 
 | Name | Located in | Description | Required | Schema |
 | ---- | ---------- | ----------- | -------- | ------ |
-| payload | body |  | Yes | [AgentAppFeaturesRequest](#agentappfeaturesrequest) |
+| payload | body |  | Yes | [AgentAppFeaturesPayload](#agentappfeaturespayload) |
 | app_id | path | Application ID | Yes | string |
 
 ##### Responses
@@ -10769,7 +10769,7 @@ Get banner list
 | save_options | [ [ComposerSaveStrategy](#composersavestrategy) ] |  | Yes |
 | variant | string |  | Yes |
 
-#### AgentAppFeaturesRequest
+#### AgentAppFeaturesPayload
 
 Presentation features configurable on an Agent App.
 
@@ -10779,12 +10779,21 @@ default (the config form sends the full desired feature state on save).
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
 | opening_statement | string | Conversation opener shown before the first turn | No |
-| retriever_resource | object | Citations / attributions config, e.g. {'enabled': true} | No |
-| sensitive_word_avoidance | object | Content moderation config | No |
-| speech_to_text | object | Speech-to-text config | No |
+| retriever_resource | [AgentFeatureToggleConfig](#agentfeaturetoggleconfig) | Citations / attributions config, e.g. {'enabled': true} | No |
+| sensitive_word_avoidance | [AgentSensitiveWordAvoidanceFeatureConfig](#agentsensitivewordavoidancefeatureconfig) | Content moderation config | No |
+| speech_to_text | [AgentFeatureToggleConfig](#agentfeaturetoggleconfig) | Speech-to-text config | No |
 | suggested_questions | [ string ] | Preset questions shown alongside the opener | No |
-| suggested_questions_after_answer | object | Follow-up suggestions config, e.g. {'enabled': true} | No |
-| text_to_speech | object | Text-to-speech config | No |
+| suggested_questions_after_answer | [AgentSuggestedQuestionsAfterAnswerFeatureConfig](#agentsuggestedquestionsafteranswerfeatureconfig) | Follow-up suggestions config, e.g. {'enabled': true} | No |
+| text_to_speech | [AgentTextToSpeechFeatureConfig](#agenttexttospeechfeatureconfig) | Text-to-speech config | No |
+
+#### AgentCliToolConfig
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| command | string |  | No |
+| description | string |  | No |
+| enabled | boolean |  | No |
+| name | string |  | No |
 
 #### AgentComposerAgentResponse
 
@@ -10817,6 +10826,17 @@ default (the config form sends the full desired feature state on save).
 | capabilities | [ComposerCandidateCapabilities](#composercandidatecapabilities) |  | No |
 | variant | [ComposerVariant](#composervariant) |  | Yes |
 
+#### AgentComposerDifyToolCandidateResponse
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| description | string |  | No |
+| id | string |  | No |
+| name | string |  | No |
+| plugin_id | string |  | No |
+| provider | string |  | No |
+| provider_id | string |  | No |
+
 #### AgentComposerImpactBindingResponse
 
 | Name | Type | Description | Required |
@@ -10838,18 +10858,18 @@ default (the config form sends the full desired feature state on save).
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
 | declare_output_types | [ [DeclaredOutputType](#declaredoutputtype) ] |  | No |
-| human_contacts | [ object ] |  | No |
-| previous_node_outputs | [ object ] |  | No |
+| human_contacts | [ [AgentHumanContactConfig](#agenthumancontactconfig) ] |  | No |
+| previous_node_outputs | [ [WorkflowPreviousNodeOutputRef](#workflowpreviousnodeoutputref) ] |  | No |
 
 #### AgentComposerSoulCandidatesResponse
 
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
-| cli_tools | [ object ] |  | No |
-| dify_tools | [ object ] |  | No |
-| human_contacts | [ object ] |  | No |
-| knowledge_datasets | [ object ] |  | No |
-| skills_files | [ object ] |  | No |
+| cli_tools | [ [AgentCliToolConfig](#agentclitoolconfig) ] |  | No |
+| dify_tools | [ [AgentComposerDifyToolCandidateResponse](#agentcomposerdifytoolcandidateresponse) ] |  | No |
+| human_contacts | [ [AgentHumanContactConfig](#agenthumancontactconfig) ] |  | No |
+| knowledge_datasets | [ [AgentKnowledgeDatasetConfig](#agentknowledgedatasetconfig) ] |  | No |
+| skills_files | [ [AgentSkillRefConfig](#agentskillrefconfig) ] |  | No |
 
 #### AgentComposerSoulLockResponse
 
@@ -10920,6 +10940,49 @@ Audit operation recorded for Agent Soul version/revision changes.
 | version | integer |  | Yes |
 | version_note | string |  | No |
 
+#### AgentEnvVariableConfig
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| name | string |  | No |
+| required | boolean |  | No |
+| type | string |  | No |
+| value | string<br>integer<br>number<br>boolean<br>[ string ]<br>[ integer ]<br>[ number ]<br>[ boolean ] |  | No |
+
+#### AgentFeatureToggleConfig
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| enabled | boolean |  | No |
+
+#### AgentFileRefConfig
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| id | string |  | No |
+| name | string |  | No |
+| transfer_method | string |  | No |
+| type | string |  | No |
+| url | string |  | No |
+
+#### AgentHumanContactConfig
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| contact_id | string |  | No |
+| email | string |  | No |
+| human_id | string |  | No |
+| id | string |  | No |
+| name | string |  | No |
+
+#### AgentHumanToolConfig
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| description | string |  | No |
+| enabled | boolean |  | No |
+| name | string |  | No |
+
 #### AgentIconType
 
 Supported icon storage formats for Agent roster entries.
@@ -10993,6 +11056,23 @@ the current roster/workflow APIs scoped to Dify Agent.
 | ---- | ---- | ----------- | -------- |
 | AgentKind | string | Agent implementation family.  This leaves room for future non-Dify agent implementations while keeping the current roster/workflow APIs scoped to Dify Agent. |  |
 
+#### AgentKnowledgeDatasetConfig
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| description | string |  | No |
+| id | string |  | No |
+| name | string |  | No |
+
+#### AgentKnowledgeQueryConfig
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| query | string |  | No |
+| score_threshold | number |  | No |
+| score_threshold_enabled | boolean |  | No |
+| top_k | integer |  | No |
+
 #### AgentKnowledgeQueryMode
 
 | Name | Type | Description | Required |
@@ -11006,6 +11086,37 @@ the current roster/workflow APIs scoped to Dify Agent.
 | conversation_id | string | Conversation UUID | Yes |
 | message_id | string | Message UUID | Yes |
 
+#### AgentMemoryArtifactConfig
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| id | string |  | No |
+| name | string |  | No |
+| type | string |  | No |
+| url | string |  | No |
+
+#### AgentModelResponseFormatConfig
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| type | string |  | No |
+
+#### AgentModerationIOConfig
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| enabled | boolean |  | No |
+| preset_response | string |  | No |
+
+#### AgentModerationProviderConfig
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| api_based_extension_id | string |  | No |
+| inputs_config | [AgentModerationIOConfig](#agentmoderationioconfig) |  | No |
+| keywords | string |  | No |
+| outputs_config | [AgentModerationIOConfig](#agentmoderationioconfig) |  | No |
+
 #### AgentReferencingWorkflowResponse
 
 | Name | Type | Description | Required |
@@ -11058,6 +11169,14 @@ the current roster/workflow APIs scoped to Dify Agent.
 | workflow_id | string |  | No |
 | workflow_node_id | string |  | No |
 
+#### AgentSandboxProviderConfig
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| env | [ [AgentEnvVariableConfig](#agentenvvariableconfig) ] |  | No |
+| image | string |  | No |
+| working_dir | string |  | No |
+
 #### AgentScope
 
 Visibility and lifecycle scope of an Agent record.
@@ -11066,17 +11185,56 @@ Visibility and lifecycle scope of an Agent record.
 | ---- | ---- | ----------- | -------- |
 | AgentScope | string | Visibility and lifecycle scope of an Agent record. |  |
 
+#### AgentSecretRefConfig
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| id | string |  | No |
+| name | string |  | No |
+| provider | string |  | No |
+| type | string |  | No |
+
+#### AgentSensitiveWordAvoidanceFeatureConfig
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| config | [AgentModerationProviderConfig](#agentmoderationproviderconfig) |  | No |
+| enabled | boolean |  | No |
+| type | string |  | No |
+
+#### AgentSkillRefConfig
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| description | string |  | No |
+| file_id | string |  | No |
+| id | string |  | No |
+| name | string |  | No |
+| path | string |  | No |
+
+#### AgentSoulAppFeaturesConfig
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| opening_statement | string |  | No |
+| retriever_resource | [AgentFeatureToggleConfig](#agentfeaturetoggleconfig) |  | No |
+| sensitive_word_avoidance | [AgentSensitiveWordAvoidanceFeatureConfig](#agentsensitivewordavoidancefeatureconfig) |  | No |
+| speech_to_text | [AgentFeatureToggleConfig](#agentfeaturetoggleconfig) |  | No |
+| suggested_questions | [ string ] |  | No |
+| suggested_questions_after_answer | [AgentSuggestedQuestionsAfterAnswerFeatureConfig](#agentsuggestedquestionsafteranswerfeatureconfig) |  | No |
+| text_to_speech | [AgentTextToSpeechFeatureConfig](#agenttexttospeechfeatureconfig) |  | No |
+
 #### AgentSoulConfig
 
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
-| app_features | object |  | No |
+| app_features | [AgentSoulAppFeaturesConfig](#agentsoulappfeaturesconfig) |  | No |
 | app_variables | [ [AppVariableConfig](#appvariableconfig) ] |  | No |
 | env | [AgentSoulEnvConfig](#agentsoulenvconfig) |  | No |
 | human | [AgentSoulHumanConfig](#agentsoulhumanconfig) |  | No |
 | knowledge | [AgentSoulKnowledgeConfig](#agentsoulknowledgeconfig) |  | No |
 | memory | [AgentSoulMemoryConfig](#agentsoulmemoryconfig) |  | No |
-| misc_legacy | object |  | No |
+| misc_legacy | [AgentSoulAppFeaturesConfig](#agentsoulappfeaturesconfig) |  | No |
 | model | [AgentSoulModelConfig](#agentsoulmodelconfig) |  | No |
 | prompt | [AgentSoulPromptConfig](#agentsoulpromptconfig) |  | No |
 | sandbox | [AgentSoulSandboxConfig](#agentsoulsandboxconfig) |  | No |
@@ -11125,29 +11283,29 @@ old Agent tool payloads can be read while new payloads stay explicit.
 
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
-| secret_refs | [ object ] |  | No |
-| variables | [ object ] |  | No |
+| secret_refs | [ [AgentSecretRefConfig](#agentsecretrefconfig) ] |  | No |
+| variables | [ [AgentEnvVariableConfig](#agentenvvariableconfig) ] |  | No |
 
 #### AgentSoulHumanConfig
 
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
-| contacts | [ object ] |  | No |
-| tools | [ object ] |  | No |
+| contacts | [ [AgentHumanContactConfig](#agenthumancontactconfig) ] |  | No |
+| tools | [ [AgentHumanToolConfig](#agenthumantoolconfig) ] |  | No |
 
 #### AgentSoulKnowledgeConfig
 
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
-| datasets | [ object ] |  | No |
-| query_config | object |  | No |
+| datasets | [ [AgentKnowledgeDatasetConfig](#agentknowledgedatasetconfig) ] |  | No |
+| query_config | [AgentKnowledgeQueryConfig](#agentknowledgequeryconfig) |  | No |
 | query_mode | [AgentKnowledgeQueryMode](#agentknowledgequerymode) |  | No |
 
 #### AgentSoulMemoryConfig
 
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
-| artifacts | [ object ] |  | No |
+| artifacts | [ [AgentMemoryArtifactConfig](#agentmemoryartifactconfig) ] |  | No |
 | budget | string |  | No |
 | scope | string |  | No |
 
@@ -11160,7 +11318,7 @@ Stable model selection for Agent runtime without storing secret values.
 | credential_ref | [AgentSoulModelCredentialRef](#agentsoulmodelcredentialref) |  | No |
 | model | string |  | Yes |
 | model_provider | string |  | Yes |
-| model_settings | object |  | No |
+| model_settings | [AgentSoulModelSettings](#agentsoulmodelsettings) |  | No |
 | plugin_id | string |  | Yes |
 
 #### AgentSoulModelCredentialRef
@@ -11173,6 +11331,18 @@ Reference to model credentials resolved only at runtime.
 | provider | string |  | No |
 | type | string |  | Yes |
 
+#### AgentSoulModelSettings
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| frequency_penalty | number |  | No |
+| max_tokens | integer |  | No |
+| presence_penalty | number |  | No |
+| response_format | [AgentModelResponseFormatConfig](#agentmodelresponseformatconfig) |  | No |
+| stop | [ string ] |  | No |
+| temperature | number |  | No |
+| top_p | number |  | No |
+
 #### AgentSoulPromptConfig
 
 | Name | Type | Description | Required |
@@ -11183,21 +11353,21 @@ Reference to model credentials resolved only at runtime.
 
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
-| config | object |  | No |
+| config | [AgentSandboxProviderConfig](#agentsandboxproviderconfig) |  | No |
 | provider | string |  | No |
 
 #### AgentSoulSkillsFilesConfig
 
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
-| files | [ object ] |  | No |
-| skills | [ object ] |  | No |
+| files | [ [AgentFileRefConfig](#agentfilerefconfig) ] |  | No |
+| skills | [ [AgentSkillRefConfig](#agentskillrefconfig) ] |  | No |
 
 #### AgentSoulToolsConfig
 
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
-| cli_tools | [ object ] |  | No |
+| cli_tools | [ [AgentCliToolConfig](#agentclitoolconfig) ] |  | No |
 | dify_tools | [ [AgentSoulDifyToolConfig](#agentsouldifytoolconfig) ] |  | No |
 
 #### AgentSource
@@ -11216,6 +11386,23 @@ Soft lifecycle state for Agent records.
 | ---- | ---- | ----------- | -------- |
 | AgentStatus | string | Soft lifecycle state for Agent records. |  |
 
+#### AgentSuggestedQuestionsAfterAnswerFeatureConfig
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| enabled | boolean |  | No |
+| model | [AgentSoulModelConfig](#agentsoulmodelconfig) |  | No |
+| prompt | string |  | No |
+
+#### AgentTextToSpeechFeatureConfig
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| autoPlay | string |  | No |
+| enabled | boolean |  | No |
+| language | string |  | No |
+| voice | string |  | No |
+
 #### AgentThought
 
 | Name | Type | Description | Required |
@@ -12833,9 +13020,9 @@ Per PRD §OUTPUT 配置框, output check is **file-only** and optional. Stage 4
 
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
-| benchmark_file_ref | object |  | No |
+| benchmark_file_ref | [AgentFileRefConfig](#agentfilerefconfig) |  | No |
 | enabled | boolean |  | No |
-| model_ref | object |  | No |
+| model_ref | [AgentSoulModelConfig](#agentsoulmodelconfig) |  | No |
 | prompt | string |  | No |
 
 #### DeclaredOutputConfig
@@ -16262,13 +16449,19 @@ How a workflow node is bound to an Agent.
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
 | declared_outputs | [ [DeclaredOutputConfig](#declaredoutputconfig) ] |  | No |
-| human_contacts | [ object ] |  | No |
-| metadata | object |  | No |
+| human_contacts | [ [AgentHumanContactConfig](#agenthumancontactconfig) ] |  | No |
+| metadata | [WorkflowNodeJobMetadata](#workflownodejobmetadata) |  | No |
 | mode | [WorkflowNodeJobMode](#workflownodejobmode) |  | No |
-| previous_node_output_refs | [ object ] |  | No |
+| previous_node_output_refs | [ [WorkflowPreviousNodeOutputRef](#workflowpreviousnodeoutputref) ] |  | No |
 | schema_version | integer |  | No |
 | workflow_prompt | string |  | No |
 
+#### WorkflowNodeJobMetadata
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| file_refs | [ [AgentFileRefConfig](#agentfilerefconfig) ] |  | No |
+
 #### WorkflowNodeJobMode
 
 | Name | Type | Description | Required |
@@ -16328,6 +16521,19 @@ How a workflow node is bound to an Agent.
 | paused_at | string |  | No |
 | paused_nodes | [ [PausedNodeResponse](#pausednoderesponse) ] |  | Yes |
 
+#### WorkflowPreviousNodeOutputRef
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| key | string |  | No |
+| name | string |  | No |
+| node_id | string |  | No |
+| output | string |  | No |
+| selector | [  ] |  | No |
+| value_selector | [  ] |  | No |
+| variable | string |  | No |
+| variable_selector | [  ] |  | No |
+
 #### WorkflowResponse
 
 | Name | Type | Description | Required |