fix: resolve remaining CI failures for style checks and unit tests

- Add model_features property and build_execution_context method to
  AgentAppRunner to fix mypy attr-defined errors
- Export WorkflowComment, WorkflowCommentReply, WorkflowCommentMention
  from models/__init__.py to fix import errors
- Add NestedNodeGraphRequest, NestedNodeGraphResponse,
  NestedNodeParameterSchema to services/workflow/entities.py
- Update test_agent_chat_app_runner: tests for invalid LLM mode and
  invalid strategy now reflect unified AgentAppRunner behavior
  (no longer raises ValueError for these cases)

Made-with: Cursor

.github/dependabot.yml

@@ -1,106 +1,6 @@
 version: 2
 
 updates:
-  - package-ecosystem: "pip"
-    directory: "/api"
-    open-pull-requests-limit: 10
-    schedule:
-      interval: "weekly"
-    groups:
-      flask:
-        patterns:
-          - "flask"
-          - "flask-*"
-          - "werkzeug"
-          - "gunicorn"
-      google:
-        patterns:
-          - "google-*"
-          - "googleapis-*"
-      opentelemetry:
-        patterns:
-          - "opentelemetry-*"
-      pydantic:
-        patterns:
-          - "pydantic"
-          - "pydantic-*"
-      llm:
-        patterns:
-          - "langfuse"
-          - "langsmith"
-          - "litellm"
-          - "mlflow*"
-          - "opik"
-          - "weave*"
-          - "arize*"
-          - "tiktoken"
-          - "transformers"
-      database:
-        patterns:
-          - "sqlalchemy"
-          - "psycopg2*"
-          - "psycogreen"
-          - "redis*"
-          - "alembic*"
-      storage:
-        patterns:
-          - "boto3*"
-          - "botocore*"
-          - "azure-*"
-          - "bce-*"
-          - "cos-python-*"
-          - "esdk-obs-*"
-          - "google-cloud-storage"
-          - "opendal"
-          - "oss2"
-          - "supabase*"
-          - "tos*"
-      vdb:
-        patterns:
-          - "alibabacloud*"
-          - "chromadb"
-          - "clickhouse-*"
-          - "clickzetta-*"
-          - "couchbase"
-          - "elasticsearch"
-          - "opensearch-py"
-          - "oracledb"
-          - "pgvect*"
-          - "pymilvus"
-          - "pymochow"
-          - "pyobvector"
-          - "qdrant-client"
-          - "intersystems-*"
-          - "tablestore"
-          - "tcvectordb"
-          - "tidb-vector"
-          - "upstash-*"
-          - "volcengine-*"
-          - "weaviate-*"
-          - "xinference-*"
-          - "mo-vector"
-          - "mysql-connector-*"
-      dev:
-        patterns:
-          - "coverage"
-          - "dotenv-linter"
-          - "faker"
-          - "lxml-stubs"
-          - "basedpyright"
-          - "ruff"
-          - "pytest*"
-          - "types-*"
-          - "boto3-stubs"
-          - "hypothesis"
-          - "pandas-stubs"
-          - "scipy-stubs"
-          - "import-linter"
-          - "celery-types"
-          - "mypy*"
-          - "pyrefly"
-      python-packages:
-        patterns:
-          - "*"
   - package-ecosystem: "uv"
     directory: "/api"
     open-pull-requests-limit: 10

.github/pull_request_template.md

@@ -18,7 +18,7 @@
 ## Checklist
 
 - [ ] This change requires a documentation update, included: [Dify Document](https://github.com/langgenius/dify-docs)
-- [x] I understand that this PR may be closed in case there was no previous discussion or issues. (This doesn't apply to typos!)
-- [x] I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
-- [x] I've updated the documentation accordingly.
-- [x] I ran `make lint` and `make type-check` (backend) and `cd web && pnpm exec vp staged` (frontend) to appease the lint gods
+- [ ] I understand that this PR may be closed in case there was no previous discussion or issues. (This doesn't apply to typos!)
+- [ ] I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
+- [ ] I've updated the documentation accordingly.
+- [ ] I ran `make lint && make type-check` (backend) and `cd web && pnpm exec vp staged` (frontend) to appease the lint gods

.github/workflows/stale.yml

@@ -23,8 +23,8 @@ jobs:
           days-before-issue-stale: 15
           days-before-issue-close: 3
           repo-token: ${{ secrets.GITHUB_TOKEN }}
-          stale-issue-message: "Close due to it's no longer active, if you have any questions, you can reopen it."
-          stale-pr-message: "Close due to it's no longer active, if you have any questions, you can reopen it."
+          stale-issue-message: "Closed due to inactivity. If you have any questions, you can reopen it."
+          stale-pr-message: "Closed due to inactivity. If you have any questions, you can reopen it."
           stale-issue-label: 'no-issue-activity'
           stale-pr-label: 'no-pr-activity'
-          any-of-labels: 'duplicate,question,invalid,wontfix,no-issue-activity,no-pr-activity,enhancement,cant-reproduce,help-wanted'
+          any-of-labels: '🌚 invalid,🙋‍♂️ question,wont-fix,no-issue-activity,no-pr-activity,💪 enhancement,🤔 cant-reproduce,🙏 help wanted'

api/configs/feature/__init__.py

@@ -287,6 +287,27 @@ class MarketplaceConfig(BaseSettings):
     )
 
 
+class CreatorsPlatformConfig(BaseSettings):
+    """
+    Configuration for creators platform
+    """
+
+    CREATORS_PLATFORM_FEATURES_ENABLED: bool = Field(
+        description="Enable or disable creators platform features",
+        default=True,
+    )
+
+    CREATORS_PLATFORM_API_URL: HttpUrl = Field(
+        description="Creators Platform API URL",
+        default=HttpUrl("https://creators.dify.ai"),
+    )
+
+    CREATORS_PLATFORM_OAUTH_CLIENT_ID: str = Field(
+        description="OAuth client_id for the Creators Platform app registered in Dify",
+        default="",
+    )
+
+
 class EndpointConfig(BaseSettings):
     """
     Configuration for various application endpoints and URLs
@@ -341,6 +362,15 @@ class FileAccessConfig(BaseSettings):
         default="",
     )
 
+    FILES_API_URL: str = Field(
+        description="Base URL for storage file ticket API endpoints."
+        " Used by sandbox containers (internal or external like e2b) that need"
+        " an absolute, routable address to upload/download files via the API."
+        " For all-in-one Docker deployments, set to http://localhost."
+        " For public sandbox environments, set to a public domain or IP.",
+        default="",
+    )
+
     FILES_ACCESS_TIMEOUT: int = Field(
         description="Expiration time in seconds for file access URLs",
         default=300,
@@ -1274,6 +1304,52 @@ class PositionConfig(BaseSettings):
         return {item.strip() for item in self.POSITION_TOOL_EXCLUDES.split(",") if item.strip() != ""}
 
 
+class CollaborationConfig(BaseSettings):
+    ENABLE_COLLABORATION_MODE: bool = Field(
+        description="Whether to enable collaboration mode features across the workspace",
+        default=False,
+    )
+
+
+class SandboxExpiredRecordsCleanConfig(BaseSettings):
+    SANDBOX_EXPIRED_RECORDS_CLEAN_GRACEFUL_PERIOD: NonNegativeInt = Field(
+        description="Graceful period in days for sandbox records clean after subscription expiration",
+        default=21,
+    )
+    SANDBOX_EXPIRED_RECORDS_CLEAN_BATCH_SIZE: PositiveInt = Field(
+        description="Maximum number of records to process in each batch",
+        default=1000,
+    )
+    SANDBOX_EXPIRED_RECORDS_CLEAN_BATCH_MAX_INTERVAL: PositiveInt = Field(
+        description="Maximum interval in milliseconds between batches",
+        default=200,
+    )
+    SANDBOX_EXPIRED_RECORDS_RETENTION_DAYS: PositiveInt = Field(
+        description="Retention days for sandbox expired workflow_run records and message records",
+        default=30,
+    )
+    SANDBOX_EXPIRED_RECORDS_CLEAN_TASK_LOCK_TTL: PositiveInt = Field(
+        description="Lock TTL for sandbox expired records clean task in seconds",
+        default=90000,
+    )
+
+
+class AgentV2UpgradeConfig(BaseSettings):
+    """Feature flags for transparent Agent V2 upgrade."""
+
+    AGENT_V2_TRANSPARENT_UPGRADE: bool = Field(
+        description="Transparently run old apps (chat/completion/agent-chat) through the Agent V2 workflow engine. "
+        "When enabled, old apps synthesize a virtual workflow at runtime instead of using legacy runners.",
+        default=False,
+    )
+
+    AGENT_V2_REPLACES_LLM: bool = Field(
+        description="Transparently replace LLM nodes in workflows with Agent V2 nodes at runtime. "
+        "LLMNodeData is remapped to AgentV2NodeData with tools=[] (identical behavior).",
+        default=False,
+    )
+
+
 class LoginConfig(BaseSettings):
     ENABLE_EMAIL_CODE_LOGIN: bool = Field(
         description="whether to enable email code login",
@@ -1343,29 +1419,6 @@ class TenantIsolatedTaskQueueConfig(BaseSettings):
     )
 
 
-class SandboxExpiredRecordsCleanConfig(BaseSettings):
-    SANDBOX_EXPIRED_RECORDS_CLEAN_GRACEFUL_PERIOD: NonNegativeInt = Field(
-        description="Graceful period in days for sandbox records clean after subscription expiration",
-        default=21,
-    )
-    SANDBOX_EXPIRED_RECORDS_CLEAN_BATCH_SIZE: PositiveInt = Field(
-        description="Maximum number of records to process in each batch",
-        default=1000,
-    )
-    SANDBOX_EXPIRED_RECORDS_CLEAN_BATCH_MAX_INTERVAL: PositiveInt = Field(
-        description="Maximum interval in milliseconds between batches",
-        default=200,
-    )
-    SANDBOX_EXPIRED_RECORDS_RETENTION_DAYS: PositiveInt = Field(
-        description="Retention days for sandbox expired workflow_run records and message records",
-        default=30,
-    )
-    SANDBOX_EXPIRED_RECORDS_CLEAN_TASK_LOCK_TTL: PositiveInt = Field(
-        description="Lock TTL for sandbox expired records clean task in seconds",
-        default=90000,
-    )
-
-
 class FeatureConfig(
     # place the configs in alphabet order
     AppExecutionConfig,
@@ -1376,6 +1429,7 @@ class FeatureConfig(
     AsyncWorkflowConfig,
     PluginConfig,
     MarketplaceConfig,
+    CreatorsPlatformConfig,
     DataSetConfig,
     EndpointConfig,
     FileAccessConfig,
@@ -1391,7 +1445,6 @@ class FeatureConfig(
     PositionConfig,
     RagEtlConfig,
     RepositoryConfig,
-    SandboxExpiredRecordsCleanConfig,
     SecurityConfig,
     TenantIsolatedTaskQueueConfig,
     ToolConfig,
@@ -1399,6 +1452,9 @@ class FeatureConfig(
     WorkflowConfig,
     WorkflowNodeExecutionConfig,
     WorkspaceConfig,
+    CollaborationConfig,
+    AgentV2UpgradeConfig,
+    SandboxExpiredRecordsCleanConfig,
     LoginConfig,
     AccountConfig,
     SwaggerUIConfig,

api/constants/model_template.py

@@ -81,4 +81,20 @@ default_app_templates: Mapping[AppMode, Mapping] = {
             },
         },
     },
+    # agent default mode (new agent backed by single-node workflow)
+    AppMode.AGENT: {
+        "app": {
+            "mode": AppMode.AGENT,
+            "enable_site": True,
+            "enable_api": True,
+        },
+        "model_config": {
+            "model": {
+                "provider": "openai",
+                "name": "gpt-4o",
+                "mode": "chat",
+                "completion_params": {},
+            },
+        },
+    },
 }

api/controllers/common/controller_schemas.py

@@ -1,4 +1,5 @@
 from typing import Any, Literal
+from uuid import UUID
 
 from pydantic import BaseModel, Field, model_validator
 
@@ -23,9 +24,9 @@ class ConversationRenamePayload(BaseModel):
 
 
 class MessageListQuery(BaseModel):
-    conversation_id: UUIDStrOrEmpty
-    first_id: UUIDStrOrEmpty | None = None
-    limit: int = Field(default=20, ge=1, le=100)
+    conversation_id: UUIDStrOrEmpty = Field(description="Conversation UUID")
+    first_id: UUIDStrOrEmpty | None = Field(default=None, description="First message ID for pagination")
+    limit: int = Field(default=20, ge=1, le=100, description="Number of messages to return (1-100)")
 
 
 class MessageFeedbackPayload(BaseModel):
@@ -69,11 +70,35 @@ class WorkflowUpdatePayload(BaseModel):
     marked_comment: str | None = Field(default=None, max_length=100)
 
 
+# --- Dataset schemas ---
+
+
+DOCUMENT_BATCH_DOWNLOAD_ZIP_MAX_DOCS = 100
+
+
+class ChildChunkCreatePayload(BaseModel):
+    content: str
+
+
+class ChildChunkUpdatePayload(BaseModel):
+    content: str
+
+
+class DocumentBatchDownloadZipPayload(BaseModel):
+    """Request payload for bulk downloading documents as a zip archive."""
+
+    document_ids: list[UUID] = Field(..., min_length=1, max_length=DOCUMENT_BATCH_DOWNLOAD_ZIP_MAX_DOCS)
+
+
+class MetadataUpdatePayload(BaseModel):
+    name: str
+
+
 # --- Audio schemas ---
 
 
 class TextToAudioPayload(BaseModel):
-    message_id: str | None = None
-    voice: str | None = None
-    text: str | None = None
-    streaming: bool | None = None
+    message_id: str | None = Field(default=None, description="Message ID")
+    voice: str | None = Field(default=None, description="Voice to use for TTS")
+    text: str | None = Field(default=None, description="Text to convert to audio")
+    streaming: bool | None = Field(default=None, description="Enable streaming response")

api/controllers/console/apikey.py

@@ -1,12 +1,16 @@
+from datetime import datetime
+
 import flask_restx
-from flask_restx import Resource, fields, marshal_with
+from flask_restx import Resource
 from flask_restx._http import HTTPStatus
+from pydantic import field_validator
 from sqlalchemy import delete, func, select
 from sqlalchemy.orm import sessionmaker
 from werkzeug.exceptions import Forbidden
 
+from controllers.common.schema import register_schema_models
 from extensions.ext_database import db
-from libs.helper import TimestampField
+from fields.base import ResponseModel
 from libs.login import current_account_with_tenant, login_required
 from models.dataset import Dataset
 from models.enums import ApiTokenType
@@ -16,21 +20,31 @@ from services.api_token_service import ApiTokenCache
 from . import console_ns
 from .wraps import account_initialization_required, edit_permission_required, setup_required
 
-api_key_fields = {
-    "id": fields.String,
-    "type": fields.String,
-    "token": fields.String,
-    "last_used_at": TimestampField,
-    "created_at": TimestampField,
-}
 
-api_key_item_model = console_ns.model("ApiKeyItem", api_key_fields)
+def _to_timestamp(value: datetime | int | None) -> int | None:
+    if isinstance(value, datetime):
+        return int(value.timestamp())
+    return value
 
-api_key_list = {"data": fields.List(fields.Nested(api_key_item_model), attribute="items")}
 
-api_key_list_model = console_ns.model(
-    "ApiKeyList", {"data": fields.List(fields.Nested(api_key_item_model), attribute="items")}
-)
+class ApiKeyItem(ResponseModel):
+    id: str
+    type: str
+    token: str
+    last_used_at: int | None = None
+    created_at: int | None = None
+
+    @field_validator("last_used_at", "created_at", mode="before")
+    @classmethod
+    def _normalize_timestamp(cls, value: datetime | int | None) -> int | None:
+        return _to_timestamp(value)
+
+
+class ApiKeyList(ResponseModel):
+    data: list[ApiKeyItem]
+
+
+register_schema_models(console_ns, ApiKeyItem, ApiKeyList)
 
 
 def _get_resource(resource_id, tenant_id, resource_model):
@@ -54,7 +68,6 @@ class BaseApiKeyListResource(Resource):
     token_prefix: str | None = None
     max_keys = 10
 
-    @marshal_with(api_key_list_model)
     def get(self, resource_id):
         assert self.resource_id_field is not None, "resource_id_field must be set"
         resource_id = str(resource_id)
@@ -66,9 +79,8 @@ class BaseApiKeyListResource(Resource):
                 ApiToken.type == self.resource_type, getattr(ApiToken, self.resource_id_field) == resource_id
             )
         ).all()
-        return {"items": keys}
+        return ApiKeyList.model_validate({"data": keys}, from_attributes=True).model_dump(mode="json")
 
-    @marshal_with(api_key_item_model)
     @edit_permission_required
     def post(self, resource_id):
         assert self.resource_id_field is not None, "resource_id_field must be set"
@@ -100,7 +112,7 @@ class BaseApiKeyListResource(Resource):
         api_token.type = self.resource_type
         db.session.add(api_token)
         db.session.commit()
-        return api_token, 201
+        return ApiKeyItem.model_validate(api_token, from_attributes=True).model_dump(mode="json"), 201
 
 
 class BaseApiKeyResource(Resource):
@@ -147,7 +159,7 @@ class AppApiKeyListResource(BaseApiKeyListResource):
     @console_ns.doc("get_app_api_keys")
     @console_ns.doc(description="Get all API keys for an app")
     @console_ns.doc(params={"resource_id": "App ID"})
-    @console_ns.response(200, "Success", api_key_list_model)
+    @console_ns.response(200, "API keys retrieved successfully", console_ns.models[ApiKeyList.__name__])
     def get(self, resource_id):  # type: ignore
         """Get all API keys for an app"""
         return super().get(resource_id)
@@ -155,7 +167,7 @@ class AppApiKeyListResource(BaseApiKeyListResource):
     @console_ns.doc("create_app_api_key")
     @console_ns.doc(description="Create a new API key for an app")
     @console_ns.doc(params={"resource_id": "App ID"})
-    @console_ns.response(201, "API key created successfully", api_key_item_model)
+    @console_ns.response(201, "API key created successfully", console_ns.models[ApiKeyItem.__name__])
     @console_ns.response(400, "Maximum keys exceeded")
     def post(self, resource_id):  # type: ignore
         """Create a new API key for an app"""
@@ -187,7 +199,7 @@ class DatasetApiKeyListResource(BaseApiKeyListResource):
     @console_ns.doc("get_dataset_api_keys")
     @console_ns.doc(description="Get all API keys for a dataset")
     @console_ns.doc(params={"resource_id": "Dataset ID"})
-    @console_ns.response(200, "Success", api_key_list_model)
+    @console_ns.response(200, "API keys retrieved successfully", console_ns.models[ApiKeyList.__name__])
     def get(self, resource_id):  # type: ignore
         """Get all API keys for a dataset"""
         return super().get(resource_id)
@@ -195,7 +207,7 @@ class DatasetApiKeyListResource(BaseApiKeyListResource):
     @console_ns.doc("create_dataset_api_key")
     @console_ns.doc(description="Create a new API key for a dataset")
     @console_ns.doc(params={"resource_id": "Dataset ID"})
-    @console_ns.response(201, "API key created successfully", api_key_item_model)
+    @console_ns.response(201, "API key created successfully", console_ns.models[ApiKeyItem.__name__])
     @console_ns.response(400, "Maximum keys exceeded")
     def post(self, resource_id):  # type: ignore
         """Create a new API key for a dataset"""

api/controllers/console/app/annotation.py

@@ -25,7 +25,13 @@ from fields.annotation_fields import (
 )
 from libs.helper import uuid_value
 from libs.login import login_required
-from services.annotation_service import AppAnnotationService
+from services.annotation_service import (
+    AppAnnotationService,
+    EnableAnnotationArgs,
+    UpdateAnnotationArgs,
+    UpdateAnnotationSettingArgs,
+    UpsertAnnotationArgs,
+)
 
 DEFAULT_REF_TEMPLATE_SWAGGER_2_0 = "#/definitions/{model}"
 
@@ -120,7 +126,12 @@ class AnnotationReplyActionApi(Resource):
         args = AnnotationReplyPayload.model_validate(console_ns.payload)
         match action:
             case "enable":
-                result = AppAnnotationService.enable_app_annotation(args.model_dump(), app_id)
+                enable_args: EnableAnnotationArgs = {
+                    "score_threshold": args.score_threshold,
+                    "embedding_provider_name": args.embedding_provider_name,
+                    "embedding_model_name": args.embedding_model_name,
+                }
+                result = AppAnnotationService.enable_app_annotation(enable_args, app_id)
             case "disable":
                 result = AppAnnotationService.disable_app_annotation(app_id)
         return result, 200
@@ -161,7 +172,8 @@ class AppAnnotationSettingUpdateApi(Resource):
 
         args = AnnotationSettingUpdatePayload.model_validate(console_ns.payload)
 
-        result = AppAnnotationService.update_app_annotation_setting(app_id, annotation_setting_id, args.model_dump())
+        setting_args: UpdateAnnotationSettingArgs = {"score_threshold": args.score_threshold}
+        result = AppAnnotationService.update_app_annotation_setting(app_id, annotation_setting_id, setting_args)
         return result, 200
 
 
@@ -237,8 +249,16 @@ class AnnotationApi(Resource):
     def post(self, app_id):
         app_id = str(app_id)
         args = CreateAnnotationPayload.model_validate(console_ns.payload)
-        data = args.model_dump(exclude_none=True)
-        annotation = AppAnnotationService.up_insert_app_annotation_from_message(data, app_id)
+        upsert_args: UpsertAnnotationArgs = {}
+        if args.answer is not None:
+            upsert_args["answer"] = args.answer
+        if args.content is not None:
+            upsert_args["content"] = args.content
+        if args.message_id is not None:
+            upsert_args["message_id"] = args.message_id
+        if args.question is not None:
+            upsert_args["question"] = args.question
+        annotation = AppAnnotationService.up_insert_app_annotation_from_message(upsert_args, app_id)
         return Annotation.model_validate(annotation, from_attributes=True).model_dump(mode="json")
 
     @setup_required
@@ -315,9 +335,12 @@ class AnnotationUpdateDeleteApi(Resource):
         app_id = str(app_id)
         annotation_id = str(annotation_id)
         args = UpdateAnnotationPayload.model_validate(console_ns.payload)
-        annotation = AppAnnotationService.update_app_annotation_directly(
-            args.model_dump(exclude_none=True), app_id, annotation_id
-        )
+        update_args: UpdateAnnotationArgs = {}
+        if args.answer is not None:
+            update_args["answer"] = args.answer
+        if args.question is not None:
+            update_args["question"] = args.question
+        annotation = AppAnnotationService.update_app_annotation_directly(update_args, app_id, annotation_id)
         return Annotation.model_validate(annotation, from_attributes=True).model_dump(mode="json")
 
     @setup_required

api/controllers/console/app/app.py

@@ -52,7 +52,7 @@ from services.entities.knowledge_entities.knowledge_entities import (
 )
 from services.feature_service import FeatureService
 
-ALLOW_CREATE_APP_MODES = ["chat", "agent-chat", "advanced-chat", "workflow", "completion"]
+ALLOW_CREATE_APP_MODES = ["chat", "agent-chat", "advanced-chat", "workflow", "completion", "agent"]
 
 register_enum_models(console_ns, IconType)
 
@@ -62,7 +62,7 @@ _logger = logging.getLogger(__name__)
 class AppListQuery(BaseModel):
     page: int = Field(default=1, ge=1, le=99999, description="Page number (1-99999)")
     limit: int = Field(default=20, ge=1, le=100, description="Page size (1-100)")
-    mode: Literal["completion", "chat", "advanced-chat", "workflow", "agent-chat", "channel", "all"] = Field(
+    mode: Literal["completion", "chat", "advanced-chat", "workflow", "agent-chat", "agent", "channel", "all"] = Field(
         default="all", description="App mode filter"
     )
     name: str | None = Field(default=None, description="Filter by app name")
@@ -94,7 +94,9 @@ class AppListQuery(BaseModel):
 class CreateAppPayload(BaseModel):
     name: str = Field(..., min_length=1, description="App name")
     description: str | None = Field(default=None, description="App description (max 400 chars)", max_length=400)
-    mode: Literal["chat", "agent-chat", "advanced-chat", "workflow", "completion"] = Field(..., description="App mode")
+    mode: Literal["chat", "agent-chat", "advanced-chat", "workflow", "completion", "agent"] = Field(
+        ..., description="App mode"
+    )
     icon_type: IconType | None = Field(default=None, description="Icon type")
     icon: str | None = Field(default=None, description="Icon")
     icon_background: str | None = Field(default=None, description="Icon background color")

api/controllers/console/app/app_import.py

@@ -1,7 +1,8 @@
-from flask_restx import Resource, fields, marshal_with
+from flask_restx import Resource
 from pydantic import BaseModel, Field
 from sqlalchemy.orm import sessionmaker
 
+from controllers.common.schema import register_schema_models
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
     account_initialization_required,
@@ -10,35 +11,15 @@ from controllers.console.wraps import (
     setup_required,
 )
 from extensions.ext_database import db
-from fields.app_fields import (
-    app_import_check_dependencies_fields,
-    app_import_fields,
-    leaked_dependency_fields,
-)
 from libs.login import current_account_with_tenant, login_required
 from models.model import App
-from services.app_dsl_service import AppDslService
+from services.app_dsl_service import AppDslService, Import
 from services.enterprise.enterprise_service import EnterpriseService
-from services.entities.dsl_entities import ImportStatus
+from services.entities.dsl_entities import CheckDependenciesResult, ImportStatus
 from services.feature_service import FeatureService
 
 from .. import console_ns
 
-# Register models for flask_restx to avoid dict type issues in Swagger
-# Register base model first
-leaked_dependency_model = console_ns.model("LeakedDependency", leaked_dependency_fields)
-
-app_import_model = console_ns.model("AppImport", app_import_fields)
-
-# For nested models, need to replace nested dict with registered model
-app_import_check_dependencies_fields_copy = app_import_check_dependencies_fields.copy()
-app_import_check_dependencies_fields_copy["leaked_dependencies"] = fields.List(fields.Nested(leaked_dependency_model))
-app_import_check_dependencies_model = console_ns.model(
-    "AppImportCheckDependencies", app_import_check_dependencies_fields_copy
-)
-
-DEFAULT_REF_TEMPLATE_SWAGGER_2_0 = "#/definitions/{model}"
-
 
 class AppImportPayload(BaseModel):
     mode: str = Field(..., description="Import mode")
@@ -52,18 +33,18 @@ class AppImportPayload(BaseModel):
     app_id: str | None = Field(None)
 
 
-console_ns.schema_model(
-    AppImportPayload.__name__, AppImportPayload.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0)
-)
+register_schema_models(console_ns, AppImportPayload, Import, CheckDependenciesResult)
 
 
 @console_ns.route("/apps/imports")
 class AppImportApi(Resource):
     @console_ns.expect(console_ns.models[AppImportPayload.__name__])
+    @console_ns.response(200, "Import completed", console_ns.models[Import.__name__])
+    @console_ns.response(202, "Import pending confirmation", console_ns.models[Import.__name__])
+    @console_ns.response(400, "Import failed", console_ns.models[Import.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    @marshal_with(app_import_model)
     @cloud_edition_billing_resource_check("apps")
     @edit_permission_required
     def post(self):
@@ -104,10 +85,11 @@ class AppImportApi(Resource):
 
 @console_ns.route("/apps/imports/<string:import_id>/confirm")
 class AppImportConfirmApi(Resource):
+    @console_ns.response(200, "Import confirmed", console_ns.models[Import.__name__])
+    @console_ns.response(400, "Import failed", console_ns.models[Import.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    @marshal_with(app_import_model)
     @edit_permission_required
     def post(self, import_id):
         # Check user role first
@@ -128,11 +110,11 @@ class AppImportConfirmApi(Resource):
 
 @console_ns.route("/apps/imports/<string:app_id>/check-dependencies")
 class AppImportCheckDependenciesApi(Resource):
+    @console_ns.response(200, "Dependencies checked", console_ns.models[CheckDependenciesResult.__name__])
     @setup_required
     @login_required
     @get_app_model
     @account_initialization_required
-    @marshal_with(app_import_check_dependencies_model)
     @edit_permission_required
     def get(self, app_model: App):
         with sessionmaker(db.engine).begin() as session:

api/controllers/console/app/completion.py

@@ -161,7 +161,7 @@ class ChatMessageApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT])
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @edit_permission_required
     def post(self, app_model):
         args_model = ChatMessagePayload.model_validate(console_ns.payload)
@@ -215,7 +215,7 @@ class ChatMessageStopApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT])
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     def post(self, app_model, task_id):
         if not isinstance(current_user, Account):
             raise ValueError("current_user must be an Account instance")

api/controllers/console/app/mcp_server.py

@@ -1,23 +1,27 @@
 import json
+from datetime import datetime
+from typing import Any
 
-from flask_restx import Resource, marshal_with
-from pydantic import BaseModel, Field
+from flask_restx import Resource
+from pydantic import BaseModel, Field, field_validator
 from sqlalchemy import select
 from werkzeug.exceptions import NotFound
 
+from controllers.common.schema import register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import account_initialization_required, edit_permission_required, setup_required
 from extensions.ext_database import db
-from fields.app_fields import app_server_fields
+from fields.base import ResponseModel
 from libs.login import current_account_with_tenant, login_required
 from models.enums import AppMCPServerStatus
 from models.model import AppMCPServer
 
-DEFAULT_REF_TEMPLATE_SWAGGER_2_0 = "#/definitions/{model}"
 
-# Register model for flask_restx to avoid dict type issues in Swagger
-app_server_model = console_ns.model("AppServer", app_server_fields)
+def _to_timestamp(value: datetime | int | None) -> int | None:
+    if isinstance(value, datetime):
+        return int(value.timestamp())
+    return value
 
 
 class MCPServerCreatePayload(BaseModel):
@@ -32,8 +36,33 @@ class MCPServerUpdatePayload(BaseModel):
     status: str | None = Field(default=None, description="Server status")
 
 
-for model in (MCPServerCreatePayload, MCPServerUpdatePayload):
-    console_ns.schema_model(model.__name__, model.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0))
+class AppMCPServerResponse(ResponseModel):
+    id: str
+    name: str
+    server_code: str
+    description: str
+    status: str
+    parameters: dict[str, Any] | list[Any] | str
+    created_at: int | None = None
+    updated_at: int | None = None
+
+    @field_validator("parameters", mode="before")
+    @classmethod
+    def _parse_json_string(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            try:
+                return json.loads(value)
+            except (json.JSONDecodeError, TypeError):
+                return value
+        return value
+
+    @field_validator("created_at", "updated_at", mode="before")
+    @classmethod
+    def _normalize_timestamp(cls, value: datetime | int | None) -> int | None:
+        return _to_timestamp(value)
+
+
+register_schema_models(console_ns, MCPServerCreatePayload, MCPServerUpdatePayload, AppMCPServerResponse)
 
 
 @console_ns.route("/apps/<uuid:app_id>/server")
@@ -41,27 +70,27 @@ class AppMCPServerController(Resource):
     @console_ns.doc("get_app_mcp_server")
     @console_ns.doc(description="Get MCP server configuration for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "MCP server configuration retrieved successfully", app_server_model)
+    @console_ns.response(200, "Server configuration", console_ns.models[AppMCPServerResponse.__name__])
     @login_required
     @account_initialization_required
     @setup_required
     @get_app_model
-    @marshal_with(app_server_model)
     def get(self, app_model):
         server = db.session.scalar(select(AppMCPServer).where(AppMCPServer.app_id == app_model.id).limit(1))
-        return server
+        if server is None:
+            return {}
+        return AppMCPServerResponse.model_validate(server, from_attributes=True).model_dump(mode="json")
 
     @console_ns.doc("create_app_mcp_server")
     @console_ns.doc(description="Create MCP server configuration for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[MCPServerCreatePayload.__name__])
-    @console_ns.response(201, "MCP server configuration created successfully", app_server_model)
+    @console_ns.response(200, "Server created", console_ns.models[AppMCPServerResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @account_initialization_required
     @get_app_model
     @login_required
     @setup_required
-    @marshal_with(app_server_model)
     @edit_permission_required
     def post(self, app_model):
         _, current_tenant_id = current_account_with_tenant()
@@ -82,20 +111,19 @@ class AppMCPServerController(Resource):
         )
         db.session.add(server)
         db.session.commit()
-        return server
+        return AppMCPServerResponse.model_validate(server, from_attributes=True).model_dump(mode="json")
 
     @console_ns.doc("update_app_mcp_server")
     @console_ns.doc(description="Update MCP server configuration for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[MCPServerUpdatePayload.__name__])
-    @console_ns.response(200, "MCP server configuration updated successfully", app_server_model)
+    @console_ns.response(200, "Server updated", console_ns.models[AppMCPServerResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @console_ns.response(404, "Server not found")
     @get_app_model
     @login_required
     @setup_required
     @account_initialization_required
-    @marshal_with(app_server_model)
     @edit_permission_required
     def put(self, app_model):
         payload = MCPServerUpdatePayload.model_validate(console_ns.payload or {})
@@ -118,7 +146,7 @@ class AppMCPServerController(Resource):
             except ValueError:
                 raise ValueError("Invalid status")
         db.session.commit()
-        return server
+        return AppMCPServerResponse.model_validate(server, from_attributes=True).model_dump(mode="json")
 
 
 @console_ns.route("/apps/<uuid:server_id>/server/refresh")
@@ -126,13 +154,12 @@ class AppMCPServerRefreshController(Resource):
     @console_ns.doc("refresh_app_mcp_server")
     @console_ns.doc(description="Refresh MCP server configuration and regenerate server code")
     @console_ns.doc(params={"server_id": "Server ID"})
-    @console_ns.response(200, "MCP server refreshed successfully", app_server_model)
+    @console_ns.response(200, "Server refreshed", console_ns.models[AppMCPServerResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @console_ns.response(404, "Server not found")
     @setup_required
     @login_required
     @account_initialization_required
-    @marshal_with(app_server_model)
     @edit_permission_required
     def get(self, server_id):
         _, current_tenant_id = current_account_with_tenant()
@@ -145,4 +172,4 @@ class AppMCPServerRefreshController(Resource):
             raise NotFound()
         server.server_code = AppMCPServer.generate_server_code(16)
         db.session.commit()
-        return server
+        return AppMCPServerResponse.model_validate(server, from_attributes=True).model_dump(mode="json")

api/controllers/console/app/message.py

@@ -237,7 +237,7 @@ class ChatMessageListApi(Resource):
     @login_required
     @account_initialization_required
     @setup_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT])
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @marshal_with(message_infinite_scroll_pagination_model)
     @edit_permission_required
     def get(self, app_model):
@@ -393,7 +393,7 @@ class MessageSuggestedQuestionApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT])
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     def get(self, app_model, message_id):
         current_user, _ = current_account_with_tenant()
         message_id = str(message_id)

api/controllers/console/app/site.py

@@ -1,11 +1,12 @@
 from typing import Literal
 
-from flask_restx import Resource, marshal_with
+from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
 from sqlalchemy import select
 from werkzeug.exceptions import NotFound
 
 from constants.languages import supported_language
+from controllers.common.schema import register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
@@ -15,13 +16,11 @@ from controllers.console.wraps import (
     setup_required,
 )
 from extensions.ext_database import db
-from fields.app_fields import app_site_fields
+from fields.base import ResponseModel
 from libs.datetime_utils import naive_utc_now
 from libs.login import current_account_with_tenant, login_required
 from models import Site
 
-DEFAULT_REF_TEMPLATE_SWAGGER_2_0 = "#/definitions/{model}"
-
 
 class AppSiteUpdatePayload(BaseModel):
     title: str | None = Field(default=None)
@@ -49,13 +48,26 @@ class AppSiteUpdatePayload(BaseModel):
         return supported_language(value)
 
 
-console_ns.schema_model(
-    AppSiteUpdatePayload.__name__,
-    AppSiteUpdatePayload.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0),
-)
+class AppSiteResponse(ResponseModel):
+    app_id: str
+    access_token: str | None = Field(default=None, validation_alias="code")
+    code: str | None = None
+    title: str
+    icon: str | None = None
+    icon_background: str | None = None
+    description: str | None = None
+    default_language: str
+    customize_domain: str | None = None
+    copyright: str | None = None
+    privacy_policy: str | None = None
+    custom_disclaimer: str | None = None
+    customize_token_strategy: str
+    prompt_public: bool
+    show_workflow_steps: bool
+    use_icon_as_answer_icon: bool
 
-# Register model for flask_restx to avoid dict type issues in Swagger
-app_site_model = console_ns.model("AppSite", app_site_fields)
+
+register_schema_models(console_ns, AppSiteUpdatePayload, AppSiteResponse)
 
 
 @console_ns.route("/apps/<uuid:app_id>/site")
@@ -64,7 +76,7 @@ class AppSite(Resource):
     @console_ns.doc(description="Update application site configuration")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[AppSiteUpdatePayload.__name__])
-    @console_ns.response(200, "Site configuration updated successfully", app_site_model)
+    @console_ns.response(200, "Site configuration updated successfully", console_ns.models[AppSiteResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @console_ns.response(404, "App not found")
     @setup_required
@@ -72,7 +84,6 @@ class AppSite(Resource):
     @edit_permission_required
     @account_initialization_required
     @get_app_model
-    @marshal_with(app_site_model)
     def post(self, app_model):
         args = AppSiteUpdatePayload.model_validate(console_ns.payload or {})
         current_user, _ = current_account_with_tenant()
@@ -106,7 +117,7 @@ class AppSite(Resource):
         site.updated_at = naive_utc_now()
         db.session.commit()
 
-        return site
+        return AppSiteResponse.model_validate(site, from_attributes=True).model_dump(mode="json")
 
 
 @console_ns.route("/apps/<uuid:app_id>/site/access-token-reset")
@@ -114,7 +125,7 @@ class AppSiteAccessTokenReset(Resource):
     @console_ns.doc("reset_app_site_access_token")
     @console_ns.doc(description="Reset access token for application site")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Access token reset successfully", app_site_model)
+    @console_ns.response(200, "Access token reset successfully", console_ns.models[AppSiteResponse.__name__])
     @console_ns.response(403, "Insufficient permissions (admin/owner required)")
     @console_ns.response(404, "App or site not found")
     @setup_required
@@ -122,7 +133,6 @@ class AppSiteAccessTokenReset(Resource):
     @is_admin_or_owner_required
     @account_initialization_required
     @get_app_model
-    @marshal_with(app_site_model)
     def post(self, app_model):
         current_user, _ = current_account_with_tenant()
         site = db.session.scalar(select(Site).where(Site.app_id == app_model.id).limit(1))
@@ -135,4 +145,4 @@ class AppSiteAccessTokenReset(Resource):
         site.updated_at = naive_utc_now()
         db.session.commit()
 
-        return site
+        return AppSiteResponse.model_validate(site, from_attributes=True).model_dump(mode="json")

api/controllers/console/app/workflow.py

@@ -206,7 +206,7 @@ class DraftWorkflowApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW, AppMode.AGENT])
     @marshal_with(workflow_model)
     @edit_permission_required
     def get(self, app_model: App):
@@ -226,7 +226,7 @@ class DraftWorkflowApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW, AppMode.AGENT])
     @console_ns.doc("sync_draft_workflow")
     @console_ns.doc(description="Sync draft workflow configuration")
     @console_ns.expect(console_ns.models[SyncDraftWorkflowPayload.__name__])
@@ -310,7 +310,7 @@ class AdvancedChatDraftWorkflowRunApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @edit_permission_required
     def post(self, app_model: App):
         """
@@ -356,7 +356,7 @@ class AdvancedChatDraftRunIterationNodeApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @edit_permission_required
     def post(self, app_model: App, node_id: str):
         """
@@ -432,7 +432,7 @@ class AdvancedChatDraftRunLoopNodeApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @edit_permission_required
     def post(self, app_model: App, node_id: str):
         """
@@ -534,7 +534,7 @@ class AdvancedChatDraftHumanInputFormPreviewApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @edit_permission_required
     def post(self, app_model: App, node_id: str):
         """
@@ -563,7 +563,7 @@ class AdvancedChatDraftHumanInputFormRunApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @edit_permission_required
     def post(self, app_model: App, node_id: str):
         """
@@ -718,7 +718,7 @@ class WorkflowTaskStopApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW, AppMode.AGENT])
     @edit_permission_required
     def post(self, app_model: App, task_id: str):
         """
@@ -746,7 +746,7 @@ class DraftWorkflowNodeRunApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW, AppMode.AGENT])
     @marshal_with(workflow_run_node_execution_model)
     @edit_permission_required
     def post(self, app_model: App, node_id: str):
@@ -792,7 +792,7 @@ class PublishedWorkflowApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW, AppMode.AGENT])
     @marshal_with(workflow_model)
     @edit_permission_required
     def get(self, app_model: App):
@@ -810,7 +810,7 @@ class PublishedWorkflowApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW, AppMode.AGENT])
     @edit_permission_required
     def post(self, app_model: App):
         """
@@ -854,7 +854,7 @@ class DefaultBlockConfigsApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW, AppMode.AGENT])
     @edit_permission_required
     def get(self, app_model: App):
         """
@@ -876,7 +876,7 @@ class DefaultBlockConfigApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW, AppMode.AGENT])
     @edit_permission_required
     def get(self, app_model: App, block_type: str):
         """
@@ -941,7 +941,7 @@ class PublishedAllWorkflowApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW, AppMode.AGENT])
     @marshal_with(workflow_pagination_model)
     @edit_permission_required
     def get(self, app_model: App):
@@ -990,7 +990,7 @@ class DraftWorkflowRestoreApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW, AppMode.AGENT])
     @edit_permission_required
     def post(self, app_model: App, workflow_id: str):
         current_user, _ = current_account_with_tenant()
@@ -1028,7 +1028,7 @@ class WorkflowByIdApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW, AppMode.AGENT])
     @marshal_with(workflow_model)
     @edit_permission_required
     def patch(self, app_model: App, workflow_id: str):
@@ -1068,7 +1068,7 @@ class WorkflowByIdApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW, AppMode.AGENT])
     @edit_permission_required
     def delete(self, app_model: App, workflow_id: str):
         """
@@ -1103,7 +1103,7 @@ class DraftWorkflowNodeLastRunApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW, AppMode.AGENT])
     @marshal_with(workflow_run_node_execution_model)
     def get(self, app_model: App, node_id: str):
         srv = WorkflowService()

api/controllers/console/app/workflow_comment.py

@@ -0,0 +1,322 @@
+import logging
+
+from flask_restx import Resource, marshal_with
+from pydantic import BaseModel, Field, TypeAdapter
+
+from controllers.console import console_ns
+from controllers.console.app.wraps import get_app_model
+from controllers.console.wraps import account_initialization_required, setup_required
+from fields.member_fields import AccountWithRole
+from fields.workflow_comment_fields import (
+    workflow_comment_basic_fields,
+    workflow_comment_create_fields,
+    workflow_comment_detail_fields,
+    workflow_comment_reply_create_fields,
+    workflow_comment_reply_update_fields,
+    workflow_comment_resolve_fields,
+    workflow_comment_update_fields,
+)
+from libs.login import current_user, login_required
+from models import App
+from services.account_service import TenantService
+from services.workflow_comment_service import WorkflowCommentService
+
+logger = logging.getLogger(__name__)
+DEFAULT_REF_TEMPLATE_SWAGGER_2_0 = "#/definitions/{model}"
+
+
+class WorkflowCommentCreatePayload(BaseModel):
+    position_x: float = Field(..., description="Comment X position")
+    position_y: float = Field(..., description="Comment Y position")
+    content: str = Field(..., description="Comment content")
+    mentioned_user_ids: list[str] = Field(default_factory=list, description="Mentioned user IDs")
+
+
+class WorkflowCommentUpdatePayload(BaseModel):
+    content: str = Field(..., description="Comment content")
+    position_x: float | None = Field(default=None, description="Comment X position")
+    position_y: float | None = Field(default=None, description="Comment Y position")
+    mentioned_user_ids: list[str] = Field(default_factory=list, description="Mentioned user IDs")
+
+
+class WorkflowCommentReplyCreatePayload(BaseModel):
+    content: str = Field(..., description="Reply content")
+    mentioned_user_ids: list[str] = Field(default_factory=list, description="Mentioned user IDs")
+
+
+class WorkflowCommentReplyUpdatePayload(BaseModel):
+    content: str = Field(..., description="Reply content")
+    mentioned_user_ids: list[str] = Field(default_factory=list, description="Mentioned user IDs")
+
+
+class WorkflowCommentMentionUsersResponse(BaseModel):
+    users: list[AccountWithRole] = Field(description="Mentionable users")
+
+
+for model in (
+    WorkflowCommentCreatePayload,
+    WorkflowCommentUpdatePayload,
+    WorkflowCommentReplyCreatePayload,
+    WorkflowCommentReplyUpdatePayload,
+):
+    console_ns.schema_model(model.__name__, model.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0))
+
+for model in (AccountWithRole, WorkflowCommentMentionUsersResponse):
+    console_ns.schema_model(model.__name__, model.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0))
+
+workflow_comment_basic_model = console_ns.model("WorkflowCommentBasic", workflow_comment_basic_fields)
+workflow_comment_detail_model = console_ns.model("WorkflowCommentDetail", workflow_comment_detail_fields)
+workflow_comment_create_model = console_ns.model("WorkflowCommentCreate", workflow_comment_create_fields)
+workflow_comment_update_model = console_ns.model("WorkflowCommentUpdate", workflow_comment_update_fields)
+workflow_comment_resolve_model = console_ns.model("WorkflowCommentResolve", workflow_comment_resolve_fields)
+workflow_comment_reply_create_model = console_ns.model(
+    "WorkflowCommentReplyCreate", workflow_comment_reply_create_fields
+)
+workflow_comment_reply_update_model = console_ns.model(
+    "WorkflowCommentReplyUpdate", workflow_comment_reply_update_fields
+)
+workflow_comment_mention_users_model = console_ns.models[WorkflowCommentMentionUsersResponse.__name__]
+
+
+@console_ns.route("/apps/<uuid:app_id>/workflow/comments")
+class WorkflowCommentListApi(Resource):
+    """API for listing and creating workflow comments."""
+
+    @console_ns.doc("list_workflow_comments")
+    @console_ns.doc(description="Get all comments for a workflow")
+    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.response(200, "Comments retrieved successfully", workflow_comment_basic_model)
+    @login_required
+    @setup_required
+    @account_initialization_required
+    @get_app_model()
+    @marshal_with(workflow_comment_basic_model, envelope="data")
+    def get(self, app_model: App):
+        """Get all comments for a workflow."""
+        comments = WorkflowCommentService.get_comments(tenant_id=current_user.current_tenant_id, app_id=app_model.id)
+
+        return comments
+
+    @console_ns.doc("create_workflow_comment")
+    @console_ns.doc(description="Create a new workflow comment")
+    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.expect(console_ns.models[WorkflowCommentCreatePayload.__name__])
+    @console_ns.response(201, "Comment created successfully", workflow_comment_create_model)
+    @login_required
+    @setup_required
+    @account_initialization_required
+    @get_app_model()
+    @marshal_with(workflow_comment_create_model)
+    def post(self, app_model: App):
+        """Create a new workflow comment."""
+        payload = WorkflowCommentCreatePayload.model_validate(console_ns.payload or {})
+
+        result = WorkflowCommentService.create_comment(
+            tenant_id=current_user.current_tenant_id,
+            app_id=app_model.id,
+            created_by=current_user.id,
+            content=payload.content,
+            position_x=payload.position_x,
+            position_y=payload.position_y,
+            mentioned_user_ids=payload.mentioned_user_ids,
+        )
+
+        return result, 201
+
+
+@console_ns.route("/apps/<uuid:app_id>/workflow/comments/<string:comment_id>")
+class WorkflowCommentDetailApi(Resource):
+    """API for managing individual workflow comments."""
+
+    @console_ns.doc("get_workflow_comment")
+    @console_ns.doc(description="Get a specific workflow comment")
+    @console_ns.doc(params={"app_id": "Application ID", "comment_id": "Comment ID"})
+    @console_ns.response(200, "Comment retrieved successfully", workflow_comment_detail_model)
+    @login_required
+    @setup_required
+    @account_initialization_required
+    @get_app_model()
+    @marshal_with(workflow_comment_detail_model)
+    def get(self, app_model: App, comment_id: str):
+        """Get a specific workflow comment."""
+        comment = WorkflowCommentService.get_comment(
+            tenant_id=current_user.current_tenant_id, app_id=app_model.id, comment_id=comment_id
+        )
+
+        return comment
+
+    @console_ns.doc("update_workflow_comment")
+    @console_ns.doc(description="Update a workflow comment")
+    @console_ns.doc(params={"app_id": "Application ID", "comment_id": "Comment ID"})
+    @console_ns.expect(console_ns.models[WorkflowCommentUpdatePayload.__name__])
+    @console_ns.response(200, "Comment updated successfully", workflow_comment_update_model)
+    @login_required
+    @setup_required
+    @account_initialization_required
+    @get_app_model()
+    @marshal_with(workflow_comment_update_model)
+    def put(self, app_model: App, comment_id: str):
+        """Update a workflow comment."""
+        payload = WorkflowCommentUpdatePayload.model_validate(console_ns.payload or {})
+
+        result = WorkflowCommentService.update_comment(
+            tenant_id=current_user.current_tenant_id,
+            app_id=app_model.id,
+            comment_id=comment_id,
+            user_id=current_user.id,
+            content=payload.content,
+            position_x=payload.position_x,
+            position_y=payload.position_y,
+            mentioned_user_ids=payload.mentioned_user_ids,
+        )
+
+        return result
+
+    @console_ns.doc("delete_workflow_comment")
+    @console_ns.doc(description="Delete a workflow comment")
+    @console_ns.doc(params={"app_id": "Application ID", "comment_id": "Comment ID"})
+    @console_ns.response(204, "Comment deleted successfully")
+    @login_required
+    @setup_required
+    @account_initialization_required
+    @get_app_model()
+    def delete(self, app_model: App, comment_id: str):
+        """Delete a workflow comment."""
+        WorkflowCommentService.delete_comment(
+            tenant_id=current_user.current_tenant_id,
+            app_id=app_model.id,
+            comment_id=comment_id,
+            user_id=current_user.id,
+        )
+
+        return {"result": "success"}, 204
+
+
+@console_ns.route("/apps/<uuid:app_id>/workflow/comments/<string:comment_id>/resolve")
+class WorkflowCommentResolveApi(Resource):
+    """API for resolving and reopening workflow comments."""
+
+    @console_ns.doc("resolve_workflow_comment")
+    @console_ns.doc(description="Resolve a workflow comment")
+    @console_ns.doc(params={"app_id": "Application ID", "comment_id": "Comment ID"})
+    @console_ns.response(200, "Comment resolved successfully", workflow_comment_resolve_model)
+    @login_required
+    @setup_required
+    @account_initialization_required
+    @get_app_model()
+    @marshal_with(workflow_comment_resolve_model)
+    def post(self, app_model: App, comment_id: str):
+        """Resolve a workflow comment."""
+        comment = WorkflowCommentService.resolve_comment(
+            tenant_id=current_user.current_tenant_id,
+            app_id=app_model.id,
+            comment_id=comment_id,
+            user_id=current_user.id,
+        )
+
+        return comment
+
+
+@console_ns.route("/apps/<uuid:app_id>/workflow/comments/<string:comment_id>/replies")
+class WorkflowCommentReplyApi(Resource):
+    """API for managing comment replies."""
+
+    @console_ns.doc("create_workflow_comment_reply")
+    @console_ns.doc(description="Add a reply to a workflow comment")
+    @console_ns.doc(params={"app_id": "Application ID", "comment_id": "Comment ID"})
+    @console_ns.expect(console_ns.models[WorkflowCommentReplyCreatePayload.__name__])
+    @console_ns.response(201, "Reply created successfully", workflow_comment_reply_create_model)
+    @login_required
+    @setup_required
+    @account_initialization_required
+    @get_app_model()
+    @marshal_with(workflow_comment_reply_create_model)
+    def post(self, app_model: App, comment_id: str):
+        """Add a reply to a workflow comment."""
+        # Validate comment access first
+        WorkflowCommentService.validate_comment_access(
+            comment_id=comment_id, tenant_id=current_user.current_tenant_id, app_id=app_model.id
+        )
+
+        payload = WorkflowCommentReplyCreatePayload.model_validate(console_ns.payload or {})
+
+        result = WorkflowCommentService.create_reply(
+            comment_id=comment_id,
+            content=payload.content,
+            created_by=current_user.id,
+            mentioned_user_ids=payload.mentioned_user_ids,
+        )
+
+        return result, 201
+
+
+@console_ns.route("/apps/<uuid:app_id>/workflow/comments/<string:comment_id>/replies/<string:reply_id>")
+class WorkflowCommentReplyDetailApi(Resource):
+    """API for managing individual comment replies."""
+
+    @console_ns.doc("update_workflow_comment_reply")
+    @console_ns.doc(description="Update a comment reply")
+    @console_ns.doc(params={"app_id": "Application ID", "comment_id": "Comment ID", "reply_id": "Reply ID"})
+    @console_ns.expect(console_ns.models[WorkflowCommentReplyUpdatePayload.__name__])
+    @console_ns.response(200, "Reply updated successfully", workflow_comment_reply_update_model)
+    @login_required
+    @setup_required
+    @account_initialization_required
+    @get_app_model()
+    @marshal_with(workflow_comment_reply_update_model)
+    def put(self, app_model: App, comment_id: str, reply_id: str):
+        """Update a comment reply."""
+        # Validate comment access first
+        WorkflowCommentService.validate_comment_access(
+            comment_id=comment_id, tenant_id=current_user.current_tenant_id, app_id=app_model.id
+        )
+
+        payload = WorkflowCommentReplyUpdatePayload.model_validate(console_ns.payload or {})
+
+        reply = WorkflowCommentService.update_reply(
+            reply_id=reply_id,
+            user_id=current_user.id,
+            content=payload.content,
+            mentioned_user_ids=payload.mentioned_user_ids,
+        )
+
+        return reply
+
+    @console_ns.doc("delete_workflow_comment_reply")
+    @console_ns.doc(description="Delete a comment reply")
+    @console_ns.doc(params={"app_id": "Application ID", "comment_id": "Comment ID", "reply_id": "Reply ID"})
+    @console_ns.response(204, "Reply deleted successfully")
+    @login_required
+    @setup_required
+    @account_initialization_required
+    @get_app_model()
+    def delete(self, app_model: App, comment_id: str, reply_id: str):
+        """Delete a comment reply."""
+        # Validate comment access first
+        WorkflowCommentService.validate_comment_access(
+            comment_id=comment_id, tenant_id=current_user.current_tenant_id, app_id=app_model.id
+        )
+
+        WorkflowCommentService.delete_reply(reply_id=reply_id, user_id=current_user.id)
+
+        return {"result": "success"}, 204
+
+
+@console_ns.route("/apps/<uuid:app_id>/workflow/comments/mention-users")
+class WorkflowCommentMentionUsersApi(Resource):
+    """API for getting mentionable users for workflow comments."""
+
+    @console_ns.doc("workflow_comment_mention_users")
+    @console_ns.doc(description="Get all users in current tenant for mentions")
+    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.response(200, "Mentionable users retrieved successfully", workflow_comment_mention_users_model)
+    @login_required
+    @setup_required
+    @account_initialization_required
+    @get_app_model()
+    def get(self, app_model: App):
+        """Get all users in current tenant for mentions."""
+        members = TenantService.get_tenant_members(current_user.current_tenant)
+        member_models = TypeAdapter(list[AccountWithRole]).validate_python(members, from_attributes=True)
+        response = WorkflowCommentMentionUsersResponse(users=member_models)
+        return response.model_dump(mode="json"), 200

api/controllers/console/app/workflow_draft_variable.py

@@ -216,7 +216,7 @@ def _api_prerequisite[**P, R](f: Callable[P, R]) -> Callable[P, R | Response]:
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW, AppMode.AGENT])
     @wraps(f)
     def wrapper(*args: P.args, **kwargs: P.kwargs) -> R | Response:
         return f(*args, **kwargs)

api/controllers/console/app/workflow_run.py

@@ -207,7 +207,7 @@ class AdvancedChatAppWorkflowRunListApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @marshal_with(advanced_chat_workflow_run_pagination_model)
     def get(self, app_model: App):
         """
@@ -305,7 +305,7 @@ class AdvancedChatAppWorkflowRunCountApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @marshal_with(workflow_run_count_model)
     def get(self, app_model: App):
         """
@@ -349,7 +349,7 @@ class WorkflowRunListApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW, AppMode.AGENT])
     @marshal_with(workflow_run_pagination_model)
     def get(self, app_model: App):
         """
@@ -397,7 +397,7 @@ class WorkflowRunCountApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW, AppMode.AGENT])
     @marshal_with(workflow_run_count_model)
     def get(self, app_model: App):
         """
@@ -434,7 +434,7 @@ class WorkflowRunDetailApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW, AppMode.AGENT])
     @marshal_with(workflow_run_detail_model)
     def get(self, app_model: App, run_id):
         """
@@ -458,7 +458,7 @@ class WorkflowRunNodeExecutionListApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW, AppMode.AGENT])
     @marshal_with(workflow_run_node_execution_list_model)
     def get(self, app_model: App, run_id):
         """

api/controllers/console/auth/activate.py

@@ -1,8 +1,9 @@
 from flask import request
-from flask_restx import Resource, fields
+from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
 
 from constants.languages import supported_language
+from controllers.common.schema import register_schema_models
 from controllers.console import console_ns
 from controllers.console.error import AlreadyActivateError
 from extensions.ext_database import db
@@ -11,8 +12,6 @@ from libs.helper import EmailStr, timezone
 from models import AccountStatus
 from services.account_service import RegisterService
 
-DEFAULT_REF_TEMPLATE_SWAGGER_2_0 = "#/definitions/{model}"
-
 
 class ActivateCheckQuery(BaseModel):
     workspace_id: str | None = Field(default=None)
@@ -39,8 +38,16 @@ class ActivatePayload(BaseModel):
         return timezone(value)
 
 
-for model in (ActivateCheckQuery, ActivatePayload):
-    console_ns.schema_model(model.__name__, model.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0))
+class ActivationCheckResponse(BaseModel):
+    is_valid: bool = Field(description="Whether token is valid")
+    data: dict | None = Field(default=None, description="Activation data if valid")
+
+
+class ActivationResponse(BaseModel):
+    result: str = Field(description="Operation result")
+
+
+register_schema_models(console_ns, ActivateCheckQuery, ActivatePayload, ActivationCheckResponse, ActivationResponse)
 
 
 @console_ns.route("/activate/check")
@@ -51,13 +58,7 @@ class ActivateCheckApi(Resource):
     @console_ns.response(
         200,
         "Success",
-        console_ns.model(
-            "ActivationCheckResponse",
-            {
-                "is_valid": fields.Boolean(description="Whether token is valid"),
-                "data": fields.Raw(description="Activation data if valid"),
-            },
-        ),
+        console_ns.models[ActivationCheckResponse.__name__],
     )
     def get(self):
         args = ActivateCheckQuery.model_validate(request.args.to_dict(flat=True))  # type: ignore
@@ -95,12 +96,7 @@ class ActivateApi(Resource):
     @console_ns.response(
         200,
         "Account activated successfully",
-        console_ns.model(
-            "ActivationResponse",
-            {
-                "result": fields.String(description="Operation result"),
-            },
-        ),
+        console_ns.models[ActivationResponse.__name__],
     )
     @console_ns.response(400, "Already activated or invalid token")
     def post(self):

api/controllers/console/datasets/datasets.py

@@ -11,10 +11,7 @@ import services
 from configs import dify_config
 from controllers.common.schema import get_or_create_model, register_schema_models
 from controllers.console import console_ns
-from controllers.console.apikey import (
-    api_key_item_model,
-    api_key_list_model,
-)
+from controllers.console.apikey import ApiKeyItem, ApiKeyList
 from controllers.console.app.error import ProviderNotInitializeError
 from controllers.console.datasets.error import DatasetInUseError, DatasetNameDuplicateError, IndexingEstimateError
 from controllers.console.wraps import (
@@ -785,23 +782,23 @@ class DatasetApiKeyApi(Resource):
 
     @console_ns.doc("get_dataset_api_keys")
     @console_ns.doc(description="Get dataset API keys")
-    @console_ns.response(200, "API keys retrieved successfully", api_key_list_model)
+    @console_ns.response(200, "API keys retrieved successfully", console_ns.models[ApiKeyList.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    @marshal_with(api_key_list_model)
     def get(self):
         _, current_tenant_id = current_account_with_tenant()
         keys = db.session.scalars(
             select(ApiToken).where(ApiToken.type == self.resource_type, ApiToken.tenant_id == current_tenant_id)
         ).all()
-        return {"items": keys}
+        return ApiKeyList.model_validate({"data": keys}, from_attributes=True).model_dump(mode="json")
 
+    @console_ns.response(200, "API key created successfully", console_ns.models[ApiKeyItem.__name__])
+    @console_ns.response(400, "Maximum keys exceeded")
     @setup_required
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    @marshal_with(api_key_item_model)
     def post(self):
         _, current_tenant_id = current_account_with_tenant()
 
@@ -828,7 +825,7 @@ class DatasetApiKeyApi(Resource):
         api_token.type = self.resource_type
         db.session.add(api_token)
         db.session.commit()
-        return api_token, 200
+        return ApiKeyItem.model_validate(api_token, from_attributes=True).model_dump(mode="json"), 200
 
 
 @console_ns.route("/datasets/api-keys/<uuid:api_key_id>")

api/controllers/console/datasets/datasets_document.py

@@ -4,7 +4,6 @@ from argparse import ArgumentTypeError
 from collections.abc import Sequence
 from contextlib import ExitStack
 from typing import Any, Literal, cast
-from uuid import UUID
 
 import sqlalchemy as sa
 from flask import request, send_file
@@ -16,6 +15,7 @@ from sqlalchemy import asc, desc, func, select
 from werkzeug.exceptions import Forbidden, NotFound
 
 import services
+from controllers.common.controller_schemas import DocumentBatchDownloadZipPayload
 from controllers.common.schema import get_or_create_model, register_schema_models
 from controllers.console import console_ns
 from core.errors.error import (
@@ -71,9 +71,6 @@ from ..wraps import (
 
 logger = logging.getLogger(__name__)
 
-# NOTE: Keep constants near the top of the module for discoverability.
-DOCUMENT_BATCH_DOWNLOAD_ZIP_MAX_DOCS = 100
-
 
 # Register models for flask_restx to avoid dict type issues in Swagger
 dataset_model = get_or_create_model("Dataset", dataset_fields)
@@ -110,12 +107,6 @@ class GenerateSummaryPayload(BaseModel):
     document_list: list[str]
 
 
-class DocumentBatchDownloadZipPayload(BaseModel):
-    """Request payload for bulk downloading documents as a zip archive."""
-
-    document_ids: list[UUID] = Field(..., min_length=1, max_length=DOCUMENT_BATCH_DOWNLOAD_ZIP_MAX_DOCS)
-
-
 class DocumentDatasetListParam(BaseModel):
     page: int = Field(1, title="Page", description="Page number.")
     limit: int = Field(20, title="Limit", description="Page size.")

api/controllers/console/datasets/datasets_segments.py

@@ -10,6 +10,7 @@ from werkzeug.exceptions import Forbidden, NotFound
 
 import services
 from configs import dify_config
+from controllers.common.controller_schemas import ChildChunkCreatePayload, ChildChunkUpdatePayload
 from controllers.common.schema import register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.error import ProviderNotInitializeError
@@ -82,14 +83,6 @@ class BatchImportPayload(BaseModel):
     upload_file_id: str
 
 
-class ChildChunkCreatePayload(BaseModel):
-    content: str
-
-
-class ChildChunkUpdatePayload(BaseModel):
-    content: str
-
-
 class ChildChunkBatchUpdatePayload(BaseModel):
     chunks: list[ChildChunkUpdateArgs]
 

api/controllers/console/datasets/metadata.py

@@ -1,9 +1,9 @@
 from typing import Literal
 
 from flask_restx import Resource, marshal_with
-from pydantic import BaseModel
 from werkzeug.exceptions import NotFound
 
+from controllers.common.controller_schemas import MetadataUpdatePayload
 from controllers.common.schema import register_schema_models
 from controllers.console import console_ns
 from controllers.console.wraps import account_initialization_required, enterprise_license_required, setup_required
@@ -18,11 +18,6 @@ from services.entities.knowledge_entities.knowledge_entities import (
 )
 from services.metadata_service import MetadataService
 
-
-class MetadataUpdatePayload(BaseModel):
-    name: str
-
-
 register_schema_models(
     console_ns, MetadataArgs, MetadataOperationData, MetadataUpdatePayload, DocumentMetadataOperation, MetadataDetail
 )

api/controllers/console/socketio/__init__.py

@@ -0,0 +1 @@
+

api/controllers/console/socketio/workflow.py

@@ -0,0 +1,119 @@
+import logging
+from collections.abc import Callable
+from typing import cast
+
+from flask import Request as FlaskRequest
+
+from extensions.ext_socketio import sio
+from libs.passport import PassportService
+from libs.token import extract_access_token
+from repositories.workflow_collaboration_repository import WorkflowCollaborationRepository
+from services.account_service import AccountService
+from services.workflow_collaboration_service import WorkflowCollaborationService
+
+repository = WorkflowCollaborationRepository()
+collaboration_service = WorkflowCollaborationService(repository, sio)
+
+
+def _sio_on(event: str) -> Callable[[Callable[..., object]], Callable[..., object]]:
+    return cast(Callable[[Callable[..., object]], Callable[..., object]], sio.on(event))
+
+
+@_sio_on("connect")
+def socket_connect(sid, environ, auth):
+    """
+    WebSocket connect event, do authentication here.
+    """
+    try:
+        request_environ = FlaskRequest(environ)
+        token = extract_access_token(request_environ)
+    except Exception:
+        logging.exception("Failed to extract token")
+        token = None
+
+    if not token:
+        logging.warning("Socket connect rejected: missing token (sid=%s)", sid)
+        return False
+
+    try:
+        decoded = PassportService().verify(token)
+        user_id = decoded.get("user_id")
+        if not user_id:
+            logging.warning("Socket connect rejected: missing user_id (sid=%s)", sid)
+            return False
+
+        with sio.app.app_context():
+            user = AccountService.load_logged_in_account(account_id=user_id)
+            if not user:
+                logging.warning("Socket connect rejected: user not found (user_id=%s, sid=%s)", user_id, sid)
+                return False
+            if not user.has_edit_permission:
+                logging.warning("Socket connect rejected: no edit permission (user_id=%s, sid=%s)", user_id, sid)
+                return False
+
+            collaboration_service.save_session(sid, user)
+            return True
+
+    except Exception:
+        logging.exception("Socket authentication failed")
+        return False
+
+
+@_sio_on("user_connect")
+def handle_user_connect(sid, data):
+    """
+    Handle user connect event. Each session (tab) is treated as an independent collaborator.
+    """
+    workflow_id = data.get("workflow_id")
+    if not workflow_id:
+        return {"msg": "workflow_id is required"}, 400
+
+    result = collaboration_service.register_session(workflow_id, sid)
+    if not result:
+        return {"msg": "unauthorized"}, 401
+
+    user_id, is_leader = result
+    return {"msg": "connected", "user_id": user_id, "sid": sid, "isLeader": is_leader}
+
+
+@_sio_on("disconnect")
+def handle_disconnect(sid):
+    """
+    Handle session disconnect event. Remove the specific session from online users.
+    """
+    collaboration_service.disconnect_session(sid)
+
+
+@_sio_on("collaboration_event")
+def handle_collaboration_event(sid, data):
+    """
+    Handle general collaboration events, include:
+    1. mouse_move
+    2. vars_and_features_update
+    3. sync_request (ask leader to update graph)
+    4. app_state_update
+    5. mcp_server_update
+    6. workflow_update
+    7. comments_update
+    8. node_panel_presence
+    9. skill_file_active
+    10. skill_sync_request
+    11. skill_resync_request
+    """
+    return collaboration_service.relay_collaboration_event(sid, data)
+
+
+@_sio_on("graph_event")
+def handle_graph_event(sid, data):
+    """
+    Handle graph events - simple broadcast relay.
+    """
+    return collaboration_service.relay_graph_event(sid, data)
+
+
+@_sio_on("skill_event")
+def handle_skill_event(sid, data):
+    """
+    Handle skill events - simple broadcast relay.
+    """
+    return collaboration_service.relay_skill_event(sid, data)

api/controllers/console/workspace/dsl.py

@@ -0,0 +1,67 @@
+import json
+
+import httpx
+import yaml
+from flask import request
+from flask_restx import Resource
+from pydantic import BaseModel
+from sqlalchemy.orm import Session
+from werkzeug.exceptions import Forbidden
+
+from controllers.console import console_ns
+from controllers.console.wraps import account_initialization_required, setup_required
+from core.plugin.impl.exc import PluginPermissionDeniedError
+from extensions.ext_database import db
+from libs.login import current_account_with_tenant, login_required
+from models.model import App
+from models.workflow import Workflow
+from services.app_dsl_service import AppDslService
+
+
+class DSLPredictRequest(BaseModel):
+    app_id: str
+    current_node_id: str
+
+
+@console_ns.route("/workspaces/current/dsl/predict")
+class DSLPredictApi(Resource):
+    @setup_required
+    @login_required
+    @account_initialization_required
+    def post(self):
+        user, _ = current_account_with_tenant()
+        if not user.is_admin_or_owner:
+            raise Forbidden()
+
+        args = DSLPredictRequest.model_validate(request.get_json())
+
+        app_id: str = args.app_id
+        current_node_id: str = args.current_node_id
+
+        with Session(db.engine) as session:
+            app = session.query(App).filter_by(id=app_id).first()
+            workflow = session.query(Workflow).filter_by(app_id=app_id, version=Workflow.VERSION_DRAFT).first()
+
+        if not app:
+            raise ValueError("App not found")
+        if not workflow:
+            raise ValueError("Workflow not found")
+
+        try:
+            i = 0
+            for node_id, _ in workflow.walk_nodes():
+                if node_id == current_node_id:
+                    break
+                i += 1
+
+            dsl = yaml.safe_load(AppDslService.export_dsl(app_model=app))
+
+            response = httpx.post(
+                "http://spark-832c:8000/predict",
+                json={"graph_data": dsl, "source_node_index": i},
+            )
+            return {
+                "nodes": json.loads(response.json()),
+            }
+        except PluginPermissionDeniedError as e:
+            raise ValueError(e.description) from e

api/controllers/files/storage_files.py

@@ -0,0 +1,80 @@
+"""Token-based file proxy controller for storage operations.
+
+This controller handles file download and upload operations using opaque UUID tokens.
+The token maps to the real storage key in Redis, so the actual storage path is never
+exposed in the URL.
+
+Routes:
+    GET  /files/storage-files/{token} - Download a file
+    PUT  /files/storage-files/{token} - Upload a file
+
+The operation type (download/upload) is determined by the ticket stored in Redis,
+not by the HTTP method. This ensures a download ticket cannot be used for upload
+and vice versa.
+"""
+
+from urllib.parse import quote
+
+from flask import Response, request
+from flask_restx import Resource
+from werkzeug.exceptions import Forbidden, NotFound, RequestEntityTooLarge
+
+from controllers.files import files_ns
+from extensions.ext_storage import storage
+from services.storage_ticket_service import StorageTicketService
+
+
+@files_ns.route("/storage-files/<string:token>")
+class StorageFilesApi(Resource):
+    """Handle file operations through token-based URLs."""
+
+    def get(self, token: str):
+        """Download a file using a token.
+
+        The ticket must have op="download", otherwise returns 403.
+        """
+        ticket = StorageTicketService.get_ticket(token)
+        if ticket is None:
+            raise Forbidden("Invalid or expired token")
+
+        if ticket.op != "download":
+            raise Forbidden("This token is not valid for download")
+
+        try:
+            generator = storage.load_stream(ticket.storage_key)
+        except FileNotFoundError:
+            raise NotFound("File not found")
+
+        filename = ticket.filename or ticket.storage_key.rsplit("/", 1)[-1]
+        encoded_filename = quote(filename)
+
+        return Response(
+            generator,
+            mimetype="application/octet-stream",
+            direct_passthrough=True,
+            headers={
+                "Content-Disposition": f"attachment; filename*=UTF-8''{encoded_filename}",
+            },
+        )
+
+    def put(self, token: str):
+        """Upload a file using a token.
+
+        The ticket must have op="upload", otherwise returns 403.
+        If the request body exceeds max_bytes, returns 413.
+        """
+        ticket = StorageTicketService.get_ticket(token)
+        if ticket is None:
+            raise Forbidden("Invalid or expired token")
+
+        if ticket.op != "upload":
+            raise Forbidden("This token is not valid for upload")
+
+        content = request.get_data()
+
+        if ticket.max_bytes is not None and len(content) > ticket.max_bytes:
+            raise RequestEntityTooLarge(f"Upload exceeds maximum size of {ticket.max_bytes} bytes")
+
+        storage.save(ticket.storage_key, content)
+
+        return Response(status=204)

api/controllers/inner_api/plugin/wraps.py

@@ -94,10 +94,9 @@ def get_user_tenant[**P, R](view_func: Callable[P, R]) -> Callable[P, R]:
 
 
 def plugin_data[**P, R](
-    view: Callable[P, R] | None = None,
     *,
     payload_type: type[BaseModel],
-) -> Callable[P, R] | Callable[[Callable[P, R]], Callable[P, R]]:
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
     def decorator(view_func: Callable[P, R]) -> Callable[P, R]:
         @wraps(view_func)
         def decorated_view(*args: P.args, **kwargs: P.kwargs) -> R:
@@ -116,7 +115,4 @@ def plugin_data[**P, R](
 
         return decorated_view
 
-    if view is None:
-        return decorator
-    else:
-        return decorator(view)
+    return decorator

api/controllers/service_api/app/annotation.py

@@ -12,7 +12,12 @@ from controllers.service_api.wraps import validate_app_token
 from extensions.ext_redis import redis_client
 from fields.annotation_fields import Annotation, AnnotationList
 from models.model import App
-from services.annotation_service import AppAnnotationService
+from services.annotation_service import (
+    AppAnnotationService,
+    EnableAnnotationArgs,
+    InsertAnnotationArgs,
+    UpdateAnnotationArgs,
+)
 
 
 class AnnotationCreatePayload(BaseModel):
@@ -46,10 +51,15 @@ class AnnotationReplyActionApi(Resource):
     @validate_app_token
     def post(self, app_model: App, action: Literal["enable", "disable"]):
         """Enable or disable annotation reply feature."""
-        args = AnnotationReplyActionPayload.model_validate(service_api_ns.payload or {}).model_dump()
+        payload = AnnotationReplyActionPayload.model_validate(service_api_ns.payload or {})
         match action:
             case "enable":
-                result = AppAnnotationService.enable_app_annotation(args, app_model.id)
+                enable_args: EnableAnnotationArgs = {
+                    "score_threshold": payload.score_threshold,
+                    "embedding_provider_name": payload.embedding_provider_name,
+                    "embedding_model_name": payload.embedding_model_name,
+                }
+                result = AppAnnotationService.enable_app_annotation(enable_args, app_model.id)
             case "disable":
                 result = AppAnnotationService.disable_app_annotation(app_model.id)
         return result, 200
@@ -135,8 +145,9 @@ class AnnotationListApi(Resource):
     @validate_app_token
     def post(self, app_model: App):
         """Create a new annotation."""
-        args = AnnotationCreatePayload.model_validate(service_api_ns.payload or {}).model_dump()
-        annotation = AppAnnotationService.insert_app_annotation_directly(args, app_model.id)
+        payload = AnnotationCreatePayload.model_validate(service_api_ns.payload or {})
+        insert_args: InsertAnnotationArgs = {"question": payload.question, "answer": payload.answer}
+        annotation = AppAnnotationService.insert_app_annotation_directly(insert_args, app_model.id)
         response = Annotation.model_validate(annotation, from_attributes=True)
         return response.model_dump(mode="json"), HTTPStatus.CREATED
 
@@ -164,8 +175,9 @@ class AnnotationUpdateDeleteApi(Resource):
     @edit_permission_required
     def put(self, app_model: App, annotation_id: str):
         """Update an existing annotation."""
-        args = AnnotationCreatePayload.model_validate(service_api_ns.payload or {}).model_dump()
-        annotation = AppAnnotationService.update_app_annotation_directly(args, app_model.id, annotation_id)
+        payload = AnnotationCreatePayload.model_validate(service_api_ns.payload or {})
+        update_args: UpdateAnnotationArgs = {"question": payload.question, "answer": payload.answer}
+        annotation = AppAnnotationService.update_app_annotation_directly(update_args, app_model.id, annotation_id)
         response = Annotation.model_validate(annotation, from_attributes=True)
         return response.model_dump(mode="json")
 

api/controllers/service_api/app/audio.py

@@ -3,10 +3,10 @@ import logging
 from flask import request
 from flask_restx import Resource
 from graphon.model_runtime.errors.invoke import InvokeError
-from pydantic import BaseModel, Field
 from werkzeug.exceptions import InternalServerError
 
 import services
+from controllers.common.controller_schemas import TextToAudioPayload
 from controllers.common.schema import register_schema_model
 from controllers.service_api import service_api_ns
 from controllers.service_api.app.error import (
@@ -86,13 +86,6 @@ class AudioApi(Resource):
             raise InternalServerError()
 
 
-class TextToAudioPayload(BaseModel):
-    message_id: str | None = Field(default=None, description="Message ID")
-    voice: str | None = Field(default=None, description="Voice to use for TTS")
-    text: str | None = Field(default=None, description="Text to convert to audio")
-    streaming: bool | None = Field(default=None, description="Enable streaming response")
-
-
 register_schema_model(service_api_ns, TextToAudioPayload)
 
 

api/controllers/service_api/app/completion.py

@@ -194,7 +194,7 @@ class ChatApi(Resource):
         Supports conversation management and both blocking and streaming response modes.
         """
         app_mode = AppMode.value_of(app_model.mode)
-        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
+        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT}:
             raise NotChatAppError()
 
         payload = ChatRequestPayload.model_validate(service_api_ns.payload or {})
@@ -258,7 +258,7 @@ class ChatStopApi(Resource):
     def post(self, app_model: App, end_user: EndUser, task_id: str):
         """Stop a running chat message generation."""
         app_mode = AppMode.value_of(app_model.mode)
-        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
+        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT}:
             raise NotChatAppError()
 
         AppTaskService.stop_task(

api/controllers/service_api/app/conversation.py

@@ -98,7 +98,7 @@ class ConversationApi(Resource):
         Supports pagination using last_id and limit parameters.
         """
         app_mode = AppMode.value_of(app_model.mode)
-        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
+        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT}:
             raise NotChatAppError()
 
         query_args = ConversationListQuery.model_validate(request.args.to_dict())
@@ -142,7 +142,7 @@ class ConversationDetailApi(Resource):
     def delete(self, app_model: App, end_user: EndUser, c_id):
         """Delete a specific conversation."""
         app_mode = AppMode.value_of(app_model.mode)
-        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
+        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT}:
             raise NotChatAppError()
 
         conversation_id = str(c_id)
@@ -171,7 +171,7 @@ class ConversationRenameApi(Resource):
     def post(self, app_model: App, end_user: EndUser, c_id):
         """Rename a conversation or auto-generate a name."""
         app_mode = AppMode.value_of(app_model.mode)
-        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
+        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT}:
             raise NotChatAppError()
 
         conversation_id = str(c_id)
@@ -213,7 +213,7 @@ class ConversationVariablesApi(Resource):
         """
         # conversational variable only for chat app
         app_mode = AppMode.value_of(app_model.mode)
-        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
+        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT}:
             raise NotChatAppError()
 
         conversation_id = str(c_id)
@@ -252,7 +252,7 @@ class ConversationVariableDetailApi(Resource):
         The value must match the variable's expected type.
         """
         app_mode = AppMode.value_of(app_model.mode)
-        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
+        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT}:
             raise NotChatAppError()
 
         conversation_id = str(c_id)

api/controllers/service_api/app/message.py

@@ -53,7 +53,7 @@ class MessageListApi(Resource):
         Retrieves messages with pagination support using first_id.
         """
         app_mode = AppMode.value_of(app_model.mode)
-        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
+        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT}:
             raise NotChatAppError()
 
         query_args = MessageListQuery.model_validate(request.args.to_dict())
@@ -158,7 +158,7 @@ class MessageSuggestedApi(Resource):
         """
         message_id = str(message_id)
         app_mode = AppMode.value_of(app_model.mode)
-        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
+        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT}:
             raise NotChatAppError()
 
         try:

api/controllers/service_api/dataset/document.py

@@ -10,6 +10,7 @@ from sqlalchemy import desc, func, select
 from werkzeug.exceptions import Forbidden, NotFound
 
 import services
+from controllers.common.controller_schemas import DocumentBatchDownloadZipPayload
 from controllers.common.errors import (
     FilenameNotExistsError,
     FileTooLargeError,
@@ -100,15 +101,6 @@ class DocumentListQuery(BaseModel):
     status: str | None = Field(default=None, description="Document status filter")
 
 
-DOCUMENT_BATCH_DOWNLOAD_ZIP_MAX_DOCS = 100
-
-
-class DocumentBatchDownloadZipPayload(BaseModel):
-    """Request payload for bulk downloading uploaded documents as a ZIP archive."""
-
-    document_ids: list[UUID] = Field(..., min_length=1, max_length=DOCUMENT_BATCH_DOWNLOAD_ZIP_MAX_DOCS)
-
-
 register_enum_models(service_api_ns, RetrievalMethod)
 
 register_schema_models(

api/controllers/service_api/dataset/metadata.py

@@ -2,9 +2,9 @@ from typing import Literal
 
 from flask_login import current_user
 from flask_restx import marshal
-from pydantic import BaseModel
 from werkzeug.exceptions import NotFound
 
+from controllers.common.controller_schemas import MetadataUpdatePayload
 from controllers.common.schema import register_schema_model, register_schema_models
 from controllers.service_api import service_api_ns
 from controllers.service_api.wraps import DatasetApiResource, cloud_edition_billing_rate_limit_check
@@ -18,11 +18,6 @@ from services.entities.knowledge_entities.knowledge_entities import (
 )
 from services.metadata_service import MetadataService
 
-
-class MetadataUpdatePayload(BaseModel):
-    name: str
-
-
 register_schema_model(service_api_ns, MetadataUpdatePayload)
 register_schema_models(
     service_api_ns,

api/controllers/service_api/dataset/segment.py

@@ -8,6 +8,7 @@ from sqlalchemy import select
 from werkzeug.exceptions import NotFound
 
 from configs import dify_config
+from controllers.common.controller_schemas import ChildChunkCreatePayload, ChildChunkUpdatePayload
 from controllers.common.schema import register_schema_models
 from controllers.service_api import service_api_ns
 from controllers.service_api.app.error import ProviderNotInitializeError
@@ -69,20 +70,12 @@ class SegmentUpdatePayload(BaseModel):
     segment: SegmentUpdateArgs
 
 
-class ChildChunkCreatePayload(BaseModel):
-    content: str
-
-
 class ChildChunkListQuery(BaseModel):
     limit: int = Field(default=20, ge=1)
     keyword: str | None = None
     page: int = Field(default=1, ge=1)
 
 
-class ChildChunkUpdatePayload(BaseModel):
-    content: str
-
-
 register_schema_models(
     service_api_ns,
     SegmentCreatePayload,

api/controllers/web/message.py

@@ -3,10 +3,10 @@ from typing import Literal
 
 from flask import request
 from graphon.model_runtime.errors.invoke import InvokeError
-from pydantic import BaseModel, Field, TypeAdapter, field_validator
+from pydantic import BaseModel, Field, TypeAdapter
 from werkzeug.exceptions import InternalServerError, NotFound
 
-from controllers.common.controller_schemas import MessageFeedbackPayload
+from controllers.common.controller_schemas import MessageFeedbackPayload, MessageListQuery
 from controllers.common.schema import register_schema_models
 from controllers.web import web_ns
 from controllers.web.error import (
@@ -25,7 +25,6 @@ from core.errors.error import ModelCurrentlyNotSupportError, ProviderTokenNotIni
 from fields.conversation_fields import ResultResponse
 from fields.message_fields import SuggestedQuestionsResponse, WebMessageInfiniteScrollPagination, WebMessageListItem
 from libs import helper
-from libs.helper import uuid_value
 from models.enums import FeedbackRating
 from models.model import AppMode
 from services.app_generate_service import AppGenerateService
@@ -41,19 +40,6 @@ from services.message_service import MessageService
 logger = logging.getLogger(__name__)
 
 
-class MessageListQuery(BaseModel):
-    conversation_id: str = Field(description="Conversation UUID")
-    first_id: str | None = Field(default=None, description="First message ID for pagination")
-    limit: int = Field(default=20, ge=1, le=100, description="Number of messages to return (1-100)")
-
-    @field_validator("conversation_id", "first_id")
-    @classmethod
-    def validate_uuid(cls, value: str | None) -> str | None:
-        if value is None:
-            return value
-        return uuid_value(value)
-
-
 class MessageMoreLikeThisQuery(BaseModel):
     response_mode: Literal["blocking", "streaming"] = Field(
         description="Response mode",

api/core/agent/agent_app_runner.py

@@ -0,0 +1,399 @@
+import logging
+from collections.abc import Generator
+from copy import deepcopy
+from typing import Any, cast
+
+from core.agent.base_agent_runner import BaseAgentRunner
+from core.agent.entities import AgentEntity, AgentLog, AgentResult, ExecutionContext
+from core.agent.patterns.strategy_factory import StrategyFactory
+from core.app.apps.base_app_queue_manager import PublishFrom
+from core.app.entities.queue_entities import QueueAgentThoughtEvent, QueueMessageEndEvent, QueueMessageFileEvent
+from core.prompt.agent_history_prompt_transform import AgentHistoryPromptTransform
+from core.tools.__base.tool import Tool
+from core.tools.entities.tool_entities import ToolInvokeMeta
+from core.tools.tool_engine import ToolEngine
+from graphon.file import file_manager
+from graphon.model_runtime.entities import (
+    AssistantPromptMessage,
+    LLMResult,
+    LLMResultChunk,
+    LLMUsage,
+    PromptMessage,
+    PromptMessageContentType,
+    SystemPromptMessage,
+    TextPromptMessageContent,
+    UserPromptMessage,
+)
+from graphon.model_runtime.entities.message_entities import ImagePromptMessageContent, PromptMessageContentUnionTypes
+from graphon.model_runtime.entities.model_entities import ModelFeature
+from graphon.model_runtime.model_providers.__base.large_language_model import LargeLanguageModel
+from models.model import Message
+
+logger = logging.getLogger(__name__)
+
+
+class AgentAppRunner(BaseAgentRunner):
+
+    @property
+    def model_features(self) -> list[ModelFeature]:
+        llm_model = cast(LargeLanguageModel, self.model_instance.model_type_instance)
+        model_schema = llm_model.get_model_schema(self.model_instance.model_name, self.model_instance.credentials)
+        if not model_schema:
+            return []
+        return list(model_schema.features or [])
+
+    def build_execution_context(self) -> ExecutionContext:
+        return ExecutionContext(
+            user_id=self.user_id,
+            app_id=self.application_generate_entity.app_config.app_id,
+            conversation_id=self.conversation.id if self.conversation else None,
+            message_id=self.message.id if self.message else None,
+            tenant_id=self.tenant_id,
+        )
+    def _create_tool_invoke_hook(self, message: Message):
+        """
+        Create a tool invoke hook that uses ToolEngine.agent_invoke.
+        This hook handles file creation and returns proper meta information.
+        """
+        # Get trace manager from app generate entity
+        trace_manager = self.application_generate_entity.trace_manager
+
+        def tool_invoke_hook(
+            tool: Tool, tool_args: dict[str, Any], tool_name: str
+        ) -> tuple[str, list[str], ToolInvokeMeta]:
+            """Hook that uses agent_invoke for proper file and meta handling."""
+            tool_invoke_response, message_files, tool_invoke_meta = ToolEngine.agent_invoke(
+                tool=tool,
+                tool_parameters=tool_args,
+                user_id=self.user_id,
+                tenant_id=self.tenant_id,
+                message=message,
+                invoke_from=self.application_generate_entity.invoke_from,
+                agent_tool_callback=self.agent_callback,
+                trace_manager=trace_manager,
+                app_id=self.application_generate_entity.app_config.app_id,
+                message_id=message.id,
+                conversation_id=self.conversation.id,
+            )
+
+            # Publish files and track IDs
+            for message_file_id in message_files:
+                self.queue_manager.publish(
+                    QueueMessageFileEvent(message_file_id=message_file_id),
+                    PublishFrom.APPLICATION_MANAGER,
+                )
+                self._current_message_file_ids.append(message_file_id)
+
+            return tool_invoke_response, message_files, tool_invoke_meta
+
+        return tool_invoke_hook
+
+    def run(self, message: Message, query: str, **kwargs: Any) -> Generator[LLMResultChunk, None, None]:
+        """
+        Run Agent application
+        """
+        self.query = query
+        app_generate_entity = self.application_generate_entity
+
+        app_config = self.app_config
+        assert app_config is not None, "app_config is required"
+        assert app_config.agent is not None, "app_config.agent is required"
+
+        # convert tools into ModelRuntime Tool format
+        tool_instances, _ = self._init_prompt_tools()
+
+        assert app_config.agent
+
+        # Create tool invoke hook for agent_invoke
+        tool_invoke_hook = self._create_tool_invoke_hook(message)
+
+        # Get instruction for ReAct strategy
+        instruction = self.app_config.prompt_template.simple_prompt_template or ""
+
+        # Use factory to create appropriate strategy
+        strategy = StrategyFactory.create_strategy(
+            model_features=self.model_features,
+            model_instance=self.model_instance,
+            tools=list(tool_instances.values()),
+            files=list(self.files),
+            max_iterations=app_config.agent.max_iteration,
+            context=self.build_execution_context(),
+            agent_strategy=self.config.strategy,
+            tool_invoke_hook=tool_invoke_hook,
+            instruction=instruction,
+        )
+
+        # Initialize state variables
+        current_agent_thought_id: str | None = None
+        has_published_thought = False
+        current_tool_name: str | None = None
+        self._current_message_file_ids: list[str] = []
+
+        # organize prompt messages
+        prompt_messages = self._organize_prompt_messages()
+
+        # Run strategy
+        generator = strategy.run(
+            prompt_messages=prompt_messages,
+            model_parameters=app_generate_entity.model_conf.parameters,
+            stop=app_generate_entity.model_conf.stop,
+            stream=True,
+        )
+
+        # Consume generator and collect result
+        result: AgentResult | None = None
+        try:
+            while True:
+                try:
+                    output = next(generator)
+                except StopIteration as e:
+                    # Generator finished, get the return value
+                    result = e.value
+                    break
+
+                if isinstance(output, LLMResultChunk):
+                    # Handle LLM chunk
+                    if current_agent_thought_id and not has_published_thought:
+                        self.queue_manager.publish(
+                            QueueAgentThoughtEvent(agent_thought_id=current_agent_thought_id),
+                            PublishFrom.APPLICATION_MANAGER,
+                        )
+                        has_published_thought = True
+
+                    yield output
+
+                elif isinstance(output, AgentLog):
+                    # Handle Agent Log using log_type for type-safe dispatch
+                    if output.status == AgentLog.LogStatus.START:
+                        if output.log_type == AgentLog.LogType.ROUND:
+                            # Start of a new round
+                            message_file_ids: list[str] = []
+                            current_agent_thought_id = self.create_agent_thought(
+                                message_id=message.id,
+                                message="",
+                                tool_name="",
+                                tool_input="",
+                                messages_ids=message_file_ids,
+                            )
+                            has_published_thought = False
+
+                        elif output.log_type == AgentLog.LogType.TOOL_CALL:
+                            if current_agent_thought_id is None:
+                                continue
+
+                            # Tool call start - extract data from structured fields
+                            current_tool_name = output.data.get("tool_name", "")
+                            tool_input = output.data.get("tool_args", {})
+
+                            self.save_agent_thought(
+                                agent_thought_id=current_agent_thought_id,
+                                tool_name=current_tool_name,
+                                tool_input=tool_input,
+                                thought=None,
+                                observation=None,
+                                tool_invoke_meta=None,
+                                answer=None,
+                                messages_ids=[],
+                            )
+                            self.queue_manager.publish(
+                                QueueAgentThoughtEvent(agent_thought_id=current_agent_thought_id),
+                                PublishFrom.APPLICATION_MANAGER,
+                            )
+
+                    elif output.status == AgentLog.LogStatus.SUCCESS:
+                        if output.log_type == AgentLog.LogType.THOUGHT:
+                            if current_agent_thought_id is None:
+                                continue
+
+                            thought_text = output.data.get("thought")
+                            self.save_agent_thought(
+                                agent_thought_id=current_agent_thought_id,
+                                tool_name=None,
+                                tool_input=None,
+                                thought=thought_text,
+                                observation=None,
+                                tool_invoke_meta=None,
+                                answer=None,
+                                messages_ids=[],
+                            )
+                            self.queue_manager.publish(
+                                QueueAgentThoughtEvent(agent_thought_id=current_agent_thought_id),
+                                PublishFrom.APPLICATION_MANAGER,
+                            )
+
+                        elif output.log_type == AgentLog.LogType.TOOL_CALL:
+                            if current_agent_thought_id is None:
+                                continue
+
+                            # Tool call finished
+                            tool_output = output.data.get("output")
+                            # Get meta from strategy output (now properly populated)
+                            tool_meta = output.data.get("meta")
+
+                            # Wrap tool_meta with tool_name as key (required by agent_service)
+                            if tool_meta and current_tool_name:
+                                tool_meta = {current_tool_name: tool_meta}
+
+                            self.save_agent_thought(
+                                agent_thought_id=current_agent_thought_id,
+                                tool_name=None,
+                                tool_input=None,
+                                thought=None,
+                                observation=tool_output,
+                                tool_invoke_meta=tool_meta,
+                                answer=None,
+                                messages_ids=self._current_message_file_ids,
+                            )
+                            # Clear message file ids after saving
+                            self._current_message_file_ids = []
+                            current_tool_name = None
+
+                            self.queue_manager.publish(
+                                QueueAgentThoughtEvent(agent_thought_id=current_agent_thought_id),
+                                PublishFrom.APPLICATION_MANAGER,
+                            )
+
+                        elif output.log_type == AgentLog.LogType.ROUND:
+                            if current_agent_thought_id is None:
+                                continue
+
+                            # Round finished - save LLM usage and answer
+                            llm_usage = output.metadata.get(AgentLog.LogMetadata.LLM_USAGE)
+                            llm_result = output.data.get("llm_result")
+                            final_answer = output.data.get("final_answer")
+
+                            self.save_agent_thought(
+                                agent_thought_id=current_agent_thought_id,
+                                tool_name=None,
+                                tool_input=None,
+                                thought=llm_result,
+                                observation=None,
+                                tool_invoke_meta=None,
+                                answer=final_answer,
+                                messages_ids=[],
+                                llm_usage=llm_usage,
+                            )
+                            self.queue_manager.publish(
+                                QueueAgentThoughtEvent(agent_thought_id=current_agent_thought_id),
+                                PublishFrom.APPLICATION_MANAGER,
+                            )
+
+        except Exception:
+            # Re-raise any other exceptions
+            raise
+
+        # Process final result
+        if isinstance(result, AgentResult):
+            final_answer = result.text
+            usage = result.usage or LLMUsage.empty_usage()
+
+            # Publish end event
+            self.queue_manager.publish(
+                QueueMessageEndEvent(
+                    llm_result=LLMResult(
+                        model=self.model_instance.model_name,
+                        prompt_messages=prompt_messages,
+                        message=AssistantPromptMessage(content=final_answer),
+                        usage=usage,
+                        system_fingerprint="",
+                    )
+                ),
+                PublishFrom.APPLICATION_MANAGER,
+            )
+
+    def _init_system_message(self, prompt_template: str, prompt_messages: list[PromptMessage]) -> list[PromptMessage]:
+        """
+        Initialize system message
+        """
+        if not prompt_template:
+            return prompt_messages or []
+
+        prompt_messages = prompt_messages or []
+
+        if prompt_messages and isinstance(prompt_messages[0], SystemPromptMessage):
+            prompt_messages[0] = SystemPromptMessage(content=prompt_template)
+            return prompt_messages
+
+        if not prompt_messages:
+            return [SystemPromptMessage(content=prompt_template)]
+
+        prompt_messages.insert(0, SystemPromptMessage(content=prompt_template))
+        return prompt_messages
+
+    def _organize_user_query(self, query: str, prompt_messages: list[PromptMessage]) -> list[PromptMessage]:
+        """
+        Organize user query
+        """
+        if self.files:
+            # get image detail config
+            image_detail_config = (
+                self.application_generate_entity.file_upload_config.image_config.detail
+                if (
+                    self.application_generate_entity.file_upload_config
+                    and self.application_generate_entity.file_upload_config.image_config
+                )
+                else None
+            )
+            image_detail_config = image_detail_config or ImagePromptMessageContent.DETAIL.LOW
+
+            prompt_message_contents: list[PromptMessageContentUnionTypes] = []
+            for file in self.files:
+                prompt_message_contents.append(
+                    file_manager.to_prompt_message_content(
+                        file,
+                        image_detail_config=image_detail_config,
+                    )
+                )
+            prompt_message_contents.append(TextPromptMessageContent(data=query))
+
+            prompt_messages.append(UserPromptMessage(content=prompt_message_contents))
+        else:
+            prompt_messages.append(UserPromptMessage(content=query))
+
+        return prompt_messages
+
+    def _clear_user_prompt_image_messages(self, prompt_messages: list[PromptMessage]) -> list[PromptMessage]:
+        """
+        As for now, gpt supports both fc and vision at the first iteration.
+        We need to remove the image messages from the prompt messages at the first iteration.
+        """
+        prompt_messages = deepcopy(prompt_messages)
+
+        for prompt_message in prompt_messages:
+            if isinstance(prompt_message, UserPromptMessage):
+                if isinstance(prompt_message.content, list):
+                    prompt_message.content = "\n".join(
+                        [
+                            content.data
+                            if content.type == PromptMessageContentType.TEXT
+                            else "[image]"
+                            if content.type == PromptMessageContentType.IMAGE
+                            else "[file]"
+                            for content in prompt_message.content
+                        ]
+                    )
+
+        return prompt_messages
+
+    def _organize_prompt_messages(self):
+        # For ReAct strategy, use the agent prompt template
+        if self.config.strategy == AgentEntity.Strategy.CHAIN_OF_THOUGHT and self.config.prompt:
+            prompt_template = self.config.prompt.first_prompt
+        else:
+            prompt_template = self.app_config.prompt_template.simple_prompt_template or ""
+
+        self.history_prompt_messages = self._init_system_message(prompt_template, self.history_prompt_messages)
+        query_prompt_messages = self._organize_user_query(self.query or "", [])
+
+        self.history_prompt_messages = AgentHistoryPromptTransform(
+            model_config=self.model_config,
+            prompt_messages=[*query_prompt_messages, *self._current_thoughts],
+            history_messages=self.history_prompt_messages,
+            memory=self.memory,
+        ).get_prompt()
+
+        prompt_messages = [*self.history_prompt_messages, *query_prompt_messages, *self._current_thoughts]
+        if len(self._current_thoughts) != 0:
+            # clear messages after the first iteration
+            prompt_messages = self._clear_user_prompt_image_messages(prompt_messages)
+        return prompt_messages

api/core/agent/entities.py

@@ -1,3 +1,5 @@
+import uuid
+from collections.abc import Mapping
 from enum import StrEnum
 from typing import Any, Union
 
@@ -92,3 +94,79 @@ class AgentInvokeMessage(ToolInvokeMessage):
     """
 
     pass
+
+
+class ExecutionContext(BaseModel):
+    """Execution context containing trace and audit information.
+
+    Carries IDs and metadata needed for tracing, auditing, and correlation
+    but not part of the core business logic.
+    """
+
+    user_id: str | None = None
+    app_id: str | None = None
+    conversation_id: str | None = None
+    message_id: str | None = None
+    tenant_id: str | None = None
+
+    @classmethod
+    def create_minimal(cls, user_id: str | None = None) -> "ExecutionContext":
+        return cls(user_id=user_id)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "user_id": self.user_id,
+            "app_id": self.app_id,
+            "conversation_id": self.conversation_id,
+            "message_id": self.message_id,
+            "tenant_id": self.tenant_id,
+        }
+
+    def with_updates(self, **kwargs) -> "ExecutionContext":
+        data = self.to_dict()
+        data.update(kwargs)
+        return ExecutionContext(**{k: v for k, v in data.items() if k in ExecutionContext.model_fields})
+
+
+class AgentLog(BaseModel):
+    """Structured log entry for agent execution tracing."""
+
+    class LogType(StrEnum):
+        ROUND = "round"
+        THOUGHT = "thought"
+        TOOL_CALL = "tool_call"
+
+    class LogMetadata(StrEnum):
+        STARTED_AT = "started_at"
+        FINISHED_AT = "finished_at"
+        ELAPSED_TIME = "elapsed_time"
+        TOTAL_PRICE = "total_price"
+        TOTAL_TOKENS = "total_tokens"
+        PROVIDER = "provider"
+        CURRENCY = "currency"
+        LLM_USAGE = "llm_usage"
+        ICON = "icon"
+        ICON_DARK = "icon_dark"
+
+    class LogStatus(StrEnum):
+        START = "start"
+        ERROR = "error"
+        SUCCESS = "success"
+
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    label: str = Field(...)
+    log_type: LogType = Field(...)
+    parent_id: str | None = Field(default=None)
+    error: str | None = Field(default=None)
+    status: LogStatus = Field(...)
+    data: Mapping[str, Any] = Field(...)
+    metadata: Mapping[LogMetadata, Any] = Field(default={})
+
+
+class AgentResult(BaseModel):
+    """Agent execution result."""
+
+    text: str = Field(default="")
+    files: list[Any] = Field(default_factory=list)
+    usage: Any | None = Field(default=None)
+    finish_reason: str | None = Field(default=None)

api/core/agent/patterns/__init__.py

@@ -0,0 +1,19 @@
+"""Agent patterns module.
+
+This module provides different strategies for agent execution:
+- FunctionCallStrategy: Uses native function/tool calling
+- ReActStrategy: Uses ReAct (Reasoning + Acting) approach
+- StrategyFactory: Factory for creating strategies based on model features
+"""
+
+from .base import AgentPattern
+from .function_call import FunctionCallStrategy
+from .react import ReActStrategy
+from .strategy_factory import StrategyFactory
+
+__all__ = [
+    "AgentPattern",
+    "FunctionCallStrategy",
+    "ReActStrategy",
+    "StrategyFactory",
+]

api/core/agent/patterns/base.py

@@ -0,0 +1,506 @@
+"""Base class for agent strategies."""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Generator
+from typing import TYPE_CHECKING, Any
+
+from core.agent.entities import AgentLog, AgentResult, ExecutionContext
+from core.model_manager import ModelInstance
+from core.tools.entities.tool_entities import ToolInvokeMessage, ToolInvokeMeta
+from graphon.file import File
+from graphon.model_runtime.entities import (
+    AssistantPromptMessage,
+    LLMResult,
+    LLMResultChunk,
+    LLMResultChunkDelta,
+    PromptMessage,
+    PromptMessageTool,
+)
+from graphon.model_runtime.entities.llm_entities import LLMUsage
+from graphon.model_runtime.entities.message_entities import TextPromptMessageContent
+
+if TYPE_CHECKING:
+    from core.tools.__base.tool import Tool
+
+# Type alias for tool invoke hook
+# Returns: (response_content, message_file_ids, tool_invoke_meta)
+ToolInvokeHook = Callable[["Tool", dict[str, Any], str], tuple[str, list[str], ToolInvokeMeta]]
+
+
+class AgentPattern(ABC):
+    """Base class for agent execution strategies."""
+
+    def __init__(
+        self,
+        model_instance: ModelInstance,
+        tools: list[Tool],
+        context: ExecutionContext,
+        max_iterations: int = 10,
+        workflow_call_depth: int = 0,
+        files: list[File] = [],
+        tool_invoke_hook: ToolInvokeHook | None = None,
+    ):
+        """Initialize the agent strategy."""
+        self.model_instance = model_instance
+        self.tools = tools
+        self.context = context
+        self.max_iterations = min(max_iterations, 99)  # Cap at 99 iterations
+        self.workflow_call_depth = workflow_call_depth
+        self.files: list[File] = files
+        self.tool_invoke_hook = tool_invoke_hook
+
+    @abstractmethod
+    def run(
+        self,
+        prompt_messages: list[PromptMessage],
+        model_parameters: dict[str, Any],
+        stop: list[str] = [],
+        stream: bool = True,
+    ) -> Generator[LLMResultChunk | AgentLog, None, AgentResult]:
+        """Execute the agent strategy."""
+        pass
+
+    def _accumulate_usage(self, total_usage: dict[str, Any], delta_usage: LLMUsage) -> None:
+        """Accumulate LLM usage statistics."""
+        if not total_usage.get("usage"):
+            # Create a copy to avoid modifying the original
+            total_usage["usage"] = LLMUsage(
+                prompt_tokens=delta_usage.prompt_tokens,
+                prompt_unit_price=delta_usage.prompt_unit_price,
+                prompt_price_unit=delta_usage.prompt_price_unit,
+                prompt_price=delta_usage.prompt_price,
+                completion_tokens=delta_usage.completion_tokens,
+                completion_unit_price=delta_usage.completion_unit_price,
+                completion_price_unit=delta_usage.completion_price_unit,
+                completion_price=delta_usage.completion_price,
+                total_tokens=delta_usage.total_tokens,
+                total_price=delta_usage.total_price,
+                currency=delta_usage.currency,
+                latency=delta_usage.latency,
+            )
+        else:
+            current: LLMUsage = total_usage["usage"]
+            current.prompt_tokens += delta_usage.prompt_tokens
+            current.completion_tokens += delta_usage.completion_tokens
+            current.total_tokens += delta_usage.total_tokens
+            current.prompt_price += delta_usage.prompt_price
+            current.completion_price += delta_usage.completion_price
+            current.total_price += delta_usage.total_price
+
+    def _extract_content(self, content: Any) -> str:
+        """Extract text content from message content."""
+        if isinstance(content, list):
+            # Content items are PromptMessageContentUnionTypes
+            text_parts = []
+            for c in content:
+                # Check if it's a TextPromptMessageContent (which has data attribute)
+                if isinstance(c, TextPromptMessageContent):
+                    text_parts.append(c.data)
+            return "".join(text_parts)
+        return str(content)
+
+    def _has_tool_calls(self, chunk: LLMResultChunk) -> bool:
+        """Check if chunk contains tool calls."""
+        # LLMResultChunk always has delta attribute
+        return bool(chunk.delta.message and chunk.delta.message.tool_calls)
+
+    def _has_tool_calls_result(self, result: LLMResult) -> bool:
+        """Check if result contains tool calls (non-streaming)."""
+        # LLMResult always has message attribute
+        return bool(result.message and result.message.tool_calls)
+
+    def _extract_tool_calls(self, chunk: LLMResultChunk) -> list[tuple[str, str, dict[str, Any]]]:
+        """Extract tool calls from streaming chunk."""
+        tool_calls: list[tuple[str, str, dict[str, Any]]] = []
+        if chunk.delta.message and chunk.delta.message.tool_calls:
+            for tool_call in chunk.delta.message.tool_calls:
+                if tool_call.function:
+                    try:
+                        args = json.loads(tool_call.function.arguments) if tool_call.function.arguments else {}
+                    except json.JSONDecodeError:
+                        args = {}
+                    tool_calls.append((tool_call.id or "", tool_call.function.name, args))
+        return tool_calls
+
+    def _extract_tool_calls_result(self, result: LLMResult) -> list[tuple[str, str, dict[str, Any]]]:
+        """Extract tool calls from non-streaming result."""
+        tool_calls = []
+        if result.message and result.message.tool_calls:
+            for tool_call in result.message.tool_calls:
+                if tool_call.function:
+                    try:
+                        args = json.loads(tool_call.function.arguments) if tool_call.function.arguments else {}
+                    except json.JSONDecodeError:
+                        args = {}
+                    tool_calls.append((tool_call.id or "", tool_call.function.name, args))
+        return tool_calls
+
+    def _extract_text_from_message(self, message: PromptMessage) -> str:
+        """Extract text content from a prompt message."""
+        # PromptMessage always has content attribute
+        content = message.content
+        if isinstance(content, str):
+            return content
+        elif isinstance(content, list):
+            # Extract text from content list
+            text_parts = []
+            for item in content:
+                if isinstance(item, TextPromptMessageContent):
+                    text_parts.append(item.data)
+            return " ".join(text_parts)
+        return ""
+
+    def _get_tool_metadata(self, tool_instance: Tool) -> dict[AgentLog.LogMetadata, Any]:
+        """Get metadata for a tool including provider and icon info."""
+        from core.tools.tool_manager import ToolManager
+
+        metadata: dict[AgentLog.LogMetadata, Any] = {}
+        if tool_instance.entity and tool_instance.entity.identity:
+            identity = tool_instance.entity.identity
+            if identity.provider:
+                metadata[AgentLog.LogMetadata.PROVIDER] = identity.provider
+
+            # Get icon using ToolManager for proper URL generation
+            tenant_id = self.context.tenant_id
+            if tenant_id and identity.provider:
+                try:
+                    provider_type = tool_instance.tool_provider_type()
+                    icon = ToolManager.get_tool_icon(tenant_id, provider_type, identity.provider)
+                    if isinstance(icon, str):
+                        metadata[AgentLog.LogMetadata.ICON] = icon
+                    elif isinstance(icon, dict):
+                        # Handle icon dict with background/content or light/dark variants
+                        metadata[AgentLog.LogMetadata.ICON] = icon
+                except Exception:
+                    # Fallback to identity.icon if ToolManager fails
+                    if identity.icon:
+                        metadata[AgentLog.LogMetadata.ICON] = identity.icon
+            elif identity.icon:
+                metadata[AgentLog.LogMetadata.ICON] = identity.icon
+        return metadata
+
+    def _create_log(
+        self,
+        label: str,
+        log_type: AgentLog.LogType,
+        status: AgentLog.LogStatus,
+        data: dict[str, Any] | None = None,
+        parent_id: str | None = None,
+        extra_metadata: dict[AgentLog.LogMetadata, Any] | None = None,
+    ) -> AgentLog:
+        """Create a new AgentLog with standard metadata."""
+        metadata: dict[AgentLog.LogMetadata, Any] = {
+            AgentLog.LogMetadata.STARTED_AT: time.perf_counter(),
+        }
+        if extra_metadata:
+            metadata.update(extra_metadata)
+
+        return AgentLog(
+            label=label,
+            log_type=log_type,
+            status=status,
+            data=data or {},
+            parent_id=parent_id,
+            metadata=metadata,
+        )
+
+    def _finish_log(
+        self,
+        log: AgentLog,
+        data: dict[str, Any] | None = None,
+        usage: LLMUsage | None = None,
+    ) -> AgentLog:
+        """Finish an AgentLog by updating its status and metadata."""
+        log.status = AgentLog.LogStatus.SUCCESS
+
+        if data is not None:
+            log.data = data
+
+        # Calculate elapsed time
+        started_at = log.metadata.get(AgentLog.LogMetadata.STARTED_AT, time.perf_counter())
+        finished_at = time.perf_counter()
+
+        # Update metadata
+        log.metadata = {
+            **log.metadata,
+            AgentLog.LogMetadata.FINISHED_AT: finished_at,
+            # Calculate elapsed time in seconds
+            AgentLog.LogMetadata.ELAPSED_TIME: round(finished_at - started_at, 4),
+        }
+
+        # Add usage information if provided
+        if usage:
+            log.metadata.update(
+                {
+                    AgentLog.LogMetadata.TOTAL_PRICE: usage.total_price,
+                    AgentLog.LogMetadata.CURRENCY: usage.currency,
+                    AgentLog.LogMetadata.TOTAL_TOKENS: usage.total_tokens,
+                    AgentLog.LogMetadata.LLM_USAGE: usage,
+                }
+            )
+
+        return log
+
+    def _replace_file_references(self, tool_args: dict[str, Any]) -> dict[str, Any]:
+        """
+        Replace file references in tool arguments with actual File objects.
+
+        Args:
+            tool_args: Dictionary of tool arguments
+
+        Returns:
+            Updated tool arguments with file references replaced
+        """
+        # Process each argument in the dictionary
+        processed_args: dict[str, Any] = {}
+        for key, value in tool_args.items():
+            processed_args[key] = self._process_file_reference(value)
+        return processed_args
+
+    def _process_file_reference(self, data: Any) -> Any:
+        """
+        Recursively process data to replace file references.
+        Supports both single file [File: file_id] and multiple files [Files: file_id1, file_id2, ...].
+
+        Args:
+            data: The data to process (can be dict, list, str, or other types)
+
+        Returns:
+            Processed data with file references replaced
+        """
+        single_file_pattern = re.compile(r"^\[File:\s*([^\]]+)\]$")
+        multiple_files_pattern = re.compile(r"^\[Files:\s*([^\]]+)\]$")
+
+        if isinstance(data, dict):
+            # Process dictionary recursively
+            return {key: self._process_file_reference(value) for key, value in data.items()}
+        elif isinstance(data, list):
+            # Process list recursively
+            return [self._process_file_reference(item) for item in data]
+        elif isinstance(data, str):
+            # Check for single file pattern [File: file_id]
+            single_match = single_file_pattern.match(data.strip())
+            if single_match:
+                file_id = single_match.group(1).strip()
+                # Find the file in self.files
+                for file in self.files:
+                    if file.id and str(file.id) == file_id:
+                        return file
+                # If file not found, return original value
+                return data
+
+            # Check for multiple files pattern [Files: file_id1, file_id2, ...]
+            multiple_match = multiple_files_pattern.match(data.strip())
+            if multiple_match:
+                file_ids_str = multiple_match.group(1).strip()
+                # Split by comma and strip whitespace
+                file_ids = [fid.strip() for fid in file_ids_str.split(",")]
+
+                # Find all matching files
+                matched_files: list[File] = []
+                for file_id in file_ids:
+                    for file in self.files:
+                        if file.id and str(file.id) == file_id:
+                            matched_files.append(file)
+                            break
+
+                # Return list of files if any were found, otherwise return original
+                return matched_files or data
+
+            return data
+        else:
+            # Return other types as-is
+            return data
+
+    def _create_text_chunk(self, text: str, prompt_messages: list[PromptMessage]) -> LLMResultChunk:
+        """Create a text chunk for streaming."""
+        return LLMResultChunk(
+            model=self.model_instance.model_name,
+            prompt_messages=prompt_messages,
+            delta=LLMResultChunkDelta(
+                index=0,
+                message=AssistantPromptMessage(content=text),
+                usage=None,
+            ),
+            system_fingerprint="",
+        )
+
+    def _invoke_tool(
+        self,
+        tool_instance: Tool,
+        tool_args: dict[str, Any],
+        tool_name: str,
+    ) -> tuple[str, list[File], ToolInvokeMeta | None]:
+        """
+        Invoke a tool and collect its response.
+
+        Args:
+            tool_instance: The tool instance to invoke
+            tool_args: Tool arguments
+            tool_name: Name of the tool
+
+        Returns:
+            Tuple of (response_content, tool_files, tool_invoke_meta)
+        """
+        # Process tool_args to replace file references with actual File objects
+        tool_args = self._replace_file_references(tool_args)
+
+        # If a tool invoke hook is set, use it instead of generic_invoke
+        if self.tool_invoke_hook:
+            response_content, _, tool_invoke_meta = self.tool_invoke_hook(tool_instance, tool_args, tool_name)
+            # Note: message_file_ids are stored in DB, we don't convert them to File objects here
+            # The caller (AgentAppRunner) handles file publishing
+            return response_content, [], tool_invoke_meta
+
+        # Default: use generic_invoke for workflow scenarios
+        # Import here to avoid circular import
+        from core.tools.tool_engine import DifyWorkflowCallbackHandler, ToolEngine
+
+        tool_response = ToolEngine.generic_invoke(
+            tool=tool_instance,
+            tool_parameters=tool_args,
+            user_id=self.context.user_id or "",
+            workflow_tool_callback=DifyWorkflowCallbackHandler(),
+            workflow_call_depth=self.workflow_call_depth,
+            app_id=self.context.app_id,
+            conversation_id=self.context.conversation_id,
+            message_id=self.context.message_id,
+        )
+
+        # Collect response and files
+        response_content = ""
+        tool_files: list[File] = []
+
+        for response in tool_response:
+            if response.type == ToolInvokeMessage.MessageType.TEXT:
+                assert isinstance(response.message, ToolInvokeMessage.TextMessage)
+                response_content += response.message.text
+
+            elif response.type == ToolInvokeMessage.MessageType.LINK:
+                # Handle link messages
+                if isinstance(response.message, ToolInvokeMessage.TextMessage):
+                    response_content += f"[Link: {response.message.text}]"
+
+            elif response.type == ToolInvokeMessage.MessageType.IMAGE:
+                # Handle image URL messages
+                if isinstance(response.message, ToolInvokeMessage.TextMessage):
+                    response_content += f"[Image: {response.message.text}]"
+
+            elif response.type == ToolInvokeMessage.MessageType.IMAGE_LINK:
+                # Handle image link messages
+                if isinstance(response.message, ToolInvokeMessage.TextMessage):
+                    response_content += f"[Image: {response.message.text}]"
+
+            elif response.type == ToolInvokeMessage.MessageType.BINARY_LINK:
+                # Handle binary file link messages
+                if isinstance(response.message, ToolInvokeMessage.TextMessage):
+                    filename = response.meta.get("filename", "file") if response.meta else "file"
+                    response_content += f"[File: {filename} - {response.message.text}]"
+
+            elif response.type == ToolInvokeMessage.MessageType.JSON:
+                # Handle JSON messages
+                if isinstance(response.message, ToolInvokeMessage.JsonMessage):
+                    response_content += json.dumps(response.message.json_object, ensure_ascii=False, indent=2)
+
+            elif response.type == ToolInvokeMessage.MessageType.BLOB:
+                # Handle blob messages - convert to text representation
+                if isinstance(response.message, ToolInvokeMessage.BlobMessage):
+                    mime_type = (
+                        response.meta.get("mime_type", "application/octet-stream")
+                        if response.meta
+                        else "application/octet-stream"
+                    )
+                    size = len(response.message.blob)
+                    response_content += f"[Binary data: {mime_type}, size: {size} bytes]"
+
+            elif response.type == ToolInvokeMessage.MessageType.VARIABLE:
+                # Handle variable messages
+                if isinstance(response.message, ToolInvokeMessage.VariableMessage):
+                    var_name = response.message.variable_name
+                    var_value = response.message.variable_value
+                    if isinstance(var_value, str):
+                        response_content += var_value
+                    else:
+                        response_content += f"[Variable {var_name}: {json.dumps(var_value, ensure_ascii=False)}]"
+
+            elif response.type == ToolInvokeMessage.MessageType.BLOB_CHUNK:
+                # Handle blob chunk messages - these are parts of a larger blob
+                if isinstance(response.message, ToolInvokeMessage.BlobChunkMessage):
+                    response_content += f"[Blob chunk {response.message.sequence}: {len(response.message.blob)} bytes]"
+
+            elif response.type == ToolInvokeMessage.MessageType.RETRIEVER_RESOURCES:
+                # Handle retriever resources messages
+                if isinstance(response.message, ToolInvokeMessage.RetrieverResourceMessage):
+                    response_content += response.message.context
+
+            elif response.type == ToolInvokeMessage.MessageType.FILE:
+                # Extract file from meta
+                if response.meta and "file" in response.meta:
+                    file = response.meta["file"]
+                    if isinstance(file, File):
+                        # Check if file is for model or tool output
+                        if response.meta.get("target") == "self":
+                            # File is for model - add to files for next prompt
+                            self.files.append(file)
+                            response_content += f"File '{file.filename}' has been loaded into your context."
+                        else:
+                            # File is tool output
+                            tool_files.append(file)
+
+        return response_content, tool_files, None
+
+    def _validate_tool_args(self, tool_instance: Tool, tool_args: dict[str, Any]) -> str | None:
+        """Validate tool arguments against the tool's required parameters.
+
+        Checks that all required LLM-facing parameters are present and non-empty
+        before actual execution, preventing wasted tool invocations when the model
+        generates calls with missing arguments (e.g. empty ``{}``).
+
+        Returns:
+            Error message if validation fails, None if all required parameters are satisfied.
+        """
+        prompt_tool = tool_instance.to_prompt_message_tool()
+        required_params: list[str] = prompt_tool.parameters.get("required", [])
+
+        if not required_params:
+            return None
+
+        missing = [
+            p
+            for p in required_params
+            if p not in tool_args
+            or tool_args[p] is None
+            or (isinstance(tool_args[p], str) and not tool_args[p].strip())
+        ]
+
+        if not missing:
+            return None
+
+        return (
+            f"Missing required parameter(s): {', '.join(missing)}. "
+            f"Please provide all required parameters before calling this tool."
+        )
+
+    def _find_tool_by_name(self, tool_name: str) -> Tool | None:
+        """Find a tool instance by its name."""
+        for tool in self.tools:
+            if tool.entity.identity.name == tool_name:
+                return tool
+        return None
+
+    def _convert_tools_to_prompt_format(self) -> list[PromptMessageTool]:
+        """Convert tools to prompt message format."""
+        prompt_tools: list[PromptMessageTool] = []
+        for tool in self.tools:
+            prompt_tools.append(tool.to_prompt_message_tool())
+        return prompt_tools
+
+    def _update_usage_with_empty(self, llm_usage: dict[str, Any]) -> None:
+        """Initialize usage tracking with empty usage if not set."""
+        if "usage" not in llm_usage or llm_usage["usage"] is None:
+            llm_usage["usage"] = LLMUsage.empty_usage()

api/core/agent/patterns/function_call.py

@@ -0,0 +1,358 @@
+"""Function Call strategy implementation.
+
+Implements the Function Call agent pattern where the LLM uses native tool-calling
+capability to invoke tools. Includes pre-execution parameter validation that
+intercepts invalid calls (e.g. empty arguments) before they reach tool backends,
+and avoids counting purely-invalid rounds against the iteration budget.
+"""
+
+import json
+import logging
+from collections.abc import Generator
+from typing import Any, Union
+
+from core.agent.entities import AgentLog, AgentResult
+from core.tools.entities.tool_entities import ToolInvokeMeta
+from graphon.file import File
+from graphon.model_runtime.entities import (
+    AssistantPromptMessage,
+    LLMResult,
+    LLMResultChunk,
+    LLMResultChunkDelta,
+    LLMUsage,
+    PromptMessage,
+    PromptMessageTool,
+    ToolPromptMessage,
+)
+
+from .base import AgentPattern
+
+logger = logging.getLogger(__name__)
+
+
+class FunctionCallStrategy(AgentPattern):
+    """Function Call strategy using model's native tool calling capability."""
+
+    def run(
+        self,
+        prompt_messages: list[PromptMessage],
+        model_parameters: dict[str, Any],
+        stop: list[str] = [],
+        stream: bool = True,
+    ) -> Generator[LLMResultChunk | AgentLog, None, AgentResult]:
+        """Execute the function call agent strategy."""
+        # Convert tools to prompt format
+        prompt_tools: list[PromptMessageTool] = self._convert_tools_to_prompt_format()
+
+        # Initialize tracking
+        iteration_step: int = 1
+        max_iterations: int = self.max_iterations + 1
+        function_call_state: bool = True
+        total_usage: dict[str, LLMUsage | None] = {"usage": None}
+        messages: list[PromptMessage] = list(prompt_messages)  # Create mutable copy
+        final_text: str = ""
+        finish_reason: str | None = None
+        output_files: list[File] = []  # Track files produced by tools
+        # Consecutive rounds where ALL tool calls failed parameter validation.
+        # When this happens the round is "free" (iteration_step not incremented)
+        # up to a safety cap to prevent infinite loops.
+        consecutive_validation_failures: int = 0
+        max_validation_retries: int = 3
+
+        while function_call_state and iteration_step <= max_iterations:
+            function_call_state = False
+            round_log = self._create_log(
+                label=f"ROUND {iteration_step}",
+                log_type=AgentLog.LogType.ROUND,
+                status=AgentLog.LogStatus.START,
+                data={},
+            )
+            yield round_log
+            # On last iteration, remove tools to force final answer
+            current_tools: list[PromptMessageTool] = [] if iteration_step == max_iterations else prompt_tools
+            model_log = self._create_log(
+                label=f"{self.model_instance.model_name} Thought",
+                log_type=AgentLog.LogType.THOUGHT,
+                status=AgentLog.LogStatus.START,
+                data={},
+                parent_id=round_log.id,
+                extra_metadata={
+                    AgentLog.LogMetadata.PROVIDER: self.model_instance.provider,
+                },
+            )
+            yield model_log
+
+            # Track usage for this round only
+            round_usage: dict[str, LLMUsage | None] = {"usage": None}
+
+            # Invoke model
+            chunks: Union[Generator[LLMResultChunk, None, None], LLMResult] = self.model_instance.invoke_llm(
+                prompt_messages=messages,
+                model_parameters=model_parameters,
+                tools=current_tools,
+                stop=stop,
+                stream=stream,
+                callbacks=[],
+            )
+
+            # Process response
+            tool_calls, response_content, chunk_finish_reason = yield from self._handle_chunks(
+                chunks, round_usage, model_log
+            )
+            messages.append(self._create_assistant_message(response_content, tool_calls))
+
+            # Accumulate to total usage
+            round_usage_value = round_usage.get("usage")
+            if round_usage_value:
+                self._accumulate_usage(total_usage, round_usage_value)
+
+            # Update final text if no tool calls (this is likely the final answer)
+            if not tool_calls:
+                final_text = response_content
+
+            # Update finish reason
+            if chunk_finish_reason:
+                finish_reason = chunk_finish_reason
+
+            # Process tool calls
+            tool_outputs: dict[str, str] = {}
+            all_validation_errors: bool = True
+            if tool_calls:
+                function_call_state = True
+                # Execute tools (with pre-execution parameter validation)
+                for tool_call_id, tool_name, tool_args in tool_calls:
+                    tool_response, tool_files, _, is_validation_error = yield from self._handle_tool_call(
+                        tool_name, tool_args, tool_call_id, messages, round_log
+                    )
+                    tool_outputs[tool_name] = tool_response
+                    output_files.extend(tool_files)
+                    if not is_validation_error:
+                        all_validation_errors = False
+            else:
+                all_validation_errors = False
+
+            yield self._finish_log(
+                round_log,
+                data={
+                    "llm_result": response_content,
+                    "tool_calls": [
+                        {"name": tc[1], "args": tc[2], "output": tool_outputs.get(tc[1], "")} for tc in tool_calls
+                    ]
+                    if tool_calls
+                    else [],
+                    "final_answer": final_text if not function_call_state else None,
+                },
+                usage=round_usage.get("usage"),
+            )
+
+            # Skip iteration counter when every tool call in this round failed validation,
+            # giving the model a free retry — but cap retries to prevent infinite loops.
+            if tool_calls and all_validation_errors:
+                consecutive_validation_failures += 1
+                if consecutive_validation_failures >= max_validation_retries:
+                    logger.warning(
+                        "Agent hit %d consecutive validation-only rounds, forcing iteration increment",
+                        consecutive_validation_failures,
+                    )
+                    iteration_step += 1
+                    consecutive_validation_failures = 0
+                else:
+                    logger.info(
+                        "All tool calls failed validation (attempt %d/%d), not counting iteration",
+                        consecutive_validation_failures,
+                        max_validation_retries,
+                    )
+            else:
+                consecutive_validation_failures = 0
+                iteration_step += 1
+
+        # Return final result
+        from core.agent.entities import AgentResult
+
+        return AgentResult(
+            text=final_text,
+            files=output_files,
+            usage=total_usage.get("usage") or LLMUsage.empty_usage(),
+            finish_reason=finish_reason,
+        )
+
+    def _handle_chunks(
+        self,
+        chunks: Union[Generator[LLMResultChunk, None, None], LLMResult],
+        llm_usage: dict[str, LLMUsage | None],
+        start_log: AgentLog,
+    ) -> Generator[
+        LLMResultChunk | AgentLog,
+        None,
+        tuple[list[tuple[str, str, dict[str, Any]]], str, str | None],
+    ]:
+        """Handle LLM response chunks and extract tool calls and content.
+
+        Returns a tuple of (tool_calls, response_content, finish_reason).
+        """
+        tool_calls: list[tuple[str, str, dict[str, Any]]] = []
+        response_content: str = ""
+        finish_reason: str | None = None
+        if not isinstance(chunks, LLMResult):
+            # Streaming response
+            for chunk in chunks:
+                # Extract tool calls
+                if self._has_tool_calls(chunk):
+                    tool_calls.extend(self._extract_tool_calls(chunk))
+
+                # Extract content
+                if chunk.delta.message and chunk.delta.message.content:
+                    response_content += self._extract_content(chunk.delta.message.content)
+
+                # Track usage
+                if chunk.delta.usage:
+                    self._accumulate_usage(llm_usage, chunk.delta.usage)
+
+                # Capture finish reason
+                if chunk.delta.finish_reason:
+                    finish_reason = chunk.delta.finish_reason
+
+                yield chunk
+        else:
+            # Non-streaming response
+            result: LLMResult = chunks
+
+            if self._has_tool_calls_result(result):
+                tool_calls.extend(self._extract_tool_calls_result(result))
+
+            if result.message and result.message.content:
+                response_content += self._extract_content(result.message.content)
+
+            if result.usage:
+                self._accumulate_usage(llm_usage, result.usage)
+
+            # Convert to streaming format
+            yield LLMResultChunk(
+                model=result.model,
+                prompt_messages=result.prompt_messages,
+                delta=LLMResultChunkDelta(index=0, message=result.message, usage=result.usage),
+            )
+        yield self._finish_log(
+            start_log,
+            data={
+                "result": response_content,
+            },
+            usage=llm_usage.get("usage"),
+        )
+        return tool_calls, response_content, finish_reason
+
+    def _create_assistant_message(
+        self, content: str, tool_calls: list[tuple[str, str, dict[str, Any]]] | None = None
+    ) -> AssistantPromptMessage:
+        """Create assistant message with tool calls."""
+        if tool_calls is None:
+            return AssistantPromptMessage(content=content)
+        return AssistantPromptMessage(
+            content=content or "",
+            tool_calls=[
+                AssistantPromptMessage.ToolCall(
+                    id=tc[0],
+                    type="function",
+                    function=AssistantPromptMessage.ToolCall.ToolCallFunction(name=tc[1], arguments=json.dumps(tc[2])),
+                )
+                for tc in tool_calls
+            ],
+        )
+
+    def _handle_tool_call(
+        self,
+        tool_name: str,
+        tool_args: dict[str, Any],
+        tool_call_id: str,
+        messages: list[PromptMessage],
+        round_log: AgentLog,
+    ) -> Generator[AgentLog, None, tuple[str, list[File], ToolInvokeMeta | None, bool]]:
+        """Handle a single tool call and return response with files, meta, and validation status.
+
+        Validates required parameters before execution. When validation fails the tool
+        is never invoked — a synthetic error is fed back to the model so it can self-correct
+        without consuming a real iteration.
+
+        Returns:
+            (response_content, tool_files, tool_invoke_meta, is_validation_error).
+            ``is_validation_error`` is True when the call was rejected due to missing
+            required parameters, allowing the caller to skip the iteration counter.
+        """
+        # Find tool
+        tool_instance = self._find_tool_by_name(tool_name)
+        if not tool_instance:
+            raise ValueError(f"Tool {tool_name} not found")
+
+        # Get tool metadata (provider, icon, etc.)
+        tool_metadata = self._get_tool_metadata(tool_instance)
+
+        # Create tool call log
+        tool_call_log = self._create_log(
+            label=f"CALL {tool_name}",
+            log_type=AgentLog.LogType.TOOL_CALL,
+            status=AgentLog.LogStatus.START,
+            data={
+                "tool_call_id": tool_call_id,
+                "tool_name": tool_name,
+                "tool_args": tool_args,
+            },
+            parent_id=round_log.id,
+            extra_metadata=tool_metadata,
+        )
+        yield tool_call_log
+
+        # Validate required parameters before execution to avoid wasted invocations
+        validation_error = self._validate_tool_args(tool_instance, tool_args)
+        if validation_error:
+            tool_call_log.status = AgentLog.LogStatus.ERROR
+            tool_call_log.error = validation_error
+            tool_call_log.data = {**tool_call_log.data, "error": validation_error}
+            yield tool_call_log
+
+            messages.append(ToolPromptMessage(content=validation_error, tool_call_id=tool_call_id, name=tool_name))
+            return validation_error, [], None, True
+
+        # Invoke tool using base class method with error handling
+        try:
+            response_content, tool_files, tool_invoke_meta = self._invoke_tool(tool_instance, tool_args, tool_name)
+
+            yield self._finish_log(
+                tool_call_log,
+                data={
+                    **tool_call_log.data,
+                    "output": response_content,
+                    "files": len(tool_files),
+                    "meta": tool_invoke_meta.to_dict() if tool_invoke_meta else None,
+                },
+            )
+            final_content = response_content or "Tool executed successfully"
+            # Add tool response to messages
+            messages.append(
+                ToolPromptMessage(
+                    content=final_content,
+                    tool_call_id=tool_call_id,
+                    name=tool_name,
+                )
+            )
+            return response_content, tool_files, tool_invoke_meta, False
+        except Exception as e:
+            # Tool invocation failed, yield error log
+            error_message = str(e)
+            tool_call_log.status = AgentLog.LogStatus.ERROR
+            tool_call_log.error = error_message
+            tool_call_log.data = {
+                **tool_call_log.data,
+                "error": error_message,
+            }
+            yield tool_call_log
+
+            # Add error message to conversation
+            error_content = f"Tool execution failed: {error_message}"
+            messages.append(
+                ToolPromptMessage(
+                    content=error_content,
+                    tool_call_id=tool_call_id,
+                    name=tool_name,
+                )
+            )
+            return error_content, [], None, False

api/core/agent/patterns/react.py

@@ -0,0 +1,418 @@
+"""ReAct strategy implementation."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Generator
+from typing import TYPE_CHECKING, Any, Union
+
+from core.agent.entities import AgentLog, AgentResult, AgentScratchpadUnit, ExecutionContext
+from core.agent.output_parser.cot_output_parser import CotAgentOutputParser
+from core.model_manager import ModelInstance
+from graphon.file import File
+from graphon.model_runtime.entities import (
+    AssistantPromptMessage,
+    LLMResult,
+    LLMResultChunk,
+    LLMResultChunkDelta,
+    PromptMessage,
+    SystemPromptMessage,
+)
+
+from .base import AgentPattern, ToolInvokeHook
+
+if TYPE_CHECKING:
+    from core.tools.__base.tool import Tool
+
+
+class ReActStrategy(AgentPattern):
+    """ReAct strategy using reasoning and acting approach."""
+
+    def __init__(
+        self,
+        model_instance: ModelInstance,
+        tools: list[Tool],
+        context: ExecutionContext,
+        max_iterations: int = 10,
+        workflow_call_depth: int = 0,
+        files: list[File] = [],
+        tool_invoke_hook: ToolInvokeHook | None = None,
+        instruction: str = "",
+    ):
+        """Initialize the ReAct strategy with instruction support."""
+        super().__init__(
+            model_instance=model_instance,
+            tools=tools,
+            context=context,
+            max_iterations=max_iterations,
+            workflow_call_depth=workflow_call_depth,
+            files=files,
+            tool_invoke_hook=tool_invoke_hook,
+        )
+        self.instruction = instruction
+
+    def run(
+        self,
+        prompt_messages: list[PromptMessage],
+        model_parameters: dict[str, Any],
+        stop: list[str] = [],
+        stream: bool = True,
+    ) -> Generator[LLMResultChunk | AgentLog, None, AgentResult]:
+        """Execute the ReAct agent strategy."""
+        # Initialize tracking
+        agent_scratchpad: list[AgentScratchpadUnit] = []
+        iteration_step: int = 1
+        max_iterations: int = self.max_iterations + 1
+        react_state: bool = True
+        total_usage: dict[str, Any] = {"usage": None}
+        output_files: list[File] = []  # Track files produced by tools
+        final_text: str = ""
+        finish_reason: str | None = None
+
+        # Add "Observation" to stop sequences
+        if "Observation" not in stop:
+            stop = stop.copy()
+            stop.append("Observation")
+
+        while react_state and iteration_step <= max_iterations:
+            react_state = False
+            round_log = self._create_log(
+                label=f"ROUND {iteration_step}",
+                log_type=AgentLog.LogType.ROUND,
+                status=AgentLog.LogStatus.START,
+                data={},
+            )
+            yield round_log
+
+            # Build prompt with/without tools based on iteration
+            include_tools = iteration_step < max_iterations
+            current_messages = self._build_prompt_with_react_format(
+                prompt_messages, agent_scratchpad, include_tools, self.instruction
+            )
+
+            model_log = self._create_log(
+                label=f"{self.model_instance.model_name} Thought",
+                log_type=AgentLog.LogType.THOUGHT,
+                status=AgentLog.LogStatus.START,
+                data={},
+                parent_id=round_log.id,
+                extra_metadata={
+                    AgentLog.LogMetadata.PROVIDER: self.model_instance.provider,
+                },
+            )
+            yield model_log
+
+            # Track usage for this round only
+            round_usage: dict[str, Any] = {"usage": None}
+
+            # Use current messages directly (files are handled by base class if needed)
+            messages_to_use = current_messages
+
+            # Invoke model
+            chunks: Union[Generator[LLMResultChunk, None, None], LLMResult] = self.model_instance.invoke_llm(
+                prompt_messages=messages_to_use,
+                model_parameters=model_parameters,
+                stop=stop,
+                stream=stream,
+                callbacks=[],
+            )
+
+            # Process response
+            scratchpad, chunk_finish_reason = yield from self._handle_chunks(
+                chunks, round_usage, model_log, current_messages
+            )
+            agent_scratchpad.append(scratchpad)
+
+            # Accumulate to total usage
+            round_usage_value = round_usage.get("usage")
+            if round_usage_value:
+                self._accumulate_usage(total_usage, round_usage_value)
+
+            # Update finish reason
+            if chunk_finish_reason:
+                finish_reason = chunk_finish_reason
+
+            # Check if we have an action to execute
+            if scratchpad.action and scratchpad.action.action_name.lower() != "final answer":
+                react_state = True
+                # Execute tool
+                observation, tool_files = yield from self._handle_tool_call(
+                    scratchpad.action, current_messages, round_log
+                )
+                scratchpad.observation = observation
+                # Track files produced by tools
+                output_files.extend(tool_files)
+
+                # Add observation to scratchpad for display
+                yield self._create_text_chunk(f"\nObservation: {observation}\n", current_messages)
+            else:
+                # Extract final answer
+                if scratchpad.action and scratchpad.action.action_input:
+                    final_answer = scratchpad.action.action_input
+                    if isinstance(final_answer, dict):
+                        final_answer = json.dumps(final_answer, ensure_ascii=False)
+                    final_text = str(final_answer)
+                elif scratchpad.thought:
+                    # If no action but we have thought, use thought as final answer
+                    final_text = scratchpad.thought
+
+            yield self._finish_log(
+                round_log,
+                data={
+                    "thought": scratchpad.thought,
+                    "action": scratchpad.action_str if scratchpad.action else None,
+                    "observation": scratchpad.observation or None,
+                    "final_answer": final_text if not react_state else None,
+                },
+                usage=round_usage.get("usage"),
+            )
+            iteration_step += 1
+
+        # Return final result
+
+        from core.agent.entities import AgentResult
+
+        return AgentResult(
+            text=final_text, files=output_files, usage=total_usage.get("usage"), finish_reason=finish_reason
+        )
+
+    def _build_prompt_with_react_format(
+        self,
+        original_messages: list[PromptMessage],
+        agent_scratchpad: list[AgentScratchpadUnit],
+        include_tools: bool = True,
+        instruction: str = "",
+    ) -> list[PromptMessage]:
+        """Build prompt messages with ReAct format."""
+        # Copy messages to avoid modifying original
+        messages = list(original_messages)
+
+        # Find and update the system prompt that should already exist
+        system_prompt_found = False
+        for i, msg in enumerate(messages):
+            if isinstance(msg, SystemPromptMessage):
+                system_prompt_found = True
+                # The system prompt from frontend already has the template, just replace placeholders
+
+                # Format tools
+                tools_str = ""
+                tool_names = []
+                if include_tools and self.tools:
+                    # Convert tools to prompt message tools format
+                    prompt_tools = [tool.to_prompt_message_tool() for tool in self.tools]
+                    tool_names = [tool.name for tool in prompt_tools]
+
+                    # Format tools as JSON for comprehensive information
+                    from graphon.model_runtime.utils.encoders import jsonable_encoder
+
+                    tools_str = json.dumps(jsonable_encoder(prompt_tools), indent=2)
+                    tool_names_str = ", ".join(f'"{name}"' for name in tool_names)
+                else:
+                    tools_str = "No tools available"
+                    tool_names_str = ""
+
+                # Replace placeholders in the existing system prompt
+                updated_content = msg.content
+                assert isinstance(updated_content, str)
+                updated_content = updated_content.replace("{{instruction}}", instruction)
+                updated_content = updated_content.replace("{{tools}}", tools_str)
+                updated_content = updated_content.replace("{{tool_names}}", tool_names_str)
+
+                # Create new SystemPromptMessage with updated content
+                messages[i] = SystemPromptMessage(content=updated_content)
+                break
+
+        # If no system prompt found, that's unexpected but add scratchpad anyway
+        if not system_prompt_found:
+            # This shouldn't happen if frontend is working correctly
+            pass
+
+        # Format agent scratchpad
+        scratchpad_str = ""
+        if agent_scratchpad:
+            scratchpad_parts: list[str] = []
+            for unit in agent_scratchpad:
+                if unit.thought:
+                    scratchpad_parts.append(f"Thought: {unit.thought}")
+                if unit.action_str:
+                    scratchpad_parts.append(f"Action:\n```\n{unit.action_str}\n```")
+                if unit.observation:
+                    scratchpad_parts.append(f"Observation: {unit.observation}")
+            scratchpad_str = "\n".join(scratchpad_parts)
+
+        # If there's a scratchpad, append it to the last message
+        if scratchpad_str:
+            messages.append(AssistantPromptMessage(content=scratchpad_str))
+
+        return messages
+
+    def _handle_chunks(
+        self,
+        chunks: Union[Generator[LLMResultChunk, None, None], LLMResult],
+        llm_usage: dict[str, Any],
+        model_log: AgentLog,
+        current_messages: list[PromptMessage],
+    ) -> Generator[
+        LLMResultChunk | AgentLog,
+        None,
+        tuple[AgentScratchpadUnit, str | None],
+    ]:
+        """Handle LLM response chunks and extract action/thought.
+
+        Returns a tuple of (scratchpad_unit, finish_reason).
+        """
+        usage_dict: dict[str, Any] = {}
+
+        # Convert non-streaming to streaming format if needed
+        if isinstance(chunks, LLMResult):
+            result = chunks
+
+            def result_to_chunks() -> Generator[LLMResultChunk, None, None]:
+                yield LLMResultChunk(
+                    model=result.model,
+                    prompt_messages=result.prompt_messages,
+                    delta=LLMResultChunkDelta(
+                        index=0,
+                        message=result.message,
+                        usage=result.usage,
+                        finish_reason=None,
+                    ),
+                    system_fingerprint=result.system_fingerprint or "",
+                )
+
+            streaming_chunks = result_to_chunks()
+        else:
+            streaming_chunks = chunks
+
+        react_chunks = CotAgentOutputParser.handle_react_stream_output(streaming_chunks, usage_dict)
+
+        # Initialize scratchpad unit
+        scratchpad = AgentScratchpadUnit(
+            agent_response="",
+            thought="",
+            action_str="",
+            observation="",
+            action=None,
+        )
+
+        finish_reason: str | None = None
+
+        # Process chunks
+        for chunk in react_chunks:
+            if isinstance(chunk, AgentScratchpadUnit.Action):
+                # Action detected
+                action_str = json.dumps(chunk.model_dump())
+                scratchpad.agent_response = (scratchpad.agent_response or "") + action_str
+                scratchpad.action_str = action_str
+                scratchpad.action = chunk
+
+                yield self._create_text_chunk(json.dumps(chunk.model_dump()), current_messages)
+            else:
+                # Text chunk
+                chunk_text = str(chunk)
+                scratchpad.agent_response = (scratchpad.agent_response or "") + chunk_text
+                scratchpad.thought = (scratchpad.thought or "") + chunk_text
+
+                yield self._create_text_chunk(chunk_text, current_messages)
+
+        # Update usage
+        if usage_dict.get("usage"):
+            if llm_usage.get("usage"):
+                self._accumulate_usage(llm_usage, usage_dict["usage"])
+            else:
+                llm_usage["usage"] = usage_dict["usage"]
+
+        # Clean up thought
+        scratchpad.thought = (scratchpad.thought or "").strip() or "I am thinking about how to help you"
+
+        # Finish model log
+        yield self._finish_log(
+            model_log,
+            data={
+                "thought": scratchpad.thought,
+                "action": scratchpad.action_str if scratchpad.action else None,
+            },
+            usage=llm_usage.get("usage"),
+        )
+
+        return scratchpad, finish_reason
+
+    def _handle_tool_call(
+        self,
+        action: AgentScratchpadUnit.Action,
+        prompt_messages: list[PromptMessage],
+        round_log: AgentLog,
+    ) -> Generator[AgentLog, None, tuple[str, list[File]]]:
+        """Handle tool call and return observation with files."""
+        tool_name = action.action_name
+        tool_args: dict[str, Any] | str = action.action_input
+
+        # Find tool instance first to get metadata
+        tool_instance = self._find_tool_by_name(tool_name)
+        tool_metadata = self._get_tool_metadata(tool_instance) if tool_instance else {}
+
+        # Start tool log with tool metadata
+        tool_log = self._create_log(
+            label=f"CALL {tool_name}",
+            log_type=AgentLog.LogType.TOOL_CALL,
+            status=AgentLog.LogStatus.START,
+            data={
+                "tool_name": tool_name,
+                "tool_args": tool_args,
+            },
+            parent_id=round_log.id,
+            extra_metadata=tool_metadata,
+        )
+        yield tool_log
+
+        if not tool_instance:
+            # Finish tool log with error
+            yield self._finish_log(
+                tool_log,
+                data={
+                    **tool_log.data,
+                    "error": f"Tool {tool_name} not found",
+                },
+            )
+            return f"Tool {tool_name} not found", []
+
+        # Ensure tool_args is a dict
+        tool_args_dict: dict[str, Any]
+        if isinstance(tool_args, str):
+            try:
+                tool_args_dict = json.loads(tool_args)
+            except json.JSONDecodeError:
+                tool_args_dict = {"input": tool_args}
+        elif not isinstance(tool_args, dict):
+            tool_args_dict = {"input": str(tool_args)}
+        else:
+            tool_args_dict = tool_args
+
+        # Invoke tool using base class method with error handling
+        try:
+            response_content, tool_files, tool_invoke_meta = self._invoke_tool(tool_instance, tool_args_dict, tool_name)
+
+            # Finish tool log
+            yield self._finish_log(
+                tool_log,
+                data={
+                    **tool_log.data,
+                    "output": response_content,
+                    "files": len(tool_files),
+                    "meta": tool_invoke_meta.to_dict() if tool_invoke_meta else None,
+                },
+            )
+
+            return response_content or "Tool executed successfully", tool_files
+        except Exception as e:
+            # Tool invocation failed, yield error log
+            error_message = str(e)
+            tool_log.status = AgentLog.LogStatus.ERROR
+            tool_log.error = error_message
+            tool_log.data = {
+                **tool_log.data,
+                "error": error_message,
+            }
+            yield tool_log
+
+            return f"Tool execution failed: {error_message}", []

api/core/agent/patterns/strategy_factory.py

@@ -0,0 +1,108 @@
+"""Strategy factory for creating agent strategies."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from core.agent.entities import AgentEntity, ExecutionContext
+from core.model_manager import ModelInstance
+from graphon.file.models import File
+from graphon.model_runtime.entities.model_entities import ModelFeature
+
+from .base import AgentPattern, ToolInvokeHook
+from .function_call import FunctionCallStrategy
+from .react import ReActStrategy
+
+if TYPE_CHECKING:
+    from core.tools.__base.tool import Tool
+
+
+class StrategyFactory:
+    """Factory for creating agent strategies based on model features."""
+
+    # Tool calling related features
+    TOOL_CALL_FEATURES = {ModelFeature.TOOL_CALL, ModelFeature.MULTI_TOOL_CALL, ModelFeature.STREAM_TOOL_CALL}
+
+    @staticmethod
+    def create_strategy(
+        model_features: list[ModelFeature],
+        model_instance: ModelInstance,
+        context: ExecutionContext,
+        tools: list[Tool],
+        files: list[File],
+        max_iterations: int = 10,
+        workflow_call_depth: int = 0,
+        agent_strategy: AgentEntity.Strategy | None = None,
+        tool_invoke_hook: ToolInvokeHook | None = None,
+        instruction: str = "",
+    ) -> AgentPattern:
+        """
+        Create an appropriate strategy based on model features.
+
+        Args:
+            model_features: List of model features/capabilities
+            model_instance: Model instance to use
+            context: Execution context containing trace/audit information
+            tools: Available tools
+            files: Available files
+            max_iterations: Maximum iterations for the strategy
+            workflow_call_depth: Depth of workflow calls
+            agent_strategy: Optional explicit strategy override
+            tool_invoke_hook: Optional hook for custom tool invocation (e.g., agent_invoke)
+            instruction: Optional instruction for ReAct strategy
+
+        Returns:
+            AgentStrategy instance
+        """
+
+        # If explicit strategy is provided and it's Function Calling, try to use it if supported
+        if agent_strategy == AgentEntity.Strategy.FUNCTION_CALLING:
+            if set(model_features) & StrategyFactory.TOOL_CALL_FEATURES:
+                return FunctionCallStrategy(
+                    model_instance=model_instance,
+                    context=context,
+                    tools=tools,
+                    files=files,
+                    max_iterations=max_iterations,
+                    workflow_call_depth=workflow_call_depth,
+                    tool_invoke_hook=tool_invoke_hook,
+                )
+            # Fallback to ReAct if FC is requested but not supported
+
+        # If explicit strategy is Chain of Thought (ReAct)
+        if agent_strategy == AgentEntity.Strategy.CHAIN_OF_THOUGHT:
+            return ReActStrategy(
+                model_instance=model_instance,
+                context=context,
+                tools=tools,
+                files=files,
+                max_iterations=max_iterations,
+                workflow_call_depth=workflow_call_depth,
+                tool_invoke_hook=tool_invoke_hook,
+                instruction=instruction,
+            )
+
+        # Default auto-selection logic
+        if set(model_features) & StrategyFactory.TOOL_CALL_FEATURES:
+            # Model supports native function calling
+            return FunctionCallStrategy(
+                model_instance=model_instance,
+                context=context,
+                tools=tools,
+                files=files,
+                max_iterations=max_iterations,
+                workflow_call_depth=workflow_call_depth,
+                tool_invoke_hook=tool_invoke_hook,
+            )
+        else:
+            # Use ReAct strategy for models without function calling
+            return ReActStrategy(
+                model_instance=model_instance,
+                context=context,
+                tools=tools,
+                files=files,
+                max_iterations=max_iterations,
+                workflow_call_depth=workflow_call_depth,
+                tool_invoke_hook=tool_invoke_hook,
+                instruction=instruction,
+            )

api/core/app/apps/advanced_chat/app_generator.py

@@ -177,6 +177,14 @@ class AdvancedChatAppGenerator(MessageBasedAppGenerator):
                 # always enable retriever resource in debugger mode
                 app_config.additional_features.show_retrieve_source = True  # type: ignore
 
+            # Resolve parent_message_id for thread continuity
+            if invoke_from == InvokeFrom.SERVICE_API:
+                parent_message_id: str | None = UUID_NIL
+            else:
+                parent_message_id = args.get("parent_message_id")
+                if not parent_message_id and conversation:
+                    parent_message_id = self._resolve_latest_message_id(conversation.id)
+
             # init application generate entity
             application_generate_entity = AdvancedChatAppGenerateEntity(
                 task_id=str(uuid.uuid4()),
@@ -188,7 +196,7 @@ class AdvancedChatAppGenerator(MessageBasedAppGenerator):
                 ),
                 query=query,
                 files=list(file_objs),
-                parent_message_id=args.get("parent_message_id") if invoke_from != InvokeFrom.SERVICE_API else UUID_NIL,
+                parent_message_id=parent_message_id,
                 user_id=user.id,
                 stream=streaming,
                 invoke_from=invoke_from,
@@ -689,3 +697,17 @@ class AdvancedChatAppGenerator(MessageBasedAppGenerator):
             else:
                 logger.exception("Failed to process generate task pipeline, conversation_id: %s", conversation.id)
                 raise e
+
+    @staticmethod
+    def _resolve_latest_message_id(conversation_id: str) -> str | None:
+        """Auto-resolve parent_message_id to the latest message when client doesn't provide one."""
+        from sqlalchemy import select
+
+        stmt = (
+            select(Message.id)
+            .where(Message.conversation_id == conversation_id)
+            .order_by(Message.created_at.desc())
+            .limit(1)
+        )
+        latest_id = db.session.scalar(stmt)
+        return str(latest_id) if latest_id else None

api/core/app/apps/agent_chat/app_runner.py

@@ -1,15 +1,12 @@
 import logging
 from typing import cast
 
-from graphon.model_runtime.entities.llm_entities import LLMMode
-from graphon.model_runtime.entities.model_entities import ModelFeature, ModelPropertyKey
+from graphon.model_runtime.entities.model_entities import ModelFeature
 from graphon.model_runtime.model_providers.__base.large_language_model import LargeLanguageModel
 from sqlalchemy import select
 
-from core.agent.cot_chat_agent_runner import CotChatAgentRunner
-from core.agent.cot_completion_agent_runner import CotCompletionAgentRunner
+from core.agent.agent_app_runner import AgentAppRunner
 from core.agent.entities import AgentEntity
-from core.agent.fc_agent_runner import FunctionCallAgentRunner
 from core.app.apps.agent_chat.app_config_manager import AgentChatAppConfig
 from core.app.apps.base_app_queue_manager import AppQueueManager, PublishFrom
 from core.app.apps.base_app_runner import AppRunner
@@ -192,24 +189,8 @@ class AgentChatAppRunner(AppRunner):
         message_result = db.session.scalar(msg_stmt)
         if message_result is None:
             raise ValueError("Message not found")
-        db.session.close()
 
-        runner_cls: type[FunctionCallAgentRunner] | type[CotChatAgentRunner] | type[CotCompletionAgentRunner]
-        # start agent runner
-        if agent_entity.strategy == AgentEntity.Strategy.CHAIN_OF_THOUGHT:
-            # check LLM mode
-            if model_schema.model_properties.get(ModelPropertyKey.MODE) == LLMMode.CHAT:
-                runner_cls = CotChatAgentRunner
-            elif model_schema.model_properties.get(ModelPropertyKey.MODE) == LLMMode.COMPLETION:
-                runner_cls = CotCompletionAgentRunner
-            else:
-                raise ValueError(f"Invalid LLM mode: {model_schema.model_properties.get(ModelPropertyKey.MODE)}")
-        elif agent_entity.strategy == AgentEntity.Strategy.FUNCTION_CALLING:
-            runner_cls = FunctionCallAgentRunner
-        else:
-            raise ValueError(f"Invalid agent strategy: {agent_entity.strategy}")
-
-        runner = runner_cls(
+        runner = AgentAppRunner(
             tenant_id=app_config.tenant_id,
             application_generate_entity=application_generate_entity,
             conversation=conversation_result,

api/core/app/apps/common/legacy_response_adapter.py

@@ -0,0 +1,53 @@
+"""Legacy Response Adapter for transparent upgrade.
+
+When old apps (chat/completion/agent-chat) run through the Agent V2
+workflow engine via transparent upgrade, the SSE events are in workflow
+format (workflow_started, node_started, etc.). This adapter filters out
+workflow-specific events and passes through only the events that old
+clients expect (message, message_end, etc.).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Generator
+
+logger = logging.getLogger(__name__)
+
+WORKFLOW_ONLY_EVENTS = frozenset({
+    "workflow_started",
+    "workflow_finished",
+    "node_started",
+    "node_finished",
+    "iteration_started",
+    "iteration_next",
+    "iteration_completed",
+})
+
+
+def adapt_workflow_stream_for_legacy(
+    stream: Generator[str, None, None],
+) -> Generator[str, None, None]:
+    """Filter workflow-specific SSE events from a streaming response.
+
+    Passes through message, message_end, agent_log, error, ping events.
+    Suppresses workflow_started, workflow_finished, node_started, node_finished.
+
+    This makes the SSE stream look more like what old easy-UI apps produce,
+    while still carrying the actual LLM response content.
+    """
+    for chunk in stream:
+        if not chunk or not chunk.strip():
+            yield chunk
+            continue
+
+        try:
+            if chunk.startswith("data: "):
+                data = json.loads(chunk[6:])
+                event = data.get("event", "")
+                if event in WORKFLOW_ONLY_EVENTS:
+                    continue
+            yield chunk
+        except (json.JSONDecodeError, TypeError):
+            yield chunk

api/core/app/apps/workflow_app_runner.py

@@ -146,8 +146,6 @@ class WorkflowBasedAppRunner:
             call_depth=0,
         )
 
-        # Use the provided graph_runtime_state for consistent state management
-
         node_factory = DifyNodeFactory.from_graph_init_context(
             graph_init_context=graph_init_context,
             graph_runtime_state=graph_runtime_state,

api/core/app/entities/llm_generation_entities.py

@@ -0,0 +1,72 @@
+"""
+LLM Generation Detail entities.
+
+Defines the structure for storing and transmitting LLM generation details
+including reasoning content, tool calls, and their sequence.
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class ContentSegment(BaseModel):
+    """Represents a content segment in the generation sequence."""
+
+    type: Literal["content"] = "content"
+    start: int = Field(..., description="Start position in the text")
+    end: int = Field(..., description="End position in the text")
+
+
+class ReasoningSegment(BaseModel):
+    """Represents a reasoning segment in the generation sequence."""
+
+    type: Literal["reasoning"] = "reasoning"
+    index: int = Field(..., description="Index into reasoning_content array")
+
+
+class ToolCallSegment(BaseModel):
+    """Represents a tool call segment in the generation sequence."""
+
+    type: Literal["tool_call"] = "tool_call"
+    index: int = Field(..., description="Index into tool_calls array")
+
+
+SequenceSegment = ContentSegment | ReasoningSegment | ToolCallSegment
+
+
+class ToolCallDetail(BaseModel):
+    """Represents a tool call with its arguments and result."""
+
+    id: str = Field(default="", description="Unique identifier for the tool call")
+    name: str = Field(..., description="Name of the tool")
+    arguments: str = Field(default="", description="JSON string of tool arguments")
+    result: str = Field(default="", description="Result from the tool execution")
+    elapsed_time: float | None = Field(default=None, description="Elapsed time in seconds")
+    icon: str | dict | None = Field(default=None, description="Icon of the tool")
+    icon_dark: str | dict | None = Field(default=None, description="Dark theme icon of the tool")
+
+
+class LLMGenerationDetailData(BaseModel):
+    """
+    Domain model for LLM generation detail.
+
+    Contains the structured data for reasoning content, tool calls,
+    and their display sequence.
+    """
+
+    reasoning_content: list[str] = Field(default_factory=list, description="List of reasoning segments")
+    tool_calls: list[ToolCallDetail] = Field(default_factory=list, description="List of tool call details")
+    sequence: list[SequenceSegment] = Field(default_factory=list, description="Display order of segments")
+
+    def is_empty(self) -> bool:
+        """Check if there's any meaningful generation detail."""
+        return not self.reasoning_content and not self.tool_calls
+
+    def to_response_dict(self) -> dict:
+        """Convert to dictionary for API response."""
+        return {
+            "reasoning_content": self.reasoning_content,
+            "tool_calls": [tc.model_dump() for tc in self.tool_calls],
+            "sequence": [seg.model_dump() for seg in self.sequence],
+        }

api/core/helper/creators.py

@@ -0,0 +1,75 @@
+"""
+Helper module for Creators Platform integration.
+
+Provides functionality to upload DSL files to the Creators Platform
+and generate redirect URLs with OAuth authorization codes.
+"""
+
+import logging
+from urllib.parse import urlencode
+
+import httpx
+from yarl import URL
+
+from configs import dify_config
+
+logger = logging.getLogger(__name__)
+
+creators_platform_api_url = URL(str(dify_config.CREATORS_PLATFORM_API_URL))
+
+
+def upload_dsl(dsl_file_bytes: bytes, filename: str = "template.yaml") -> str:
+    """Upload a DSL file to the Creators Platform anonymous upload endpoint.
+
+    Args:
+        dsl_file_bytes: Raw bytes of the DSL file (YAML or ZIP).
+        filename: Original filename for the upload.
+
+    Returns:
+        The claim_code string used to retrieve the DSL later.
+
+    Raises:
+        httpx.HTTPStatusError: If the upload request fails.
+        ValueError: If the response does not contain a valid claim_code.
+    """
+    url = str(creators_platform_api_url / "api/v1/templates/anonymous-upload")
+    response = httpx.post(url, files={"file": (filename, dsl_file_bytes)}, timeout=30)
+    response.raise_for_status()
+
+    data = response.json()
+    claim_code = data.get("data", {}).get("claim_code")
+    if not claim_code:
+        raise ValueError("Creators Platform did not return a valid claim_code")
+
+    return claim_code
+
+
+def get_redirect_url(user_account_id: str, claim_code: str) -> str:
+    """Generate the redirect URL to the Creators Platform frontend.
+
+    Redirects to the Creators Platform root page with the dsl_claim_code.
+    If CREATORS_PLATFORM_OAUTH_CLIENT_ID is configured (Dify Cloud),
+    also signs an OAuth authorization code so the frontend can
+    automatically authenticate the user via the OAuth callback.
+
+    For self-hosted Dify without OAuth client_id configured, only the
+    dsl_claim_code is passed and the user must log in manually.
+
+    Args:
+        user_account_id: The Dify user account ID.
+        claim_code: The claim_code obtained from upload_dsl().
+
+    Returns:
+        The full redirect URL string.
+    """
+    base_url = str(dify_config.CREATORS_PLATFORM_API_URL).rstrip("/")
+    params: dict[str, str] = {"dsl_claim_code": claim_code}
+
+    client_id = str(dify_config.CREATORS_PLATFORM_OAUTH_CLIENT_ID or "")
+    if client_id:
+        from services.oauth_server import OAuthServerService
+
+        oauth_code = OAuthServerService.sign_oauth_authorization_code(client_id, user_account_id)
+        params["oauth_code"] = oauth_code
+
+    return f"{base_url}?{urlencode(params)}"

api/core/llm_generator/context_models.py

@@ -0,0 +1,62 @@
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class VariableSelectorPayload(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    variable: str = Field(..., description="Variable name used in generated code")
+    value_selector: list[str] = Field(..., description="Path to upstream node output, format: [node_id, output_name]")
+
+
+class CodeOutputPayload(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    type: str = Field(..., description="Output variable type")
+
+
+class CodeContextPayload(BaseModel):
+    # From web/app/components/workflow/nodes/tool/components/context-generate-modal/index.tsx (code node snapshot).
+    model_config = ConfigDict(extra="forbid")
+
+    code: str = Field(..., description="Existing code in the Code node")
+    outputs: dict[str, CodeOutputPayload] | None = Field(
+        default=None, description="Existing output definitions for the Code node"
+    )
+    variables: list[VariableSelectorPayload] | None = Field(
+        default=None, description="Existing variable selectors used by the Code node"
+    )
+
+
+class AvailableVarPayload(BaseModel):
+    # From web/app/components/workflow/nodes/_base/hooks/use-available-var-list.ts (available variables).
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    value_selector: list[str] = Field(..., description="Path to upstream node output")
+    type: str = Field(..., description="Variable type, e.g. string, number, array[object]")
+    description: str | None = Field(default=None, description="Optional variable description")
+    node_id: str | None = Field(default=None, description="Source node ID")
+    node_title: str | None = Field(default=None, description="Source node title")
+    node_type: str | None = Field(default=None, description="Source node type")
+    json_schema: dict[str, Any] | None = Field(
+        default=None,
+        alias="schema",
+        description="Optional JSON schema for object variables",
+    )
+
+
+class ParameterInfoPayload(BaseModel):
+    # From web/app/components/workflow/nodes/tool/use-config.ts (ToolParameter metadata).
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(..., description="Target parameter name")
+    type: str = Field(default="string", description="Target parameter type")
+    description: str = Field(default="", description="Parameter description")
+    required: bool | None = Field(default=None, description="Whether the parameter is required")
+    options: list[str] | None = Field(default=None, description="Allowed option values")
+    min: float | None = Field(default=None, description="Minimum numeric value")
+    max: float | None = Field(default=None, description="Maximum numeric value")
+    default: str | int | float | bool | None = Field(default=None, description="Default value")
+    multiple: bool | None = Field(default=None, description="Whether the parameter accepts multiple values")
+    label: str | None = Field(default=None, description="Optional display label")

api/core/llm_generator/output_models.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from graphon.variables.types import SegmentType
+
+
+class SuggestedQuestionsOutput(BaseModel):
+    """Output model for suggested questions generation."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    questions: list[str] = Field(
+        min_length=3,
+        max_length=3,
+        description="Exactly 3 suggested follow-up questions for the user",
+    )
+
+
+class VariableSelectorOutput(BaseModel):
+    """Variable selector mapping code variable to upstream node output.
+
+    Note: Separate from VariableSelector to ensure 'additionalProperties: false'
+    in JSON schema for OpenAI/Azure strict mode.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    variable: str = Field(description="Variable name used in the generated code")
+    value_selector: list[str] = Field(description="Path to upstream node output, format: [node_id, output_name]")
+
+
+class CodeNodeOutputItem(BaseModel):
+    """Single output variable definition.
+
+    Note: OpenAI/Azure strict mode requires 'additionalProperties: false' and
+    does not support dynamic object keys, so outputs use array format.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(description="Output variable name returned by the main function")
+    type: SegmentType = Field(description="Data type of the output variable")
+
+
+class CodeNodeStructuredOutput(BaseModel):
+    """Structured output for code node generation."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    variables: list[VariableSelectorOutput] = Field(
+        description="Input variables mapping code variables to upstream node outputs"
+    )
+    code: str = Field(description="Generated code with a main function that processes inputs and returns outputs")
+    outputs: list[CodeNodeOutputItem] = Field(
+        description="Output variable definitions specifying name and type for each return value"
+    )
+    message: str = Field(description="Brief explanation of what the generated code does")
+
+
+class InstructionModifyOutput(BaseModel):
+    """Output model for instruction-based prompt modification."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    modified: str = Field(description="The modified prompt content after applying the instruction")
+    message: str = Field(description="Brief explanation of what changes were made")

api/core/llm_generator/output_parser/file_ref.py

@@ -0,0 +1,203 @@
+"""
+File path detection and conversion for structured output.
+
+This module provides utilities to:
+1. Detect sandbox file path fields in JSON Schema (format: "file-path")
+2. Adapt schemas to add file-path descriptions before model invocation
+3. Convert sandbox file path strings into File objects via a resolver
+"""
+
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any, cast
+
+from graphon.file import File
+from graphon.variables.segments import ArrayFileSegment, FileSegment
+
+FILE_PATH_FORMAT = "file-path"
+FILE_PATH_DESCRIPTION_SUFFIX = "this field contains a file path from the Dify sandbox"
+
+
+def is_file_path_property(schema: Mapping[str, Any]) -> bool:
+    """Check if a schema property represents a sandbox file path."""
+    if schema.get("type") != "string":
+        return False
+    format_value = schema.get("format")
+    if not isinstance(format_value, str):
+        return False
+    normalized_format = format_value.lower().replace("_", "-")
+    return normalized_format == FILE_PATH_FORMAT
+
+
+def detect_file_path_fields(schema: Mapping[str, Any], path: str = "") -> list[str]:
+    """Recursively detect file path fields in a JSON schema."""
+    file_path_fields: list[str] = []
+    schema_type = schema.get("type")
+
+    if schema_type == "object":
+        properties = schema.get("properties")
+        if isinstance(properties, Mapping):
+            properties_mapping = cast(Mapping[str, Any], properties)
+            for prop_name, prop_schema in properties_mapping.items():
+                if not isinstance(prop_schema, Mapping):
+                    continue
+                prop_schema_mapping = cast(Mapping[str, Any], prop_schema)
+                current_path = f"{path}.{prop_name}" if path else prop_name
+
+                if is_file_path_property(prop_schema_mapping):
+                    file_path_fields.append(current_path)
+                else:
+                    file_path_fields.extend(detect_file_path_fields(prop_schema_mapping, current_path))
+
+    elif schema_type == "array":
+        items_schema = schema.get("items")
+        if not isinstance(items_schema, Mapping):
+            return file_path_fields
+        items_schema_mapping = cast(Mapping[str, Any], items_schema)
+        array_path = f"{path}[*]" if path else "[*]"
+
+        if is_file_path_property(items_schema_mapping):
+            file_path_fields.append(array_path)
+        else:
+            file_path_fields.extend(detect_file_path_fields(items_schema_mapping, array_path))
+
+    return file_path_fields
+
+
+def adapt_schema_for_sandbox_file_paths(schema: Mapping[str, Any]) -> tuple[dict[str, Any], list[str]]:
+    """Normalize sandbox file path fields and collect their JSON paths."""
+    result = _deep_copy_value(schema)
+    if not isinstance(result, dict):
+        raise ValueError("structured_output_schema must be a JSON object")
+    result_dict = cast(dict[str, Any], result)
+
+    file_path_fields: list[str] = []
+    _adapt_schema_in_place(result_dict, path="", file_path_fields=file_path_fields)
+    return result_dict, file_path_fields
+
+
+def convert_sandbox_file_paths_in_output(
+    output: Mapping[str, Any],
+    file_path_fields: Sequence[str],
+    file_resolver: Callable[[str], File],
+) -> tuple[dict[str, Any], list[File]]:
+    """Convert sandbox file paths into File objects using the resolver."""
+    if not file_path_fields:
+        return dict(output), []
+
+    result = _deep_copy_value(output)
+    if not isinstance(result, dict):
+        raise ValueError("Structured output must be a JSON object")
+    result_dict = cast(dict[str, Any], result)
+
+    files: list[File] = []
+    for path in file_path_fields:
+        _convert_path_in_place(result_dict, path.split("."), file_resolver, files)
+
+    return result_dict, files
+
+
+def _adapt_schema_in_place(schema: dict[str, Any], path: str, file_path_fields: list[str]) -> None:
+    schema_type = schema.get("type")
+
+    if schema_type == "object":
+        properties = schema.get("properties")
+        if isinstance(properties, Mapping):
+            properties_mapping = cast(Mapping[str, Any], properties)
+            for prop_name, prop_schema in properties_mapping.items():
+                if not isinstance(prop_schema, dict):
+                    continue
+                prop_schema_dict = cast(dict[str, Any], prop_schema)
+                current_path = f"{path}.{prop_name}" if path else prop_name
+
+                if is_file_path_property(prop_schema_dict):
+                    _normalize_file_path_schema(prop_schema_dict)
+                    file_path_fields.append(current_path)
+                else:
+                    _adapt_schema_in_place(prop_schema_dict, current_path, file_path_fields)
+
+    elif schema_type == "array":
+        items_schema = schema.get("items")
+        if not isinstance(items_schema, dict):
+            return
+        items_schema_dict = cast(dict[str, Any], items_schema)
+        array_path = f"{path}[*]" if path else "[*]"
+
+        if is_file_path_property(items_schema_dict):
+            _normalize_file_path_schema(items_schema_dict)
+            file_path_fields.append(array_path)
+        else:
+            _adapt_schema_in_place(items_schema_dict, array_path, file_path_fields)
+
+
+def _normalize_file_path_schema(schema: dict[str, Any]) -> None:
+    schema["type"] = "string"
+    schema["format"] = FILE_PATH_FORMAT
+    description = schema.get("description", "")
+    if description:
+        if FILE_PATH_DESCRIPTION_SUFFIX not in description:
+            schema["description"] = f"{description}\n{FILE_PATH_DESCRIPTION_SUFFIX}"
+    else:
+        schema["description"] = FILE_PATH_DESCRIPTION_SUFFIX
+
+
+def _deep_copy_value(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        mapping = cast(Mapping[str, Any], value)
+        return {key: _deep_copy_value(item) for key, item in mapping.items()}
+    if isinstance(value, list):
+        list_value = cast(list[Any], value)
+        return [_deep_copy_value(item) for item in list_value]
+    return value
+
+
+def _convert_path_in_place(
+    obj: dict[str, Any],
+    path_parts: list[str],
+    file_resolver: Callable[[str], File],
+    files: list[File],
+) -> None:
+    if not path_parts:
+        return
+
+    current = path_parts[0]
+    remaining = path_parts[1:]
+
+    if current.endswith("[*]"):
+        key = current[:-3] if current != "[*]" else ""
+        target_value = obj.get(key) if key else obj
+
+        if isinstance(target_value, list):
+            target_list = cast(list[Any], target_value)
+            if remaining:
+                for item in target_list:
+                    if isinstance(item, dict):
+                        item_dict = cast(dict[str, Any], item)
+                        _convert_path_in_place(item_dict, remaining, file_resolver, files)
+            else:
+                resolved_files: list[File] = []
+                for item in target_list:
+                    if not isinstance(item, str):
+                        raise ValueError("File path must be a string")
+                    file = file_resolver(item)
+                    files.append(file)
+                    resolved_files.append(file)
+                if key:
+                    obj[key] = ArrayFileSegment(value=resolved_files)
+        return
+
+    if not remaining:
+        if current not in obj:
+            return
+        value = obj[current]
+        if value is None:
+            obj[current] = None
+            return
+        if not isinstance(value, str):
+            raise ValueError("File path must be a string")
+        file = file_resolver(value)
+        files.append(file)
+        obj[current] = FileSegment(value=file)
+        return
+
+    if current in obj and isinstance(obj[current], dict):
+        _convert_path_in_place(obj[current], remaining, file_resolver, files)

api/core/llm_generator/utils.py

@@ -0,0 +1,45 @@
+"""Utility functions for LLM generator."""
+
+from graphon.model_runtime.entities.message_entities import (
+    AssistantPromptMessage,
+    PromptMessage,
+    PromptMessageRole,
+    SystemPromptMessage,
+    ToolPromptMessage,
+    UserPromptMessage,
+)
+
+
+def deserialize_prompt_messages(messages: list[dict]) -> list[PromptMessage]:
+    """
+    Deserialize list of dicts to list[PromptMessage].
+
+    Expected format:
+        [
+            {"role": "user", "content": "..."},
+            {"role": "assistant", "content": "..."},
+        ]
+    """
+    result: list[PromptMessage] = []
+    for msg in messages:
+        role = PromptMessageRole.value_of(msg["role"])
+        content = msg.get("content", "")
+
+        match role:
+            case PromptMessageRole.USER:
+                result.append(UserPromptMessage(content=content))
+            case PromptMessageRole.ASSISTANT:
+                result.append(AssistantPromptMessage(content=content))
+            case PromptMessageRole.SYSTEM:
+                result.append(SystemPromptMessage(content=content))
+            case PromptMessageRole.TOOL:
+                result.append(ToolPromptMessage(content=content, tool_call_id=msg.get("tool_call_id", "")))
+
+    return result
+
+
+def serialize_prompt_messages(messages: list[PromptMessage]) -> list[dict]:
+    """
+    Serialize list[PromptMessage] to list of dicts.
+    """
+    return [{"role": msg.role.value, "content": msg.content} for msg in messages]

api/core/memory/__init__.py

@@ -0,0 +1,11 @@
+from core.memory.base import BaseMemory
+from core.memory.node_token_buffer_memory import (
+    NodeTokenBufferMemory,
+)
+from core.memory.token_buffer_memory import TokenBufferMemory
+
+__all__ = [
+    "BaseMemory",
+    "NodeTokenBufferMemory",
+    "TokenBufferMemory",
+]

api/core/memory/base.py

@@ -0,0 +1,82 @@
+"""
+Base memory interfaces and types.
+
+This module defines the common protocol for memory implementations.
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+
+from graphon.model_runtime.entities import ImagePromptMessageContent, PromptMessage
+
+
+class BaseMemory(ABC):
+    """
+    Abstract base class for memory implementations.
+
+    Provides a common interface for both conversation-level and node-level memory.
+    """
+
+    @abstractmethod
+    def get_history_prompt_messages(
+        self,
+        max_token_limit: int = 2000,
+        message_limit: int | None = None,
+    ) -> Sequence[PromptMessage]:
+        """
+        Get history prompt messages.
+
+        :param max_token_limit: Maximum tokens for history
+        :param message_limit: Maximum number of messages
+        :return: Sequence of PromptMessage for LLM context
+        """
+        pass
+
+    def get_history_prompt_text(
+        self,
+        human_prefix: str = "Human",
+        ai_prefix: str = "Assistant",
+        max_token_limit: int = 2000,
+        message_limit: int | None = None,
+    ) -> str:
+        """
+        Get history prompt as formatted text.
+
+        :param human_prefix: Prefix for human messages
+        :param ai_prefix: Prefix for assistant messages
+        :param max_token_limit: Maximum tokens for history
+        :param message_limit: Maximum number of messages
+        :return: Formatted history text
+        """
+        from graphon.model_runtime.entities import (
+            PromptMessageRole,
+            TextPromptMessageContent,
+        )
+
+        prompt_messages = self.get_history_prompt_messages(
+            max_token_limit=max_token_limit,
+            message_limit=message_limit,
+        )
+
+        string_messages = []
+        for m in prompt_messages:
+            if m.role == PromptMessageRole.USER:
+                role = human_prefix
+            elif m.role == PromptMessageRole.ASSISTANT:
+                role = ai_prefix
+            else:
+                continue
+
+            if isinstance(m.content, list):
+                inner_msg = ""
+                for content in m.content:
+                    if isinstance(content, TextPromptMessageContent):
+                        inner_msg += f"{content.data}\n"
+                    elif isinstance(content, ImagePromptMessageContent):
+                        inner_msg += "[image]\n"
+                string_messages.append(f"{role}: {inner_msg.strip()}")
+            else:
+                message = f"{role}: {m.content}"
+                string_messages.append(message)
+
+        return "\n".join(string_messages)

api/core/memory/node_token_buffer_memory.py

@@ -0,0 +1,196 @@
+"""
+Node-level Token Buffer Memory for Chatflow.
+
+This module provides node-scoped memory within a conversation.
+Each LLM node in a workflow can maintain its own independent conversation history.
+
+Note: This is only available in Chatflow (advanced-chat mode) because it requires
+both conversation_id and node_id.
+
+Design:
+- History is read directly from WorkflowNodeExecutionModel.outputs["context"]
+- No separate storage needed - the context is already saved during node execution
+- Thread tracking leverages Message table's parent_message_id structure
+"""
+
+import logging
+from collections.abc import Sequence
+from typing import cast
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from core.memory.base import BaseMemory
+from core.model_manager import ModelInstance
+from core.prompt.utils.extract_thread_messages import extract_thread_messages
+from graphon.file import file_manager
+from graphon.model_runtime.entities import (
+    AssistantPromptMessage,
+    MultiModalPromptMessageContent,
+    PromptMessage,
+    PromptMessageRole,
+    SystemPromptMessage,
+    ToolPromptMessage,
+    UserPromptMessage,
+)
+from graphon.model_runtime.entities.message_entities import PromptMessageContentUnionTypes
+from extensions.ext_database import db
+from models.model import Message
+from models.workflow import WorkflowNodeExecutionModel
+
+logger = logging.getLogger(__name__)
+
+
+class NodeTokenBufferMemory(BaseMemory):
+    """
+    Node-level Token Buffer Memory.
+
+    Provides node-scoped memory within a conversation. Each LLM node can maintain
+    its own independent conversation history.
+
+    Key design: History is read directly from WorkflowNodeExecutionModel.outputs["context"],
+    which is already saved during node execution. No separate storage needed.
+    """
+
+    def __init__(
+        self,
+        app_id: str,
+        conversation_id: str,
+        node_id: str,
+        tenant_id: str,
+        model_instance: ModelInstance,
+    ):
+        self.app_id = app_id
+        self.conversation_id = conversation_id
+        self.node_id = node_id
+        self.tenant_id = tenant_id
+        self.model_instance = model_instance
+
+    def _get_thread_workflow_run_ids(self) -> list[str]:
+        """
+        Get workflow_run_ids for the current thread by querying Message table.
+        Returns workflow_run_ids in chronological order (oldest first).
+        """
+        with Session(db.engine, expire_on_commit=False) as session:
+            stmt = (
+                select(Message)
+                .where(Message.conversation_id == self.conversation_id)
+                .order_by(Message.created_at.desc())
+                .limit(500)
+            )
+            messages = list(session.scalars(stmt).all())
+
+        if not messages:
+            return []
+
+        # Extract thread messages using existing logic
+        thread_messages = extract_thread_messages(messages)
+
+        # For newly created message, its answer is temporarily empty, skip it
+        if thread_messages and not thread_messages[0].answer and thread_messages[0].answer_tokens == 0:
+            thread_messages.pop(0)
+
+        # Reverse to get chronological order, extract workflow_run_ids
+        return [msg.workflow_run_id for msg in reversed(thread_messages) if msg.workflow_run_id]
+
+    def _deserialize_prompt_message(self, msg_dict: dict) -> PromptMessage:
+        """Deserialize a dict to PromptMessage based on role."""
+        role = msg_dict.get("role")
+        if role in (PromptMessageRole.USER, "user"):
+            return UserPromptMessage.model_validate(msg_dict)
+        elif role in (PromptMessageRole.ASSISTANT, "assistant"):
+            return AssistantPromptMessage.model_validate(msg_dict)
+        elif role in (PromptMessageRole.SYSTEM, "system"):
+            return SystemPromptMessage.model_validate(msg_dict)
+        elif role in (PromptMessageRole.TOOL, "tool"):
+            return ToolPromptMessage.model_validate(msg_dict)
+        else:
+            return PromptMessage.model_validate(msg_dict)
+
+    def _deserialize_context(self, context_data: list[dict]) -> list[PromptMessage]:
+        """Deserialize context data from outputs to list of PromptMessage."""
+        messages = []
+        for msg_dict in context_data:
+            try:
+                msg = self._deserialize_prompt_message(msg_dict)
+                msg = self._restore_multimodal_content(msg)
+                messages.append(msg)
+            except Exception as e:
+                logger.warning("Failed to deserialize prompt message: %s", e)
+        return messages
+
+    def _restore_multimodal_content(self, message: PromptMessage) -> PromptMessage:
+        """
+        Restore multimodal content (base64 or url) from file_ref.
+
+        When context is saved, base64_data is cleared to save storage space.
+        This method restores the content by parsing file_ref (format: "method:id_or_url").
+        """
+        content = message.content
+        if content is None or isinstance(content, str):
+            return message
+
+        # Process list content, restoring multimodal data from file references
+        restored_content: list[PromptMessageContentUnionTypes] = []
+        for item in content:
+            if isinstance(item, MultiModalPromptMessageContent):
+                # restore_multimodal_content preserves the concrete subclass type
+                restored_item = file_manager.restore_multimodal_content(item)
+                restored_content.append(cast(PromptMessageContentUnionTypes, restored_item))
+            else:
+                restored_content.append(item)
+
+        return message.model_copy(update={"content": restored_content})
+
+    def get_history_prompt_messages(
+        self,
+        max_token_limit: int = 2000,
+        message_limit: int | None = None,
+    ) -> Sequence[PromptMessage]:
+        """
+        Retrieve history as PromptMessage sequence.
+        History is read directly from the last completed node execution's outputs["context"].
+        """
+        _ = message_limit  # unused, kept for interface compatibility
+
+        thread_workflow_run_ids = self._get_thread_workflow_run_ids()
+        if not thread_workflow_run_ids:
+            return []
+
+        # Get the last completed workflow_run_id (contains accumulated context)
+        last_run_id = thread_workflow_run_ids[-1]
+
+        with Session(db.engine, expire_on_commit=False) as session:
+            stmt = select(WorkflowNodeExecutionModel).where(
+                WorkflowNodeExecutionModel.workflow_run_id == last_run_id,
+                WorkflowNodeExecutionModel.node_id == self.node_id,
+                WorkflowNodeExecutionModel.status == "succeeded",
+            )
+            execution = session.scalars(stmt).first()
+
+            if not execution:
+                return []
+
+            outputs = execution.outputs_dict
+            if not outputs:
+                return []
+
+            context_data = outputs.get("context")
+
+        if not context_data or not isinstance(context_data, list):
+            return []
+
+        prompt_messages = self._deserialize_context(context_data)
+        if not prompt_messages:
+            return []
+
+        # Truncate by token limit
+        try:
+            current_tokens = self.model_instance.get_llm_num_tokens(prompt_messages)
+            while current_tokens > max_token_limit and len(prompt_messages) > 1:
+                prompt_messages.pop(0)
+                current_tokens = self.model_instance.get_llm_num_tokens(prompt_messages)
+        except Exception as e:
+            logger.warning("Failed to count tokens for truncation: %s", e)
+
+        return prompt_messages

api/core/memory/token_buffer_memory.py

@@ -64,7 +64,7 @@ class TokenBufferMemory:
         match self.conversation.mode:
             case AppMode.AGENT_CHAT | AppMode.COMPLETION | AppMode.CHAT:
                 file_extra_config = FileUploadConfigManager.convert(self.conversation.model_config)
-            case AppMode.ADVANCED_CHAT | AppMode.WORKFLOW:
+            case AppMode.ADVANCED_CHAT | AppMode.WORKFLOW | AppMode.AGENT:
                 app = self.conversation.app
                 if not app:
                     raise ValueError("App not found for conversation")

api/core/rag/datasource/vdb/vector_factory.py

@@ -41,7 +41,23 @@ class AbstractVectorFactory(ABC):
 class Vector:
     def __init__(self, dataset: Dataset, attributes: list | None = None):
         if attributes is None:
-            attributes = ["doc_id", "dataset_id", "document_id", "doc_hash", "doc_type"]
+            # `is_summary` and `original_chunk_id` are stored on summary vectors
+            # by `SummaryIndexService` and read back by `RetrievalService` to
+            # route summary hits through their original parent chunks. They
+            # must be listed here so vector backends that use this list as an
+            # explicit return-properties projection (notably Weaviate) actually
+            # return those fields; without them, summary hits silently
+            # collapse into `is_summary = False` branches and the summary
+            # retrieval path is a no-op. See #34884.
+            attributes = [
+                "doc_id",
+                "dataset_id",
+                "document_id",
+                "doc_hash",
+                "doc_type",
+                "is_summary",
+                "original_chunk_id",
+            ]
         self._dataset = dataset
         self._embeddings = self._get_embeddings()
         self._attributes = attributes

api/core/rag/docstore/dataset_docstore.py

@@ -244,7 +244,7 @@ class DatasetDocumentStore:
         return document_segment
 
     def add_multimodel_documents_binding(self, segment_id: str, multimodel_documents: list[AttachmentDocument] | None):
-        if multimodel_documents:
+        if multimodel_documents and self._document_id is not None:
             for multimodel_document in multimodel_documents:
                 binding = SegmentAttachmentBinding(
                     tenant_id=self._dataset.tenant_id,

api/core/tools/__base/tool.py

@@ -8,6 +8,8 @@ from typing import TYPE_CHECKING, Any
 if TYPE_CHECKING:  # pragma: no cover
     from models.model import File
 
+from graphon.model_runtime.entities import PromptMessageTool
+
 from core.tools.__base.tool_runtime import ToolRuntime
 from core.tools.entities.tool_entities import (
     ToolEntity,
@@ -154,6 +156,61 @@ class Tool(ABC):
 
         return parameters
 
+    def to_prompt_message_tool(self) -> PromptMessageTool:
+        """Convert this tool to a PromptMessageTool for LLM consumption."""
+        message_tool = PromptMessageTool(
+            name=self.entity.identity.name,
+            description=self.entity.description.llm if self.entity.description else "",
+            parameters={
+                "type": "object",
+                "properties": {},
+                "required": [],
+            },
+        )
+
+        parameters = self.get_merged_runtime_parameters()
+        for parameter in parameters:
+            if parameter.form != ToolParameter.ToolParameterForm.LLM:
+                continue
+
+            parameter_type = parameter.type.as_normal_type()
+            if parameter.type in {
+                ToolParameter.ToolParameterType.SYSTEM_FILES,
+                ToolParameter.ToolParameterType.FILE,
+                ToolParameter.ToolParameterType.FILES,
+            }:
+                if parameter.type == ToolParameter.ToolParameterType.FILE:
+                    file_format_desc = " Input the file id with format: [File: file_id]."
+                else:
+                    file_format_desc = "Input the file id with format: [Files: file_id1, file_id2, ...]. "
+
+                message_tool.parameters["properties"][parameter.name] = {
+                    "type": "string",
+                    "description": (parameter.llm_description or "") + file_format_desc,
+                }
+                continue
+
+            enum = []
+            if parameter.type == ToolParameter.ToolParameterType.SELECT:
+                enum = [option.value for option in parameter.options] if parameter.options else []
+
+            message_tool.parameters["properties"][parameter.name] = (
+                {
+                    "type": parameter_type,
+                    "description": parameter.llm_description or "",
+                }
+                if parameter.input_schema is None
+                else parameter.input_schema
+            )
+
+            if len(enum) > 0:
+                message_tool.parameters["properties"][parameter.name]["enum"] = enum
+
+            if parameter.required:
+                message_tool.parameters["required"].append(parameter.name)
+
+        return message_tool
+
     def create_image_message(
         self,
         image: str,

api/core/tools/utils/system_encryption.py

@@ -0,0 +1,187 @@
+import base64
+import hashlib
+import logging
+from collections.abc import Mapping
+from typing import Any
+
+from Crypto.Cipher import AES
+from Crypto.Random import get_random_bytes
+from Crypto.Util.Padding import pad, unpad
+from pydantic import TypeAdapter
+
+from configs import dify_config
+
+logger = logging.getLogger(__name__)
+
+
+class EncryptionError(Exception):
+    """Encryption/decryption specific error"""
+
+    pass
+
+
+class SystemEncrypter:
+    """
+    A simple parameters encrypter using AES-CBC encryption.
+
+    This class provides methods to encrypt and decrypt parameters
+    using AES-CBC mode with a key derived from the application's SECRET_KEY.
+    """
+
+    def __init__(self, secret_key: str | None = None):
+        """
+        Initialize the encrypter.
+
+        Args:
+            secret_key: Optional secret key. If not provided, uses dify_config.SECRET_KEY
+
+        Raises:
+            ValueError: If SECRET_KEY is not configured or empty
+        """
+        secret_key = secret_key or dify_config.SECRET_KEY or ""
+
+        # Generate a fixed 256-bit key using SHA-256
+        self.key = hashlib.sha256(secret_key.encode()).digest()
+
+    def encrypt_params(self, params: Mapping[str, Any]) -> str:
+        """
+        Encrypt parameters.
+
+        Args:
+            params: parameters dictionary, e.g., {"client_id": "xxx", "client_secret": "xxx"}
+
+        Returns:
+            Base64-encoded encrypted string
+
+        Raises:
+            EncryptionError: If encryption fails
+            ValueError: If params is invalid
+        """
+
+        try:
+            # Generate random IV (16 bytes)
+            iv = get_random_bytes(16)
+
+            # Create AES cipher (CBC mode)
+            cipher = AES.new(self.key, AES.MODE_CBC, iv)
+
+            # Encrypt data
+            padded_data = pad(TypeAdapter(dict).dump_json(dict(params)), AES.block_size)
+            encrypted_data = cipher.encrypt(padded_data)
+
+            # Combine IV and encrypted data
+            combined = iv + encrypted_data
+
+            # Return base64 encoded string
+            return base64.b64encode(combined).decode()
+
+        except Exception as e:
+            raise EncryptionError(f"Encryption failed: {str(e)}") from e
+
+    def decrypt_params(self, encrypted_data: str) -> Mapping[str, Any]:
+        """
+        Decrypt parameters.
+
+        Args:
+            encrypted_data: Base64-encoded encrypted string
+
+        Returns:
+            Decrypted parameters dictionary
+
+        Raises:
+            EncryptionError: If decryption fails
+            ValueError: If encrypted_data is invalid
+        """
+        if not isinstance(encrypted_data, str):
+            raise ValueError("encrypted_data must be a string")
+
+        if not encrypted_data:
+            raise ValueError("encrypted_data cannot be empty")
+
+        try:
+            # Base64 decode
+            combined = base64.b64decode(encrypted_data)
+
+            # Check minimum length (IV + at least one AES block)
+            if len(combined) < 32:  # 16 bytes IV + 16 bytes minimum encrypted data
+                raise ValueError("Invalid encrypted data format")
+
+            # Separate IV and encrypted data
+            iv = combined[:16]
+            encrypted_data_bytes = combined[16:]
+
+            # Create AES cipher
+            cipher = AES.new(self.key, AES.MODE_CBC, iv)
+
+            # Decrypt data
+            decrypted_data = cipher.decrypt(encrypted_data_bytes)
+            unpadded_data = unpad(decrypted_data, AES.block_size)
+
+            # Parse JSON
+            params: Mapping[str, Any] = TypeAdapter(Mapping[str, Any]).validate_json(unpadded_data)
+
+            if not isinstance(params, dict):
+                raise ValueError("Decrypted data is not a valid dictionary")
+
+            return params
+
+        except Exception as e:
+            raise EncryptionError(f"Decryption failed: {str(e)}") from e
+
+
+# Factory function for creating encrypter instances
+def create_system_encrypter(secret_key: str | None = None) -> SystemEncrypter:
+    """
+    Create an encrypter instance.
+
+    Args:
+        secret_key: Optional secret key. If not provided, uses dify_config.SECRET_KEY
+
+    Returns:
+        SystemEncrypter instance
+    """
+    return SystemEncrypter(secret_key=secret_key)
+
+
+# Global encrypter instance (for backward compatibility)
+_encrypter: SystemEncrypter | None = None
+
+
+def get_system_encrypter() -> SystemEncrypter:
+    """
+    Get the global encrypter instance.
+
+    Returns:
+        SystemEncrypter instance
+    """
+    global _encrypter
+    if _encrypter is None:
+        _encrypter = SystemEncrypter()
+    return _encrypter
+
+
+# Convenience functions for backward compatibility
+def encrypt_system_params(params: Mapping[str, Any]) -> str:
+    """
+    Encrypt parameters using the global encrypter.
+
+    Args:
+        params: parameters dictionary
+
+    Returns:
+        Base64-encoded encrypted string
+    """
+    return get_system_encrypter().encrypt_params(params)
+
+
+def decrypt_system_params(encrypted_data: str) -> Mapping[str, Any]:
+    """
+    Decrypt parameters using the global encrypter.
+
+    Args:
+        encrypted_data: Base64-encoded encrypted string
+
+    Returns:
+        Decrypted parameters dictionary
+    """
+    return get_system_encrypter().decrypt_params(encrypted_data)

api/core/workflow/node_factory.py

@@ -53,6 +53,9 @@ from core.workflow.nodes.agent.plugin_strategy_adapter import (
     PluginAgentStrategyResolver,
 )
 from core.workflow.nodes.agent.runtime_support import AgentRuntimeSupport
+from core.workflow.nodes.agent_v2.entities import AGENT_V2_NODE_TYPE
+from core.workflow.nodes.agent_v2.event_adapter import AgentV2EventAdapter
+from core.workflow.nodes.agent_v2.tool_manager import AgentV2ToolManager
 from core.workflow.system_variables import SystemVariableKey, get_system_text, system_variable_selector
 from core.workflow.template_rendering import CodeExecutorJinja2TemplateRenderer
 from extensions.ext_database import db
@@ -367,6 +370,11 @@ class DifyNodeFactory(NodeFactory):
         typed_node_config = NodeConfigDictAdapter.validate_python(normalize_node_config_for_graph(node_config))
         node_id = typed_node_config["id"]
         node_data = typed_node_config["data"]
+
+        if node_data.type == BuiltinNodeTypes.LLM and dify_config.AGENT_V2_REPLACES_LLM:
+            node_data = self._remap_llm_to_agent_v2(node_data)
+            typed_node_config["data"] = node_data
+
         node_class = self._resolve_node_class(node_type=node_data.type, node_version=str(node_data.version))
         node_type = node_data.type
         node_init_kwargs_factories: Mapping[NodeType, Callable[[], dict[str, object]]] = {
@@ -433,6 +441,7 @@ class DifyNodeFactory(NodeFactory):
                 "runtime_support": self._agent_runtime_support,
                 "message_transformer": self._agent_message_transformer,
             },
+            AGENT_V2_NODE_TYPE: lambda: self._build_agent_v2_kwargs(node_data),
         }
         node_init_kwargs = node_init_kwargs_factories.get(node_type, lambda: {})()
         return node_class(
@@ -443,6 +452,71 @@ class DifyNodeFactory(NodeFactory):
             **node_init_kwargs,
         )
 
+    def _build_agent_v2_kwargs(self, node_data: BaseNodeData) -> dict[str, object]:
+        """Build initialization kwargs for Agent V2 node.
+
+        Injects memory (same mechanism as LLM Node) plus tool_manager
+        and event_adapter.
+        """
+        from core.workflow.nodes.agent_v2.entities import AgentV2NodeData
+
+        validated = AgentV2NodeData.model_validate(node_data.model_dump())
+
+        import logging as _logging
+        _log = _logging.getLogger(__name__)
+
+        memory = None
+        if validated.memory is not None:
+            conversation_id = get_system_text(
+                self.graph_runtime_state.variable_pool, SystemVariableKey.CONVERSATION_ID
+            )
+            _log.info("[AGENT_V2_MEMORY] memory_config=%s, conversation_id=%s", validated.memory, conversation_id)
+            if conversation_id:
+                from graphon.model_runtime.entities.model_entities import ModelType as _ModelType
+
+                from core.model_manager import ModelManager as _ModelManager
+
+                model_instance = _ModelManager.for_tenant(
+                    tenant_id=self._dify_context.tenant_id
+                ).get_model_instance(
+                    tenant_id=self._dify_context.tenant_id,
+                    provider=validated.model.provider,
+                    model_type=_ModelType.LLM,
+                    model=validated.model.name,
+                )
+                memory = fetch_memory(
+                    conversation_id=conversation_id,
+                    app_id=self._dify_context.app_id,
+                    node_data_memory=validated.memory,
+                    model_instance=model_instance,
+                )
+
+        return {
+            "tool_manager": AgentV2ToolManager(
+                tenant_id=self._dify_context.tenant_id,
+                app_id=self._dify_context.app_id,
+            ),
+            "event_adapter": AgentV2EventAdapter(),
+            "memory": memory,
+        }
+
+    @staticmethod
+    def _remap_llm_to_agent_v2(node_data: BaseNodeData) -> BaseNodeData:
+        """Transparently remap LLMNodeData to AgentV2NodeData.
+
+        Since AgentV2NodeData is a strict superset of LLMNodeData
+        (same LLM fields + tools/iterations/strategy), the mapping is lossless.
+        With tools=[], Agent V2 behaves identically to LLM Node.
+        """
+        from core.workflow.nodes.agent_v2.entities import AGENT_V2_NODE_TYPE, AgentV2NodeData
+
+        data_dict = node_data.model_dump()
+        data_dict["type"] = AGENT_V2_NODE_TYPE
+        data_dict.setdefault("tools", [])
+        data_dict.setdefault("max_iterations", 10)
+        data_dict.setdefault("agent_strategy", "auto")
+        return AgentV2NodeData.model_validate(data_dict)
+
     @staticmethod
     def _validate_resolved_node_data(node_class: type[Node], node_data: BaseNodeData) -> BaseNodeData:
         """

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

@@ -0,0 +1,4 @@
+from .entities import AgentV2NodeData
+from .node import AgentV2Node
+
+__all__ = ["AgentV2Node", "AgentV2NodeData"]

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

@@ -0,0 +1,86 @@
+"""Agent V2 Node data model.
+
+Merges LLM Node capabilities (prompt, memory, vision, context, structured output)
+with Agent capabilities (tool calling loop, strategy selection).
+When no tools are configured, behaves identically to an LLM Node.
+"""
+
+from collections.abc import Mapping, Sequence
+from typing import Any, Literal
+
+from graphon.entities.base_node_data import BaseNodeData
+from graphon.model_runtime.entities import ImagePromptMessageContent
+from graphon.nodes.llm.entities import (
+    LLMNodeChatModelMessage,
+    LLMNodeCompletionModelPromptTemplate,
+    ModelConfig,
+    PromptConfig,
+)
+from pydantic import BaseModel, Field, field_validator
+
+from core.prompt.entities.advanced_prompt_entities import MemoryConfig
+from core.tools.entities.tool_entities import ToolProviderType
+
+AGENT_V2_NODE_TYPE = "agent-v2"
+
+
+class ContextConfig(BaseModel):
+    enabled: bool
+    variable_selector: list[str] | None = None
+
+
+class VisionConfigOptions(BaseModel):
+    variable_selector: Sequence[str] = Field(default_factory=lambda: ["sys", "files"])
+    detail: ImagePromptMessageContent.DETAIL = ImagePromptMessageContent.DETAIL.HIGH
+
+
+class VisionConfig(BaseModel):
+    enabled: bool = False
+    configs: VisionConfigOptions = Field(default_factory=VisionConfigOptions)
+
+    @field_validator("configs", mode="before")
+    @classmethod
+    def convert_none_configs(cls, v: Any):
+        if v is None:
+            return VisionConfigOptions()
+        return v
+
+
+class ToolMetadata(BaseModel):
+    """Tool configuration for Agent V2 node."""
+
+    enabled: bool = True
+    type: ToolProviderType = Field(..., description="Tool provider type: builtin, api, mcp, workflow")
+    provider_name: str = Field(..., description="Tool provider name/identifier")
+    tool_name: str = Field(..., description="Tool name")
+    plugin_unique_identifier: str | None = Field(None)
+    credential_id: str | None = Field(None)
+    parameters: dict[str, Any] = Field(default_factory=dict)
+    settings: dict[str, Any] = Field(default_factory=dict)
+    extra: dict[str, Any] = Field(default_factory=dict)
+
+
+class AgentV2NodeData(BaseNodeData):
+    """Agent V2 Node — LLM + Agent capabilities in a single workflow node."""
+
+    type: str = AGENT_V2_NODE_TYPE
+
+    # --- LLM capabilities (superset of LLMNodeData) ---
+    model: ModelConfig
+    prompt_template: Sequence[LLMNodeChatModelMessage] | LLMNodeCompletionModelPromptTemplate
+    prompt_config: PromptConfig = Field(default_factory=PromptConfig)
+    memory: MemoryConfig | None = None
+    context: ContextConfig = Field(default_factory=lambda: ContextConfig(enabled=False))
+    vision: VisionConfig = Field(default_factory=VisionConfig)
+    structured_output: Mapping[str, Any] | None = None
+    structured_output_switch_on: bool = Field(False, alias="structured_output_enabled")
+    reasoning_format: Literal["separated", "tagged"] = "tagged"
+
+    # --- Agent capabilities ---
+    tools: Sequence[ToolMetadata] = Field(default_factory=list)
+    max_iterations: int = Field(default=10, ge=1, le=99)
+    agent_strategy: Literal["auto", "function-calling", "chain-of-thought"] = "auto"
+
+    @property
+    def tool_call_enabled(self) -> bool:
+        return bool(self.tools) and any(t.enabled for t in self.tools)

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

@@ -0,0 +1,86 @@
+"""Event adapter for Agent V2 Node.
+
+Converts AgentPattern outputs (LLMResultChunk | AgentLog) into
+graphon NodeEventBase events consumable by the workflow engine.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+
+from graphon.model_runtime.entities import LLMResultChunk
+from graphon.node_events import (
+    AgentLogEvent,
+    NodeEventBase,
+    StreamChunkEvent,
+)
+
+from core.agent.entities import AgentLog, AgentResult
+
+
+class AgentV2EventAdapter:
+    """Converts agent strategy outputs into workflow node events."""
+
+    def process_strategy_outputs(
+        self,
+        outputs: Generator[LLMResultChunk | AgentLog, None, AgentResult],
+        *,
+        node_id: str,
+        node_execution_id: str,
+    ) -> Generator[NodeEventBase, None, AgentResult]:
+        """Process strategy generator outputs, yielding node events.
+
+        Returns the final AgentResult from the strategy.
+        """
+        try:
+            while True:
+                item = next(outputs)
+                if isinstance(item, AgentLog):
+                    yield self._convert_agent_log(item, node_id=node_id, node_execution_id=node_execution_id)
+                elif isinstance(item, LLMResultChunk):
+                    pass
+        except StopIteration as e:
+            result: AgentResult = e.value
+            return result
+
+    def _convert_agent_log(
+        self,
+        log: AgentLog,
+        *,
+        node_id: str,
+        node_execution_id: str,
+    ) -> AgentLogEvent:
+        return AgentLogEvent(
+            message_id=log.id,
+            label=log.label,
+            node_execution_id=node_execution_id,
+            parent_id=log.parent_id,
+            error=log.error,
+            status=log.status.value,
+            data=dict(log.data),
+            metadata={k.value if hasattr(k, "value") else str(k): v for k, v in log.metadata.items()},
+            node_id=node_id,
+        )
+
+    def _convert_llm_chunk(
+        self,
+        chunk: LLMResultChunk,
+        *,
+        node_id: str,
+    ) -> Generator[NodeEventBase, None, None]:
+        content = ""
+        if chunk.delta.message and chunk.delta.message.content:
+            if isinstance(chunk.delta.message.content, str):
+                content = chunk.delta.message.content
+            elif isinstance(chunk.delta.message.content, list):
+                from graphon.model_runtime.entities.message_entities import TextPromptMessageContent
+
+                for item in chunk.delta.message.content:
+                    if isinstance(item, TextPromptMessageContent):
+                        content += item.data
+
+        if content:
+            yield StreamChunkEvent(
+                selector=[node_id, "text"],
+                chunk=content,
+            )

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

@@ -0,0 +1,549 @@
+"""Agent V2 Workflow Node.
+
+A unified workflow node that combines LLM capabilities with agent tool-calling.
+When tools are configured, runs an FC/ReAct loop via StrategyFactory.
+When no tools are present, behaves as a single-shot LLM invocation.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from collections.abc import Generator, Mapping, Sequence
+from typing import TYPE_CHECKING, Any, Literal
+
+from graphon.enums import WorkflowNodeExecutionMetadataKey, WorkflowNodeExecutionStatus
+from graphon.model_runtime.entities import (
+    AssistantPromptMessage,
+    LLMResultChunk,
+    PromptMessage,
+    SystemPromptMessage,
+    TextPromptMessageContent,
+    UserPromptMessage,
+)
+from graphon.model_runtime.entities.llm_entities import LLMUsage
+from graphon.model_runtime.entities.model_entities import ModelFeature, ModelType
+from graphon.node_events import (
+    NodeEventBase,
+    NodeRunResult,
+    StreamCompletedEvent,
+)
+from graphon.nodes.base.node import Node
+from graphon.nodes.base.variable_template_parser import VariableTemplateParser
+
+from core.agent.entities import AgentEntity, ExecutionContext
+from core.agent.patterns import StrategyFactory
+from core.app.entities.app_invoke_entities import DIFY_RUN_CONTEXT_KEY, DifyRunContext
+from core.model_manager import ModelInstance, ModelManager
+from core.workflow.system_variables import SystemVariableKey, get_system_text
+
+from .entities import AGENT_V2_NODE_TYPE, AgentV2NodeData
+from .event_adapter import AgentV2EventAdapter
+from .tool_manager import AgentV2ToolManager
+
+if TYPE_CHECKING:
+    from graphon.entities import GraphInitParams
+    from graphon.entities.graph_config import NodeConfigDict
+    from graphon.runtime import GraphRuntimeState
+
+logger = logging.getLogger(__name__)
+
+_THINK_PATTERN = re.compile(r"<think[^>]*>(.*?)</think>", re.IGNORECASE | re.DOTALL)
+
+
+class AgentV2Node(Node[AgentV2NodeData]):
+    node_type = AGENT_V2_NODE_TYPE
+
+    _tool_manager: AgentV2ToolManager
+    _event_adapter: AgentV2EventAdapter
+
+    def __init__(
+        self,
+        id: str,
+        config: NodeConfigDict,
+        graph_init_params: GraphInitParams,
+        graph_runtime_state: GraphRuntimeState,
+        *,
+        tool_manager: AgentV2ToolManager,
+        event_adapter: AgentV2EventAdapter,
+        memory: Any | None = None,
+    ) -> None:
+        super().__init__(
+            id=id,
+            config=config,
+            graph_init_params=graph_init_params,
+            graph_runtime_state=graph_runtime_state,
+        )
+        self._tool_manager = tool_manager
+        self._event_adapter = event_adapter
+        self._memory = memory
+
+    @classmethod
+    def version(cls) -> str:
+        return "1"
+
+    @classmethod
+    def get_default_config(cls, filters: Mapping[str, object] | None = None) -> Mapping[str, object]:
+        return {
+            "type": AGENT_V2_NODE_TYPE,
+            "config": {
+                "prompt_templates": {
+                    "chat_model": {
+                        "prompts": [
+                            {
+                                "role": "system",
+                                "text": "You are a helpful AI assistant.",
+                                "edition_type": "basic",
+                            }
+                        ]
+                    },
+                    "completion_model": {
+                        "conversation_histories_role": {
+                            "user_prefix": "Human",
+                            "assistant_prefix": "Assistant",
+                        },
+                        "prompt": {
+                            "text": "{{#sys.query#}}",
+                            "edition_type": "basic",
+                        },
+                    },
+                },
+                "agent_strategy": "auto",
+                "max_iterations": 10,
+            },
+        }
+
+    def _run(self) -> Generator[NodeEventBase, None, None]:
+        dify_ctx = DifyRunContext.model_validate(self.require_run_context_value(DIFY_RUN_CONTEXT_KEY))
+
+        try:
+            model_instance = self._fetch_model_instance(dify_ctx)
+        except Exception as e:
+            yield StreamCompletedEvent(
+                node_run_result=NodeRunResult(
+                    status=WorkflowNodeExecutionStatus.FAILED,
+                    inputs={},
+                    error=f"Failed to load model: {e}",
+                )
+            )
+            return
+
+        prompt_messages = self._build_prompt_messages(dify_ctx)
+
+        if self.node_data.tool_call_enabled:
+            yield from self._run_with_tools(model_instance, prompt_messages, dify_ctx)
+        else:
+            yield from self._run_without_tools(model_instance, prompt_messages, dify_ctx)
+
+    # ------------------------------------------------------------------
+    # No-tools path: single LLM invocation (LLM Node equivalent)
+    # ------------------------------------------------------------------
+
+    def _run_without_tools(
+        self,
+        model_instance: ModelInstance,
+        prompt_messages: list[PromptMessage],
+        dify_ctx: DifyRunContext,
+    ) -> Generator[NodeEventBase, None, None]:
+        try:
+            result_chunks: Generator[LLMResultChunk, None, None] = model_instance.invoke_llm(
+                prompt_messages=prompt_messages,
+                model_parameters=self.node_data.model.completion_params,
+                tools=[],
+                stop=[],
+                stream=True,
+                callbacks=[],
+            )
+
+            full_text = ""
+            reasoning_content = ""
+            usage: LLMUsage | None = None
+            finish_reason: str | None = None
+
+            for chunk in result_chunks:
+                chunk_text = self._extract_chunk_text(chunk)
+                if chunk_text:
+                    full_text += chunk_text
+
+                if chunk.delta.usage:
+                    usage = chunk.delta.usage
+                if chunk.delta.finish_reason:
+                    finish_reason = chunk.delta.finish_reason
+
+            if self.node_data.reasoning_format == "separated":
+                full_text, reasoning_content = self._separate_reasoning(full_text)
+
+            metadata = {}
+            if usage:
+                metadata[WorkflowNodeExecutionMetadataKey.TOTAL_TOKENS] = usage.total_tokens
+                metadata[WorkflowNodeExecutionMetadataKey.TOTAL_PRICE] = usage.total_price
+                metadata[WorkflowNodeExecutionMetadataKey.CURRENCY] = usage.currency
+                self.graph_runtime_state.add_tokens(usage.total_tokens)
+
+            yield StreamCompletedEvent(
+                node_run_result=NodeRunResult(
+                    status=WorkflowNodeExecutionStatus.SUCCEEDED,
+                    inputs={},
+                    outputs={
+                        "text": full_text,
+                        "reasoning_content": reasoning_content,
+                        "finish_reason": finish_reason or "stop",
+                    },
+                    metadata=metadata,
+                )
+            )
+        except Exception as e:
+            logger.exception("Agent V2 LLM invocation failed")
+            yield StreamCompletedEvent(
+                node_run_result=NodeRunResult(
+                    status=WorkflowNodeExecutionStatus.FAILED,
+                    inputs={},
+                    error=str(e),
+                )
+            )
+
+    # ------------------------------------------------------------------
+    # Tools path: agent loop via StrategyFactory
+    # ------------------------------------------------------------------
+
+    def _run_with_tools(
+        self,
+        model_instance: ModelInstance,
+        prompt_messages: list[PromptMessage],
+        dify_ctx: DifyRunContext,
+    ) -> Generator[NodeEventBase, None, None]:
+        try:
+            tool_instances = self._tool_manager.prepare_tool_instances(
+                list(self.node_data.tools),
+            )
+
+            model_features = self._get_model_features(model_instance)
+
+            context = ExecutionContext(
+                user_id=dify_ctx.user_id,
+                app_id=dify_ctx.app_id,
+                tenant_id=dify_ctx.tenant_id,
+                conversation_id=get_system_text(
+                    self.graph_runtime_state.variable_pool,
+                    SystemVariableKey.CONVERSATION_ID,
+                ),
+            )
+
+            agent_strategy_enum = self._map_strategy_config(self.node_data.agent_strategy)
+
+            strategy = StrategyFactory.create_strategy(
+                model_features=model_features,
+                model_instance=model_instance,
+                tools=tool_instances,
+                files=[],
+                max_iterations=self.node_data.max_iterations,
+                context=context,
+                agent_strategy=agent_strategy_enum,
+                tool_invoke_hook=self._tool_manager.create_workflow_tool_invoke_hook(context),
+            )
+
+            outputs_gen = strategy.run(
+                prompt_messages=prompt_messages,
+                model_parameters=self.node_data.model.completion_params,
+                stop=[],
+                stream=True,
+            )
+
+            result = yield from self._event_adapter.process_strategy_outputs(
+                outputs_gen,
+                node_id=self._node_id,
+                node_execution_id=self.id,
+            )
+
+            if result.usage and hasattr(result.usage, "total_tokens"):
+                self.graph_runtime_state.add_tokens(result.usage.total_tokens)
+
+            yield StreamCompletedEvent(
+                node_run_result=NodeRunResult(
+                    status=WorkflowNodeExecutionStatus.SUCCEEDED,
+                    inputs={},
+                    outputs={
+                        "text": result.text,
+                        "finish_reason": result.finish_reason or "stop",
+                    },
+                    metadata=self._build_usage_metadata(result.usage),
+                )
+            )
+        except Exception as e:
+            logger.exception("Agent V2 tool execution failed")
+            yield StreamCompletedEvent(
+                node_run_result=NodeRunResult(
+                    status=WorkflowNodeExecutionStatus.FAILED,
+                    inputs={},
+                    error=str(e),
+                )
+            )
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _fetch_model_instance(self, dify_ctx: DifyRunContext) -> ModelInstance:
+        model_config = self.node_data.model
+        model_manager = ModelManager.for_tenant(tenant_id=dify_ctx.tenant_id)
+        model_instance = model_manager.get_model_instance(
+            tenant_id=dify_ctx.tenant_id,
+            provider=model_config.provider,
+            model_type=ModelType.LLM,
+            model=model_config.name,
+        )
+        return model_instance
+
+    def _build_prompt_messages(self, dify_ctx: DifyRunContext) -> list[PromptMessage]:
+        """Build prompt messages from the node's prompt_template, resolving variables.
+
+        Handles: variable references ({{#node.var#}}), context injection ({{#context#}}),
+        Jinja2 templates, and memory (conversation history).
+        """
+        variable_pool = self.graph_runtime_state.variable_pool
+        messages: list[PromptMessage] = []
+
+        context_str = self._build_context_string(variable_pool)
+
+        template = self.node_data.prompt_template
+        if isinstance(template, Sequence) and not isinstance(template, str):
+            for msg_template in template:
+                role = msg_template.role.value if hasattr(msg_template.role, "value") else str(msg_template.role)
+                text = msg_template.text or ""
+                jinja2_text = getattr(msg_template, "jinja2_text", None)
+
+                if jinja2_text:
+                    content = self._render_jinja2(jinja2_text, variable_pool, context_str)
+                else:
+                    content = self._resolve_variable_template(text, variable_pool)
+                    if context_str:
+                        content = content.replace("{{#context#}}", context_str)
+
+                if role == "system":
+                    messages.append(SystemPromptMessage(content=content))
+                elif role == "user":
+                    messages.append(UserPromptMessage(content=content))
+                elif role == "assistant":
+                    messages.append(AssistantPromptMessage(content=content))
+        else:
+            text_content = getattr(template, "text", "") or ""
+            resolved = self._resolve_variable_template(text_content, variable_pool)
+            if context_str:
+                resolved = resolved.replace("{{#context#}}", context_str)
+            messages.append(UserPromptMessage(content=resolved))
+
+        if self._memory is not None:
+            try:
+                window_size = None
+                if self.node_data.memory and hasattr(self.node_data.memory, "window"):
+                    w = self.node_data.memory.window
+                    if w and w.enabled:
+                        window_size = w.size
+
+                history = self._memory.get_history_prompt_messages(
+                    max_token_limit=2000,
+                    message_limit=window_size or 50,
+                )
+                history_list = list(history)
+                logger.info("[AGENT_V2_MEMORY] Loaded %d history messages from memory", len(history_list))
+                if history_list:
+                    system_msgs = [m for m in messages if isinstance(m, SystemPromptMessage)]
+                    other_msgs = [m for m in messages if not isinstance(m, SystemPromptMessage)]
+                    messages = system_msgs + history_list + other_msgs
+                    logger.info("[AGENT_V2_MEMORY] Total prompt messages after memory injection: %d", len(messages))
+            except Exception:
+                logger.warning("Failed to load memory for agent-v2 node", exc_info=True)
+        else:
+            logger.info("[AGENT_V2_MEMORY] No memory injected (self._memory is None)")
+
+        return messages
+
+    def _load_memory_messages(self, dify_ctx: DifyRunContext) -> list[PromptMessage]:
+        """Load conversation history from memory."""
+        from core.memory.token_buffer_memory import TokenBufferMemory
+        from models.model import Conversation
+
+        conversation_id = get_system_text(
+            self.graph_runtime_state.variable_pool,
+            SystemVariableKey.CONVERSATION_ID,
+        )
+        if not conversation_id:
+            return []
+
+        try:
+            from sqlalchemy import select
+            from extensions.ext_database import db
+
+            stmt = select(Conversation).where(Conversation.id == conversation_id)
+            conversation = db.session.scalar(stmt)
+            if not conversation:
+                return []
+
+            model_instance = self._fetch_model_instance(dify_ctx)
+            memory = TokenBufferMemory(conversation=conversation, model_instance=model_instance)
+
+            window_size = None
+            if self.node_data.memory and hasattr(self.node_data.memory, "window"):
+                window = self.node_data.memory.window
+                if window and window.enabled:
+                    window_size = window.size
+
+            history = memory.get_history_prompt_messages(
+                max_token_limit=2000,
+                message_limit=window_size or 50,
+            )
+            return list(history)
+        except Exception:
+            logger.warning("Failed to load memory for agent-v2 node", exc_info=True)
+            return []
+
+    def _build_context_string(self, variable_pool: Any) -> str:
+        """Build context string from knowledge retrieval node output."""
+        ctx_config = self.node_data.context
+        if not ctx_config or not ctx_config.enabled:
+            return ""
+        selector = getattr(ctx_config, "variable_selector", None)
+        if not selector:
+            return ""
+        try:
+            value = variable_pool.get(selector)
+            if value is None:
+                return ""
+            raw = value.value if hasattr(value, "value") else value
+            if isinstance(raw, str):
+                return raw
+            if isinstance(raw, list):
+                parts = []
+                for item in raw:
+                    if isinstance(item, str):
+                        parts.append(item)
+                    elif isinstance(item, dict):
+                        if "content" in item:
+                            parts.append(item["content"])
+                        elif "text" in item:
+                            parts.append(item["text"])
+                return "\n".join(parts)
+            return str(raw)
+        except Exception:
+            logger.warning("Failed to build context string", exc_info=True)
+            return ""
+
+    @staticmethod
+    def _render_jinja2(template: str, variable_pool: Any, context_str: str = "") -> str:
+        """Render a Jinja2 template with variables from the pool."""
+        try:
+            from jinja2 import Environment, BaseLoader
+            env = Environment(loader=BaseLoader(), autoescape=False)
+            tpl = env.from_string(template)
+
+            parser = VariableTemplateParser(template)
+            selectors = parser.extract_variable_selectors()
+            variables: dict[str, Any] = {}
+            for selector in selectors:
+                value = variable_pool.get(selector.value_selector)
+                if value is not None:
+                    variables[selector.variable] = value.text if hasattr(value, "text") else str(value)
+                else:
+                    variables[selector.variable] = ""
+            variables["context"] = context_str
+            return tpl.render(**variables)
+        except Exception:
+            logger.warning("Jinja2 rendering failed, falling back to plain text", exc_info=True)
+            return template
+
+    @staticmethod
+    def _resolve_variable_template(template: str, variable_pool: Any) -> str:
+        """Resolve {{#node.var#}} references in a template string using the variable pool."""
+        parser = VariableTemplateParser(template)
+        selectors = parser.extract_variable_selectors()
+        if not selectors:
+            return template
+
+        inputs: dict[str, Any] = {}
+        for selector in selectors:
+            value = variable_pool.get(selector.value_selector)
+            if value is not None:
+                inputs[selector.variable] = value.text if hasattr(value, "text") else str(value)
+            else:
+                inputs[selector.variable] = ""
+
+        return parser.format(inputs)
+
+    def _get_model_features(self, model_instance: ModelInstance) -> list[ModelFeature]:
+        try:
+            model_schema = model_instance.model_type_instance.get_model_schema(
+                model_instance.model_name,
+                model_instance.credentials,
+            )
+            return list(model_schema.features) if model_schema and model_schema.features else []
+        except Exception:
+            logger.warning("Failed to get model features, assuming none")
+            return []
+
+    @staticmethod
+    def _build_usage_metadata(usage: Any) -> dict:
+        metadata: dict = {}
+        if usage and hasattr(usage, "total_tokens"):
+            metadata[WorkflowNodeExecutionMetadataKey.TOTAL_TOKENS] = usage.total_tokens
+            metadata[WorkflowNodeExecutionMetadataKey.TOTAL_PRICE] = usage.total_price
+            metadata[WorkflowNodeExecutionMetadataKey.CURRENCY] = getattr(usage, "currency", "USD")
+        return metadata
+
+    @staticmethod
+    def _map_strategy_config(
+        config_value: Literal["auto", "function-calling", "chain-of-thought"],
+    ) -> AgentEntity.Strategy | None:
+        mapping = {
+            "function-calling": AgentEntity.Strategy.FUNCTION_CALLING,
+            "chain-of-thought": AgentEntity.Strategy.CHAIN_OF_THOUGHT,
+        }
+        return mapping.get(config_value)
+
+    @staticmethod
+    def _extract_chunk_text(chunk: LLMResultChunk) -> str:
+        if not chunk.delta.message or not chunk.delta.message.content:
+            return ""
+        content = chunk.delta.message.content
+        if isinstance(content, str):
+            return content
+        if isinstance(content, list):
+            parts = []
+            for item in content:
+                if isinstance(item, TextPromptMessageContent):
+                    parts.append(item.data)
+            return "".join(parts)
+        return ""
+
+    @staticmethod
+    def _separate_reasoning(text: str) -> tuple[str, str]:
+        """Extract <think> blocks from text, return (clean_text, reasoning_content)."""
+        reasoning_parts = _THINK_PATTERN.findall(text)
+        reasoning_content = "\n".join(reasoning_parts)
+        clean_text = _THINK_PATTERN.sub("", text).strip()
+        return clean_text, reasoning_content
+
+    @classmethod
+    def _extract_variable_selector_to_variable_mapping(
+        cls,
+        *,
+        graph_config: Mapping[str, Any],
+        node_id: str,
+        node_data: AgentV2NodeData,
+    ) -> Mapping[str, Sequence[str]]:
+        result: dict[str, list[str]] = {}
+
+        if isinstance(node_data.prompt_template, Sequence) and not isinstance(node_data.prompt_template, str):
+            for msg in node_data.prompt_template:
+                text = msg.text or ""
+                jinja2_text = getattr(msg, "jinja2_text", None)
+                content = jinja2_text or text
+                selectors = VariableTemplateParser(content).extract_variable_selectors()
+                for selector in selectors:
+                    result[selector.variable] = list(selector.value_selector)
+        else:
+            text_content = getattr(node_data.prompt_template, "text", "") or ""
+            selectors = VariableTemplateParser(text_content).extract_variable_selectors()
+            for selector in selectors:
+                result[selector.variable] = list(selector.value_selector)
+
+        return {f"{node_id}.{key}": value for key, value in result.items()}

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

@@ -0,0 +1,129 @@
+"""Tool management for Agent V2 Node.
+
+Handles tool instance preparation, conversion to LLM-consumable format,
+and creation of workflow-compatible tool invoke hooks.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING, Any
+
+from core.agent.entities import AgentToolEntity, ExecutionContext
+from core.agent.patterns.base import ToolInvokeHook
+from core.callback_handler.workflow_tool_callback_handler import DifyWorkflowCallbackHandler
+from core.tools.__base.tool import Tool
+from core.tools.entities.tool_entities import ToolInvokeMeta, ToolInvokeMessage
+from core.tools.tool_engine import ToolEngine
+from core.tools.tool_manager import ToolManager
+
+if TYPE_CHECKING:
+    from .entities import ToolMetadata
+
+logger = logging.getLogger(__name__)
+
+
+class AgentV2ToolManager:
+    """Manages tool lifecycle for Agent V2 node execution."""
+
+    def __init__(
+        self,
+        *,
+        tenant_id: str,
+        app_id: str,
+    ) -> None:
+        self._tenant_id = tenant_id
+        self._app_id = app_id
+
+    def prepare_tool_instances(
+        self,
+        tools_config: list[ToolMetadata],
+    ) -> list[Tool]:
+        """Convert tool metadata configs into runtime Tool instances."""
+        tool_instances: list[Tool] = []
+        for tool_meta in tools_config:
+            if not tool_meta.enabled:
+                continue
+            try:
+                processed_settings = {}
+                for key, value in tool_meta.settings.items():
+                    if isinstance(value, dict) and "value" in value and isinstance(value["value"], dict):
+                        if "type" in value["value"] and "value" in value["value"]:
+                            processed_settings[key] = value["value"]
+                        else:
+                            processed_settings[key] = value
+                    else:
+                        processed_settings[key] = value
+
+                merged_parameters = {**tool_meta.parameters, **processed_settings}
+
+                agent_tool = AgentToolEntity(
+                    provider_id=tool_meta.provider_name,
+                    provider_type=tool_meta.type,
+                    tool_name=tool_meta.tool_name,
+                    tool_parameters=merged_parameters,
+                    plugin_unique_identifier=tool_meta.plugin_unique_identifier,
+                    credential_id=tool_meta.credential_id,
+                )
+
+                tool_runtime = ToolManager.get_agent_tool_runtime(
+                    tenant_id=self._tenant_id,
+                    app_id=self._app_id,
+                    agent_tool=agent_tool,
+                )
+                tool_instances.append(tool_runtime)
+            except Exception:
+                logger.warning("Failed to prepare tool %s/%s, skipping", tool_meta.provider_name, tool_meta.tool_name, exc_info=True)
+                continue
+
+        return tool_instances
+
+    def create_workflow_tool_invoke_hook(
+        self,
+        context: ExecutionContext,
+        workflow_call_depth: int = 0,
+    ) -> ToolInvokeHook:
+        """Create a ToolInvokeHook for workflow context."""
+
+        def hook(
+            tool: Tool,
+            tool_args: dict[str, Any],
+            tool_name: str,
+        ) -> tuple[str, list[str], ToolInvokeMeta]:
+            return self._invoke_tool_directly(tool, tool_args, tool_name, context, workflow_call_depth)
+
+        return hook
+
+    def _invoke_tool_directly(
+        self,
+        tool: Tool,
+        tool_args: dict[str, Any],
+        tool_name: str,
+        context: ExecutionContext,
+        workflow_call_depth: int,
+    ) -> tuple[str, list[str], ToolInvokeMeta]:
+        """Invoke tool directly via ToolEngine."""
+        tool_response = ToolEngine.generic_invoke(
+            tool=tool,
+            tool_parameters=tool_args,
+            user_id=context.user_id or "",
+            workflow_tool_callback=DifyWorkflowCallbackHandler(),
+            workflow_call_depth=workflow_call_depth,
+            app_id=context.app_id,
+            conversation_id=context.conversation_id,
+        )
+
+        response_content = ""
+        for response in tool_response:
+            if response.type == ToolInvokeMessage.MessageType.TEXT:
+                assert isinstance(response.message, ToolInvokeMessage.TextMessage)
+                response_content += response.message.text
+            elif response.type == ToolInvokeMessage.MessageType.JSON:
+                if isinstance(response.message, ToolInvokeMessage.JsonMessage):
+                    response_content += json.dumps(response.message.json_object, ensure_ascii=False)
+            elif response.type == ToolInvokeMessage.MessageType.LINK:
+                if isinstance(response.message, ToolInvokeMessage.TextMessage):
+                    response_content += f"[Link: {response.message.text}]"
+
+        return response_content, [], ToolInvokeMeta.empty()

api/dify_graph/entities/tool_entities.py

@@ -0,0 +1,41 @@
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from graphon.file import File
+
+
+class ToolResultStatus(StrEnum):
+    SUCCESS = "success"
+    ERROR = "error"
+
+
+class ToolCall(BaseModel):
+    id: str | None = Field(default=None, description="Unique identifier for this tool call")
+    name: str | None = Field(default=None, description="Name of the tool being called")
+    arguments: str | None = Field(default=None, description="Accumulated tool arguments JSON")
+    icon: str | dict | None = Field(default=None, description="Icon of the tool")
+    icon_dark: str | dict | None = Field(default=None, description="Dark theme icon of the tool")
+
+
+class ToolResult(BaseModel):
+    id: str | None = Field(default=None, description="Identifier of the tool call this result belongs to")
+    name: str | None = Field(default=None, description="Name of the tool")
+    output: str | None = Field(default=None, description="Tool output text, error or success message")
+    files: list[str] = Field(default_factory=list, description="File produced by tool")
+    status: ToolResultStatus | None = Field(default=ToolResultStatus.SUCCESS, description="Tool execution status")
+    elapsed_time: float | None = Field(default=None, description="Elapsed seconds spent executing the tool")
+    icon: str | dict[str, Any] | None = Field(default=None, description="Icon of the tool")
+    icon_dark: str | dict[str, Any] | None = Field(default=None, description="Dark theme icon of the tool")
+    provider: str | None = Field(default=None, description="Tool provider identifier")
+
+
+class ToolCallResult(BaseModel):
+    id: str | None = Field(default=None, description="Identifier for the tool call")
+    name: str | None = Field(default=None, description="Name of the tool")
+    arguments: str | None = Field(default=None, description="Accumulated tool arguments JSON")
+    output: str | None = Field(default=None, description="Tool output text, error or success message")
+    files: list[File] = Field(default_factory=list, description="File produced by tool")
+    status: ToolResultStatus = Field(default=ToolResultStatus.SUCCESS, description="Tool execution status")
+    elapsed_time: float | None = Field(default=None, description="Elapsed seconds spent executing the tool")

api/dify_graph/nodes/agent/agent_node.py

@@ -0,0 +1,935 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Generator, Mapping, Sequence
+from typing import TYPE_CHECKING, Any, cast
+
+from packaging.version import Version
+from pydantic import ValidationError
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from core.agent.entities import AgentToolEntity
+from core.agent.plugin_entities import AgentStrategyParameter
+from core.memory.base import BaseMemory
+from core.memory.node_token_buffer_memory import NodeTokenBufferMemory
+from core.memory.token_buffer_memory import TokenBufferMemory
+from core.model_manager import ModelInstance, ModelManager
+from core.prompt.entities.advanced_prompt_entities import MemoryMode
+from core.plugin.impl.model_runtime_factory import create_plugin_provider_manager
+from core.tools.entities.tool_entities import (
+    ToolIdentity,
+    ToolInvokeMessage,
+    ToolParameter,
+    ToolProviderType,
+)
+from core.tools.tool_manager import ToolManager
+from core.tools.utils.message_transformer import ToolFileMessageTransformer
+from core.workflow.nodes.agent.entities import AgentNodeData, AgentOldVersionModelFeatures, ParamsAutoGenerated
+from core.workflow.nodes.agent.exceptions import (
+    AgentInputTypeError,
+    AgentInvocationError,
+    AgentMessageTransformError,
+    AgentNodeError,
+    AgentVariableNotFoundError,
+    AgentVariableTypeError,
+    ToolFileNotFoundError,
+)
+from graphon.enums import (
+    BuiltinNodeTypes,
+    NodeType,
+    SystemVariableKey,
+    WorkflowNodeExecutionMetadataKey,
+    WorkflowNodeExecutionStatus,
+)
+from graphon.file import File, FileTransferMethod
+from graphon.model_runtime.entities.llm_entities import LLMUsage, LLMUsageMetadata
+from graphon.model_runtime.entities.message_entities import (
+    AssistantPromptMessage,
+    PromptMessage,
+    ToolPromptMessage,
+    UserPromptMessage,
+)
+from graphon.model_runtime.entities.model_entities import AIModelEntity, ModelType
+from graphon.model_runtime.utils.encoders import jsonable_encoder
+from graphon.node_events import (
+    AgentLogEvent,
+    NodeEventBase,
+    NodeRunResult,
+    StreamChunkEvent,
+    StreamCompletedEvent,
+)
+from graphon.nodes.base.node import Node
+from graphon.nodes.base.variable_template_parser import VariableTemplateParser
+from graphon.runtime import VariablePool
+from graphon.variables.segments import ArrayFileSegment, StringSegment
+from core.app.file_access.controller import DatabaseFileAccessController
+from extensions.ext_database import db
+from factories import file_factory
+from factories.agent_factory import get_plugin_agent_strategy
+
+_file_access_controller = DatabaseFileAccessController()
+from models import ToolFile
+from models.model import Conversation
+from services.tools.builtin_tools_manage_service import BuiltinToolManageService
+
+if TYPE_CHECKING:
+    from core.agent.strategy.plugin import PluginAgentStrategy
+    from core.plugin.entities.request import InvokeCredentials
+
+
+class AgentNode(Node[AgentNodeData]):
+    """
+    Agent Node
+    """
+
+    node_type = BuiltinNodeTypes.AGENT
+
+    @classmethod
+    def version(cls) -> str:
+        return "1"
+
+    def _run(self) -> Generator[NodeEventBase, None, None]:
+        from core.plugin.impl.exc import PluginDaemonClientSideError
+
+        dify_ctx = self.require_dify_context()
+
+        try:
+            strategy = get_plugin_agent_strategy(
+                tenant_id=dify_ctx.tenant_id,
+                agent_strategy_provider_name=self.node_data.agent_strategy_provider_name,
+                agent_strategy_name=self.node_data.agent_strategy_name,
+            )
+        except Exception as e:
+            yield StreamCompletedEvent(
+                node_run_result=NodeRunResult(
+                    status=WorkflowNodeExecutionStatus.FAILED,
+                    inputs={},
+                    error=f"Failed to get agent strategy: {str(e)}",
+                ),
+            )
+            return
+
+        agent_parameters = strategy.get_parameters()
+
+        # get parameters
+        parameters = self._generate_agent_parameters(
+            agent_parameters=agent_parameters,
+            variable_pool=self.graph_runtime_state.variable_pool,
+            node_data=self.node_data,
+            strategy=strategy,
+        )
+        parameters_for_log = self._generate_agent_parameters(
+            agent_parameters=agent_parameters,
+            variable_pool=self.graph_runtime_state.variable_pool,
+            node_data=self.node_data,
+            for_log=True,
+            strategy=strategy,
+        )
+        credentials = self._generate_credentials(parameters=parameters)
+
+        # get conversation id
+        conversation_id = self.graph_runtime_state.variable_pool.get(["sys", SystemVariableKey.CONVERSATION_ID])
+
+        try:
+            message_stream = strategy.invoke(
+                params=parameters,
+                user_id=dify_ctx.user_id,
+                app_id=dify_ctx.app_id,
+                conversation_id=conversation_id.text if conversation_id else None,
+                credentials=credentials,
+            )
+        except Exception as e:
+            error = AgentInvocationError(f"Failed to invoke agent: {str(e)}", original_error=e)
+            yield StreamCompletedEvent(
+                node_run_result=NodeRunResult(
+                    status=WorkflowNodeExecutionStatus.FAILED,
+                    inputs=parameters_for_log,
+                    error=str(error),
+                )
+            )
+            return
+
+        # Fetch memory for node memory saving
+        memory = self._fetch_memory_for_save()
+
+        try:
+            yield from self._transform_message(
+                messages=message_stream,
+                tool_info={
+                    "icon": self.agent_strategy_icon,
+                    "agent_strategy": self.node_data.agent_strategy_name,
+                },
+                parameters_for_log=parameters_for_log,
+                user_id=dify_ctx.user_id,
+                tenant_id=dify_ctx.tenant_id,
+                node_type=self.node_type,
+                node_id=self._node_id,
+                node_execution_id=self.id,
+                memory=memory,
+            )
+        except PluginDaemonClientSideError as e:
+            transform_error = AgentMessageTransformError(
+                f"Failed to transform agent message: {str(e)}", original_error=e
+            )
+            yield StreamCompletedEvent(
+                node_run_result=NodeRunResult(
+                    status=WorkflowNodeExecutionStatus.FAILED,
+                    inputs=parameters_for_log,
+                    error=str(transform_error),
+                )
+            )
+
+    def _generate_agent_parameters(
+        self,
+        *,
+        agent_parameters: Sequence[AgentStrategyParameter],
+        variable_pool: VariablePool,
+        node_data: AgentNodeData,
+        for_log: bool = False,
+        strategy: PluginAgentStrategy,
+    ) -> dict[str, Any]:
+        """
+        Generate parameters based on the given tool parameters, variable pool, and node data.
+
+        Args:
+            agent_parameters (Sequence[AgentParameter]): The list of agent parameters.
+            variable_pool (VariablePool): The variable pool containing the variables.
+            node_data (AgentNodeData): The data associated with the agent node.
+
+        Returns:
+            Mapping[str, Any]: A dictionary containing the generated parameters.
+
+        """
+        agent_parameters_dictionary = {parameter.name: parameter for parameter in agent_parameters}
+
+        result: dict[str, Any] = {}
+        for parameter_name in node_data.agent_parameters:
+            parameter = agent_parameters_dictionary.get(parameter_name)
+            if not parameter:
+                result[parameter_name] = None
+                continue
+            agent_input = node_data.agent_parameters[parameter_name]
+            match agent_input.type:
+                case "variable":
+                    variable = variable_pool.get(agent_input.value)  # type: ignore
+                    if variable is None:
+                        raise AgentVariableNotFoundError(str(agent_input.value))
+                    parameter_value = variable.value
+                case "mixed" | "constant":
+                    # variable_pool.convert_template expects a string template,
+                    # but if passing a dict, convert to JSON string first before rendering
+                    try:
+                        if not isinstance(agent_input.value, str):
+                            parameter_value = json.dumps(agent_input.value, ensure_ascii=False)
+                        else:
+                            parameter_value = str(agent_input.value)
+                    except TypeError:
+                        parameter_value = str(agent_input.value)
+                    segment_group = variable_pool.convert_template(parameter_value)
+                    parameter_value = segment_group.log if for_log else segment_group.text
+                    # variable_pool.convert_template returns a string,
+                    # so we need to convert it back to a dictionary
+                    try:
+                        if not isinstance(agent_input.value, str):
+                            parameter_value = json.loads(parameter_value)
+                    except json.JSONDecodeError:
+                        parameter_value = parameter_value
+                case _:
+                    raise AgentInputTypeError(agent_input.type)
+            value = parameter_value
+            if parameter.type == "array[tools]":
+                value = cast(list[dict[str, Any]], value)
+                value = [tool for tool in value if tool.get("enabled", False)]
+                value = self._filter_mcp_type_tool(strategy, value)
+                for tool in value:
+                    if "schemas" in tool:
+                        tool.pop("schemas")
+                    parameters = tool.get("parameters", {})
+                    if all(isinstance(v, dict) for _, v in parameters.items()):
+                        params = {}
+                        for key, param in parameters.items():
+                            if param.get("auto", ParamsAutoGenerated.OPEN) in (
+                                ParamsAutoGenerated.CLOSE,
+                                0,
+                            ):
+                                value_param = param.get("value", {})
+                                if value_param and value_param.get("type", "") == "variable":
+                                    variable_selector = value_param.get("value")
+                                    if not variable_selector:
+                                        raise ValueError("Variable selector is missing for a variable-type parameter.")
+
+                                    variable = variable_pool.get(variable_selector)
+                                    if variable is None:
+                                        raise AgentVariableNotFoundError(str(variable_selector))
+
+                                    params[key] = variable.value
+                                else:
+                                    params[key] = value_param.get("value", "") if value_param is not None else None
+                            else:
+                                params[key] = None
+                        parameters = params
+                    tool["settings"] = {k: v.get("value", None) for k, v in tool.get("settings", {}).items()}
+                    tool["parameters"] = parameters
+
+            if not for_log:
+                if parameter.type == "array[tools]":
+                    value = cast(list[dict[str, Any]], value)
+                    tool_value = []
+                    for tool in value:
+                        provider_type = ToolProviderType(tool.get("type", ToolProviderType.BUILT_IN))
+                        setting_params = tool.get("settings", {})
+                        parameters = tool.get("parameters", {})
+                        manual_input_params = [key for key, value in parameters.items() if value is not None]
+
+                        parameters = {**parameters, **setting_params}
+                        entity = AgentToolEntity(
+                            provider_id=tool.get("provider_name", ""),
+                            provider_type=provider_type,
+                            tool_name=tool.get("tool_name", ""),
+                            tool_parameters=parameters,
+                            plugin_unique_identifier=tool.get("plugin_unique_identifier", None),
+                            credential_id=tool.get("credential_id", None),
+                        )
+
+                        extra = tool.get("extra", {})
+
+                        # This is an issue that caused problems before.
+                        # Logically, we shouldn't use the node_data.version field for judgment
+                        # But for backward compatibility with historical data
+                        # this version field judgment is still preserved here.
+                        runtime_variable_pool: VariablePool | None = None
+                        if node_data.version != "1" or node_data.tool_node_version is not None:
+                            runtime_variable_pool = variable_pool
+                        dify_ctx = self.require_dify_context()
+                        tool_runtime = ToolManager.get_agent_tool_runtime(
+                            dify_ctx.tenant_id,
+                            dify_ctx.app_id,
+                            entity,
+                            dify_ctx.user_id,
+                            dify_ctx.invoke_from,
+                            runtime_variable_pool,
+                        )
+                        if tool_runtime.entity.description:
+                            tool_runtime.entity.description.llm = (
+                                extra.get("description", "") or tool_runtime.entity.description.llm
+                            )
+                        for tool_runtime_params in tool_runtime.entity.parameters:
+                            tool_runtime_params.form = (
+                                ToolParameter.ToolParameterForm.FORM
+                                if tool_runtime_params.name in manual_input_params
+                                else tool_runtime_params.form
+                            )
+                        manual_input_value = {}
+                        if tool_runtime.entity.parameters:
+                            manual_input_value = {
+                                key: value for key, value in parameters.items() if key in manual_input_params
+                            }
+                        runtime_parameters = {
+                            **tool_runtime.runtime.runtime_parameters,
+                            **manual_input_value,
+                        }
+                        tool_value.append(
+                            {
+                                **tool_runtime.entity.model_dump(mode="json"),
+                                "runtime_parameters": runtime_parameters,
+                                "credential_id": tool.get("credential_id", None),
+                                "provider_type": provider_type.value,
+                            }
+                        )
+                    value = tool_value
+                if parameter.type == AgentStrategyParameter.AgentStrategyParameterType.MODEL_SELECTOR:
+                    value = cast(dict[str, Any], value)
+                    model_instance, model_schema = self._fetch_model(value)
+                    # memory config
+                    history_prompt_messages = []
+                    if node_data.memory:
+                        memory = self._fetch_memory(model_instance)
+                        if memory:
+                            prompt_messages = memory.get_history_prompt_messages(
+                                message_limit=node_data.memory.window.size or None
+                            )
+                            history_prompt_messages = [
+                                prompt_message.model_dump(mode="json") for prompt_message in prompt_messages
+                            ]
+                    value["history_prompt_messages"] = history_prompt_messages
+                    if model_schema:
+                        # remove structured output feature to support old version agent plugin
+                        model_schema = self._remove_unsupported_model_features_for_old_version(model_schema)
+                        value["entity"] = model_schema.model_dump(mode="json")
+                    else:
+                        value["entity"] = None
+            result[parameter_name] = value
+
+        return result
+
+    def _generate_credentials(
+        self,
+        parameters: dict[str, Any],
+    ) -> InvokeCredentials:
+        """
+        Generate credentials based on the given agent parameters.
+        """
+        from core.plugin.entities.request import InvokeCredentials
+
+        credentials = InvokeCredentials()
+
+        # generate credentials for tools selector
+        credentials.tool_credentials = {}
+        for tool in parameters.get("tools", []):
+            if tool.get("credential_id"):
+                try:
+                    identity = ToolIdentity.model_validate(tool.get("identity", {}))
+                    credentials.tool_credentials[identity.provider] = tool.get("credential_id", None)
+                except ValidationError:
+                    continue
+        return credentials
+
+    @classmethod
+    def _extract_variable_selector_to_variable_mapping(
+        cls,
+        *,
+        graph_config: Mapping[str, Any],
+        node_id: str,
+        node_data: AgentNodeData,
+    ) -> Mapping[str, Sequence[str]]:
+        typed_node_data = node_data
+
+        result: dict[str, Any] = {}
+        for parameter_name in typed_node_data.agent_parameters:
+            input = typed_node_data.agent_parameters[parameter_name]
+            match input.type:
+                case "mixed" | "constant":
+                    selectors = VariableTemplateParser(str(input.value)).extract_variable_selectors()
+                    for selector in selectors:
+                        result[selector.variable] = selector.value_selector
+                case "variable":
+                    result[parameter_name] = input.value
+
+        result = {node_id + "." + key: value for key, value in result.items()}
+
+        return result
+
+    @property
+    def agent_strategy_icon(self) -> str | None:
+        """
+        Get agent strategy icon
+        :return:
+        """
+        from core.plugin.impl.plugin import PluginInstaller
+
+        manager = PluginInstaller()
+        dify_ctx = self.require_dify_context()
+        plugins = manager.list_plugins(dify_ctx.tenant_id)
+        try:
+            current_plugin = next(
+                plugin
+                for plugin in plugins
+                if f"{plugin.plugin_id}/{plugin.name}" == self.node_data.agent_strategy_provider_name
+            )
+            icon = current_plugin.declaration.icon
+        except StopIteration:
+            icon = None
+        return icon
+
+    def _fetch_memory(self, model_instance: ModelInstance) -> BaseMemory | TokenBufferMemory | None:
+        """
+        Fetch memory based on configuration mode.
+
+        Returns TokenBufferMemory for conversation mode (default),
+        or NodeTokenBufferMemory for node mode (Chatflow only).
+        """
+        node_data = self.node_data
+        memory_config = node_data.memory
+
+        if not memory_config:
+            return None
+
+        # get conversation id (required for both modes in Chatflow)
+        conversation_id_variable = self.graph_runtime_state.variable_pool.get(
+            ["sys", SystemVariableKey.CONVERSATION_ID]
+        )
+        if not isinstance(conversation_id_variable, StringSegment):
+            return None
+        conversation_id = conversation_id_variable.value
+
+        dify_ctx = self.require_dify_context()
+        if memory_config.mode == MemoryMode.NODE:
+            return NodeTokenBufferMemory(
+                app_id=dify_ctx.app_id,
+                conversation_id=conversation_id,
+                node_id=self._node_id,
+                tenant_id=dify_ctx.tenant_id,
+                model_instance=model_instance,
+            )
+        else:
+            with Session(db.engine, expire_on_commit=False) as session:
+                stmt = select(Conversation).where(
+                    Conversation.app_id == dify_ctx.app_id, Conversation.id == conversation_id
+                )
+                conversation = session.scalar(stmt)
+                if not conversation:
+                    return None
+            return TokenBufferMemory(conversation=conversation, model_instance=model_instance)
+
+    def _fetch_model(self, value: dict[str, Any]) -> tuple[ModelInstance, AIModelEntity | None]:
+        dify_ctx = self.require_dify_context()
+        provider_manager = create_plugin_provider_manager(
+            tenant_id=dify_ctx.tenant_id, user_id=dify_ctx.user_id
+        )
+        provider_model_bundle = provider_manager.get_provider_model_bundle(
+            tenant_id=dify_ctx.tenant_id, provider=value.get("provider", ""), model_type=ModelType.LLM
+        )
+        model_name = value.get("model", "")
+        model_credentials = provider_model_bundle.configuration.get_current_credentials(
+            model_type=ModelType.LLM, model=model_name
+        )
+        provider_name = provider_model_bundle.configuration.provider.provider
+        model_type_instance = provider_model_bundle.model_type_instance
+        model_instance = ModelManager(provider_manager).get_model_instance(
+            tenant_id=dify_ctx.tenant_id,
+            provider=provider_name,
+            model_type=ModelType(value.get("model_type", "")),
+            model=model_name,
+        )
+        model_schema = model_type_instance.get_model_schema(model_name, model_credentials)
+        return model_instance, model_schema
+
+    def _remove_unsupported_model_features_for_old_version(self, model_schema: AIModelEntity) -> AIModelEntity:
+        if model_schema.features:
+            for feature in model_schema.features[:]:  # Create a copy to safely modify during iteration
+                try:
+                    AgentOldVersionModelFeatures(feature.value)  # Try to create enum member from value
+                except ValueError:
+                    model_schema.features.remove(feature)
+        return model_schema
+
+    def _filter_mcp_type_tool(self, strategy: PluginAgentStrategy, tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """
+        Filter MCP type tool
+        :param strategy: plugin agent strategy
+        :param tool: tool
+        :return: filtered tool dict
+        """
+        meta_version = strategy.meta_version
+        if meta_version and Version(meta_version) > Version("0.0.1"):
+            return tools
+        else:
+            return [tool for tool in tools if tool.get("type") != ToolProviderType.MCP]
+
+    def _fetch_memory_for_save(self) -> BaseMemory | None:
+        """
+        Fetch memory instance for saving node memory.
+        This is a simplified version that doesn't require model_instance.
+        """
+        from graphon.model_runtime.entities.model_entities import ModelType
+
+        node_data = self.node_data
+        if not node_data.memory:
+            return None
+
+        # Get conversation_id
+        conversation_id_var = self.graph_runtime_state.variable_pool.get(["sys", SystemVariableKey.CONVERSATION_ID])
+        if not isinstance(conversation_id_var, StringSegment):
+            return None
+        conversation_id = conversation_id_var.value
+
+        # Return appropriate memory type based on mode
+        if node_data.memory.mode == MemoryMode.NODE:
+            try:
+                provider_manager = create_plugin_provider_manager(tenant_id=self.tenant_id)
+                model_instance = ModelManager(provider_manager).get_default_model_instance(
+                    tenant_id=self.tenant_id,
+                    model_type=ModelType.LLM,
+                )
+            except Exception:
+                return None
+
+            return NodeTokenBufferMemory(
+                app_id=self.app_id,
+                conversation_id=conversation_id,
+                node_id=self._node_id,
+                tenant_id=self.tenant_id,
+                model_instance=model_instance,
+            )
+        else:
+            # Conversation-level memory doesn't need saving here
+            return None
+
+    def _build_context(
+        self,
+        parameters_for_log: dict[str, Any],
+        user_query: str,
+        assistant_response: str,
+        agent_logs: list[AgentLogEvent],
+    ) -> list[PromptMessage]:
+        """
+        Build context from user query, tool calls, and assistant response.
+        Format: user -> assistant(with tool_calls) -> tool -> assistant
+
+        The context includes:
+        - Current user query (always present, may be empty)
+        - Assistant message with tool_calls (if tools were called)
+        - Tool results
+        - Assistant's final response
+        """
+        context_messages: list[PromptMessage] = []
+
+        # Always add user query (even if empty, to maintain conversation structure)
+        context_messages.append(UserPromptMessage(content=user_query or ""))
+
+        # Extract actual tool calls from agent logs
+        # Only include logs with label starting with "CALL " - these are real tool invocations
+        tool_calls: list[AssistantPromptMessage.ToolCall] = []
+        tool_results: list[tuple[str, str, str]] = []  # (tool_call_id, tool_name, result)
+
+        for log in agent_logs:
+            if log.status == "success" and log.label and log.label.startswith("CALL "):
+                # Extract tool name from label (format: "CALL tool_name")
+                tool_name = log.label[5:]  # Remove "CALL " prefix
+                tool_call_id = log.message_id
+
+                # Parse tool response from data
+                data = log.data or {}
+                tool_response = ""
+
+                # Try to extract the actual tool response
+                if "tool_response" in data:
+                    tool_response = data["tool_response"]
+                elif "output" in data:
+                    tool_response = data["output"]
+                elif "result" in data:
+                    tool_response = data["result"]
+
+                if isinstance(tool_response, dict):
+                    tool_response = str(tool_response)
+
+                # Get tool input for arguments
+                tool_input = data.get("tool_call_input", {}) or data.get("input", {})
+                if isinstance(tool_input, dict):
+                    import json
+
+                    tool_input_str = json.dumps(tool_input, ensure_ascii=False)
+                else:
+                    tool_input_str = str(tool_input) if tool_input else ""
+
+                if tool_response:
+                    tool_calls.append(
+                        AssistantPromptMessage.ToolCall(
+                            id=tool_call_id,
+                            type="function",
+                            function=AssistantPromptMessage.ToolCall.ToolCallFunction(
+                                name=tool_name,
+                                arguments=tool_input_str,
+                            ),
+                        )
+                    )
+                    tool_results.append((tool_call_id, tool_name, str(tool_response)))
+
+        # Add assistant message with tool_calls if there were tool calls
+        if tool_calls:
+            context_messages.append(AssistantPromptMessage(content="", tool_calls=tool_calls))
+
+            # Add tool result messages
+            for tool_call_id, tool_name, result in tool_results:
+                context_messages.append(
+                    ToolPromptMessage(
+                        content=result,
+                        tool_call_id=tool_call_id,
+                        name=tool_name,
+                    )
+                )
+
+        # Add final assistant response
+        context_messages.append(AssistantPromptMessage(content=assistant_response))
+
+        return context_messages
+
+    def _transform_message(
+        self,
+        messages: Generator[ToolInvokeMessage, None, None],
+        tool_info: Mapping[str, Any],
+        parameters_for_log: dict[str, Any],
+        user_id: str,
+        tenant_id: str,
+        node_type: NodeType,
+        node_id: str,
+        node_execution_id: str,
+        memory: BaseMemory | None = None,
+    ) -> Generator[NodeEventBase, None, None]:
+        """
+        Convert ToolInvokeMessages into tuple[plain_text, files]
+        """
+        # transform message and handle file storage
+        from core.plugin.impl.plugin import PluginInstaller
+
+        message_stream = ToolFileMessageTransformer.transform_tool_invoke_messages(
+            messages=messages,
+            user_id=user_id,
+            tenant_id=tenant_id,
+            conversation_id=None,
+        )
+
+        text = ""
+        files: list[File] = []
+        json_list: list[dict | list] = []
+
+        agent_logs: list[AgentLogEvent] = []
+        agent_execution_metadata: Mapping[WorkflowNodeExecutionMetadataKey, Any] = {}
+        llm_usage = LLMUsage.empty_usage()
+        variables: dict[str, Any] = {}
+
+        for message in message_stream:
+            if message.type in {
+                ToolInvokeMessage.MessageType.IMAGE_LINK,
+                ToolInvokeMessage.MessageType.BINARY_LINK,
+                ToolInvokeMessage.MessageType.IMAGE,
+            }:
+                assert isinstance(message.message, ToolInvokeMessage.TextMessage)
+
+                url = message.message.text
+                if message.meta:
+                    transfer_method = message.meta.get("transfer_method", FileTransferMethod.TOOL_FILE)
+                else:
+                    transfer_method = FileTransferMethod.TOOL_FILE
+
+                tool_file_id = str(url).split("/")[-1].split(".")[0]
+
+                with Session(db.engine) as session:
+                    stmt = select(ToolFile).where(ToolFile.id == tool_file_id)
+                    tool_file = session.scalar(stmt)
+                    if tool_file is None:
+                        raise ToolFileNotFoundError(tool_file_id)
+
+                mapping = {
+                    "tool_file_id": tool_file_id,
+                    "type": file_factory.get_file_type_by_mime_type(tool_file.mimetype),
+                    "transfer_method": transfer_method,
+                    "url": url,
+                }
+                file = file_factory.build_from_mapping(
+                    mapping=mapping,
+                    tenant_id=tenant_id,
+                    access_controller=_file_access_controller,
+                )
+                files.append(file)
+            elif message.type == ToolInvokeMessage.MessageType.BLOB:
+                # get tool file id
+                assert isinstance(message.message, ToolInvokeMessage.TextMessage)
+                assert message.meta
+
+                tool_file_id = message.message.text.split("/")[-1].split(".")[0]
+                with Session(db.engine) as session:
+                    stmt = select(ToolFile).where(ToolFile.id == tool_file_id)
+                    tool_file = session.scalar(stmt)
+                    if tool_file is None:
+                        raise ToolFileNotFoundError(tool_file_id)
+
+                mapping = {
+                    "tool_file_id": tool_file_id,
+                    "transfer_method": FileTransferMethod.TOOL_FILE,
+                }
+
+                files.append(
+                    file_factory.build_from_mapping(
+                        mapping=mapping,
+                        tenant_id=tenant_id,
+                        access_controller=_file_access_controller,
+                    )
+                )
+            elif message.type == ToolInvokeMessage.MessageType.TEXT:
+                assert isinstance(message.message, ToolInvokeMessage.TextMessage)
+                text += message.message.text
+                yield StreamChunkEvent(
+                    selector=[node_id, "text"],
+                    chunk=message.message.text,
+                    is_final=False,
+                )
+            elif message.type == ToolInvokeMessage.MessageType.JSON:
+                assert isinstance(message.message, ToolInvokeMessage.JsonMessage)
+                if node_type == BuiltinNodeTypes.AGENT:
+                    if isinstance(message.message.json_object, dict):
+                        msg_metadata: dict[str, Any] = message.message.json_object.pop("execution_metadata", {})
+                        llm_usage = LLMUsage.from_metadata(cast(LLMUsageMetadata, msg_metadata))
+                        agent_execution_metadata = {
+                            WorkflowNodeExecutionMetadataKey(key): value
+                            for key, value in msg_metadata.items()
+                            if key in WorkflowNodeExecutionMetadataKey.__members__.values()
+                        }
+                    else:
+                        msg_metadata = {}
+                        llm_usage = LLMUsage.empty_usage()
+                        agent_execution_metadata = {}
+                if message.message.json_object:
+                    json_list.append(message.message.json_object)
+            elif message.type == ToolInvokeMessage.MessageType.LINK:
+                assert isinstance(message.message, ToolInvokeMessage.TextMessage)
+                stream_text = f"Link: {message.message.text}\n"
+                text += stream_text
+                yield StreamChunkEvent(
+                    selector=[node_id, "text"],
+                    chunk=stream_text,
+                    is_final=False,
+                )
+            elif message.type == ToolInvokeMessage.MessageType.VARIABLE:
+                assert isinstance(message.message, ToolInvokeMessage.VariableMessage)
+                variable_name = message.message.variable_name
+                variable_value = message.message.variable_value
+                if message.message.stream:
+                    if not isinstance(variable_value, str):
+                        raise AgentVariableTypeError(
+                            "When 'stream' is True, 'variable_value' must be a string.",
+                            variable_name=variable_name,
+                            expected_type="str",
+                            actual_type=type(variable_value).__name__,
+                        )
+                    if variable_name not in variables:
+                        variables[variable_name] = ""
+                    variables[variable_name] += variable_value
+
+                    yield StreamChunkEvent(
+                        selector=[node_id, variable_name],
+                        chunk=variable_value,
+                        is_final=False,
+                    )
+                else:
+                    variables[variable_name] = variable_value
+            elif message.type == ToolInvokeMessage.MessageType.FILE:
+                assert message.meta is not None
+                assert isinstance(message.meta, dict)
+                # Validate that meta contains a 'file' key
+                if "file" not in message.meta:
+                    raise AgentNodeError("File message is missing 'file' key in meta")
+
+                # Validate that the file is an instance of File
+                if not isinstance(message.meta["file"], File):
+                    raise AgentNodeError(f"Expected File object but got {type(message.meta['file']).__name__}")
+                files.append(message.meta["file"])
+            elif message.type == ToolInvokeMessage.MessageType.LOG:
+                assert isinstance(message.message, ToolInvokeMessage.LogMessage)
+                if message.message.metadata:
+                    icon = tool_info.get("icon", "")
+                    dict_metadata = dict(message.message.metadata)
+                    if dict_metadata.get("provider"):
+                        manager = PluginInstaller()
+                        plugins = manager.list_plugins(tenant_id)
+                        try:
+                            current_plugin = next(
+                                plugin
+                                for plugin in plugins
+                                if f"{plugin.plugin_id}/{plugin.name}" == dict_metadata["provider"]
+                            )
+                            icon = current_plugin.declaration.icon
+                        except StopIteration:
+                            pass
+                        icon_dark = None
+                        try:
+                            builtin_tool = next(
+                                provider
+                                for provider in BuiltinToolManageService.list_builtin_tools(
+                                    user_id,
+                                    tenant_id,
+                                )
+                                if provider.name == dict_metadata["provider"]
+                            )
+                            icon = builtin_tool.icon
+                            icon_dark = builtin_tool.icon_dark
+                        except StopIteration:
+                            pass
+
+                        dict_metadata["icon"] = icon
+                        dict_metadata["icon_dark"] = icon_dark
+                        message.message.metadata = dict_metadata
+                agent_log = AgentLogEvent(
+                    message_id=message.message.id,
+                    node_execution_id=node_execution_id,
+                    parent_id=message.message.parent_id,
+                    error=message.message.error,
+                    status=message.message.status.value,
+                    data=message.message.data,
+                    label=message.message.label,
+                    metadata=message.message.metadata,
+                    node_id=node_id,
+                )
+
+                # check if the agent log is already in the list
+                for log in agent_logs:
+                    if log.message_id == agent_log.message_id:
+                        # update the log
+                        log.data = agent_log.data
+                        log.status = agent_log.status
+                        log.error = agent_log.error
+                        log.label = agent_log.label
+                        log.metadata = agent_log.metadata
+                        break
+                else:
+                    agent_logs.append(agent_log)
+
+                yield agent_log
+
+        # Add agent_logs to outputs['json'] to ensure frontend can access thinking process
+        json_output: list[dict[str, Any] | list[Any]] = []
+
+        # Step 1: append each agent log as its own dict.
+        if agent_logs:
+            for log in agent_logs:
+                json_output.append(
+                    {
+                        "id": log.message_id,
+                        "parent_id": log.parent_id,
+                        "error": log.error,
+                        "status": log.status,
+                        "data": log.data,
+                        "label": log.label,
+                        "metadata": log.metadata,
+                        "node_id": log.node_id,
+                    }
+                )
+        # Step 2: normalize JSON into {"data": [...]}.change json to list[dict]
+        if json_list:
+            json_output.extend(json_list)
+        else:
+            json_output.append({"data": []})
+
+        # Send final chunk events for all streamed outputs
+        # Final chunk for text stream
+        yield StreamChunkEvent(
+            selector=[node_id, "text"],
+            chunk="",
+            is_final=True,
+        )
+
+        # Final chunks for any streamed variables
+        for var_name in variables:
+            yield StreamChunkEvent(
+                selector=[node_id, var_name],
+                chunk="",
+                is_final=True,
+            )
+
+        # Get user query from parameters for building context
+        user_query = parameters_for_log.get("query", "")
+
+        # Build context from history, user query, tool calls and assistant response
+        context = self._build_context(parameters_for_log, user_query, text, agent_logs)
+
+        yield StreamCompletedEvent(
+            node_run_result=NodeRunResult(
+                status=WorkflowNodeExecutionStatus.SUCCEEDED,
+                outputs={
+                    "text": text,
+                    "usage": jsonable_encoder(llm_usage),
+                    "files": ArrayFileSegment(value=files),
+                    "json": json_output,
+                    "context": context,
+                    **variables,
+                },
+                metadata={
+                    **agent_execution_metadata,
+                    WorkflowNodeExecutionMetadataKey.TOOL_INFO: tool_info,
+                    WorkflowNodeExecutionMetadataKey.AGENT_LOG: agent_logs,
+                },
+                inputs=parameters_for_log,
+                llm_usage=llm_usage,
+            )
+        )

api/extensions/ext_socketio.py

@@ -0,0 +1,5 @@
+import socketio  # type: ignore[reportMissingTypeStubs]
+
+from configs import dify_config
+
+sio = socketio.Server(async_mode="gevent", cors_allowed_origins=dify_config.CONSOLE_CORS_ALLOW_ORIGINS)

api/extensions/storage/file_presign_storage.py

@@ -0,0 +1,73 @@
+"""Storage wrapper that provides presigned URL support with fallback to ticket-based URLs.
+
+This is the unified presign wrapper for all storage operations. When the underlying
+storage backend doesn't support presigned URLs (raises NotImplementedError), it falls
+back to generating ticket-based URLs that route through Dify's file proxy endpoints.
+
+Usage:
+    from extensions.storage.file_presign_storage import FilePresignStorage
+
+    # Wrap any BaseStorage to add presign support
+    presign_storage = FilePresignStorage(base_storage)
+    download_url = presign_storage.get_download_url("path/to/file.txt", expires_in=3600)
+    upload_url = presign_storage.get_upload_url("path/to/file.txt", expires_in=3600)
+
+When the underlying storage doesn't support presigned URLs, the fallback URLs follow the format:
+    {FILES_API_URL}/files/storage-files/{token}  (falls back to FILES_URL)
+
+The token is a UUID that maps to the real storage key in Redis.
+"""
+
+from extensions.storage.storage_wrapper import StorageWrapper
+
+
+class FilePresignStorage(StorageWrapper):
+    """Storage wrapper that provides presigned URL support with ticket fallback.
+
+    If the wrapped storage supports presigned URLs, delegates to it.
+    Otherwise, generates ticket-based URLs for both download and upload operations.
+    """
+
+    def get_download_url(
+        self,
+        filename: str,
+        expires_in: int = 3600,
+        *,
+        download_filename: str | None = None,
+    ) -> str:
+        """Get a presigned download URL, falling back to ticket URL if not supported."""
+        try:
+            return self._storage.get_download_url(filename, expires_in, download_filename=download_filename)
+        except NotImplementedError:
+            from services.storage_ticket_service import StorageTicketService
+
+            return StorageTicketService.create_download_url(filename, expires_in=expires_in, filename=download_filename)
+
+    def get_download_urls(
+        self,
+        filenames: list[str],
+        expires_in: int = 3600,
+        *,
+        download_filenames: list[str] | None = None,
+    ) -> list[str]:
+        """Get presigned download URLs for multiple files."""
+        try:
+            return self._storage.get_download_urls(filenames, expires_in, download_filenames=download_filenames)
+        except NotImplementedError:
+            from services.storage_ticket_service import StorageTicketService
+
+            if download_filenames is None:
+                return [StorageTicketService.create_download_url(f, expires_in=expires_in) for f in filenames]
+            return [
+                StorageTicketService.create_download_url(f, expires_in=expires_in, filename=df)
+                for f, df in zip(filenames, download_filenames, strict=True)
+            ]
+
+    def get_upload_url(self, filename: str, expires_in: int = 3600) -> str:
+        """Get a presigned upload URL, falling back to ticket URL if not supported."""
+        try:
+            return self._storage.get_upload_url(filename, expires_in)
+        except NotImplementedError:
+            from services.storage_ticket_service import StorageTicketService
+
+            return StorageTicketService.create_upload_url(filename, expires_in=expires_in)

api/extensions/storage/storage_wrapper.py

@@ -0,0 +1,66 @@
+"""Base class for storage wrappers that delegate to an inner storage."""
+
+from collections.abc import Generator
+
+from extensions.storage.base_storage import BaseStorage
+
+
+class StorageWrapper(BaseStorage):
+    """Base class for storage wrappers using the decorator pattern.
+
+    Forwards all BaseStorage methods to the wrapped storage by default.
+    Subclasses can override specific methods to customize behavior.
+
+    Example:
+        class MyCustomStorage(StorageWrapper):
+            def save(self, filename: str, data: bytes):
+                # Custom logic before save
+                super().save(filename, data)
+                # Custom logic after save
+    """
+
+    def __init__(self, storage: BaseStorage):
+        super().__init__()
+        self._storage = storage
+
+    def save(self, filename: str, data: bytes):
+        self._storage.save(filename, data)
+
+    def load_once(self, filename: str) -> bytes:
+        return self._storage.load_once(filename)
+
+    def load_stream(self, filename: str) -> Generator:
+        return self._storage.load_stream(filename)
+
+    def download(self, filename: str, target_filepath: str):
+        self._storage.download(filename, target_filepath)
+
+    def exists(self, filename: str) -> bool:
+        return self._storage.exists(filename)
+
+    def delete(self, filename: str):
+        self._storage.delete(filename)
+
+    def scan(self, path: str, files: bool = True, directories: bool = False) -> list[str]:
+        return self._storage.scan(path, files=files, directories=directories)
+
+    def get_download_url(
+        self,
+        filename: str,
+        expires_in: int = 3600,
+        *,
+        download_filename: str | None = None,
+    ) -> str:
+        return self._storage.get_download_url(filename, expires_in, download_filename=download_filename)
+
+    def get_download_urls(
+        self,
+        filenames: list[str],
+        expires_in: int = 3600,
+        *,
+        download_filenames: list[str] | None = None,
+    ) -> list[str]:
+        return self._storage.get_download_urls(filenames, expires_in, download_filenames=download_filenames)
+
+    def get_upload_url(self, filename: str, expires_in: int = 3600) -> str:
+        return self._storage.get_upload_url(filename, expires_in)

api/fields/online_user_fields.py

@@ -0,0 +1,17 @@
+from flask_restx import fields
+
+online_user_partial_fields = {
+    "user_id": fields.String,
+    "username": fields.String,
+    "avatar": fields.String,
+    "sid": fields.String,
+}
+
+workflow_online_users_fields = {
+    "workflow_id": fields.String,
+    "users": fields.List(fields.Nested(online_user_partial_fields)),
+}
+
+online_user_list_fields = {
+    "data": fields.List(fields.Nested(workflow_online_users_fields)),
+}

api/fields/workflow_comment_fields.py

@@ -0,0 +1,96 @@
+from flask_restx import fields
+
+from libs.helper import AvatarUrlField, TimestampField
+
+# basic account fields for comments
+account_fields = {
+    "id": fields.String,
+    "name": fields.String,
+    "email": fields.String,
+    "avatar_url": AvatarUrlField,
+}
+
+# Comment mention fields
+workflow_comment_mention_fields = {
+    "mentioned_user_id": fields.String,
+    "mentioned_user_account": fields.Nested(account_fields, allow_null=True),
+    "reply_id": fields.String,
+}
+
+# Comment reply fields
+workflow_comment_reply_fields = {
+    "id": fields.String,
+    "content": fields.String,
+    "created_by": fields.String,
+    "created_by_account": fields.Nested(account_fields, allow_null=True),
+    "created_at": TimestampField,
+}
+
+# Basic comment fields (for list views)
+workflow_comment_basic_fields = {
+    "id": fields.String,
+    "position_x": fields.Float,
+    "position_y": fields.Float,
+    "content": fields.String,
+    "created_by": fields.String,
+    "created_by_account": fields.Nested(account_fields, allow_null=True),
+    "created_at": TimestampField,
+    "updated_at": TimestampField,
+    "resolved": fields.Boolean,
+    "resolved_at": TimestampField,
+    "resolved_by": fields.String,
+    "resolved_by_account": fields.Nested(account_fields, allow_null=True),
+    "reply_count": fields.Integer,
+    "mention_count": fields.Integer,
+    "participants": fields.List(fields.Nested(account_fields)),
+}
+
+# Detailed comment fields (for single comment view)
+workflow_comment_detail_fields = {
+    "id": fields.String,
+    "position_x": fields.Float,
+    "position_y": fields.Float,
+    "content": fields.String,
+    "created_by": fields.String,
+    "created_by_account": fields.Nested(account_fields, allow_null=True),
+    "created_at": TimestampField,
+    "updated_at": TimestampField,
+    "resolved": fields.Boolean,
+    "resolved_at": TimestampField,
+    "resolved_by": fields.String,
+    "resolved_by_account": fields.Nested(account_fields, allow_null=True),
+    "replies": fields.List(fields.Nested(workflow_comment_reply_fields)),
+    "mentions": fields.List(fields.Nested(workflow_comment_mention_fields)),
+}
+
+# Comment creation response fields (simplified)
+workflow_comment_create_fields = {
+    "id": fields.String,
+    "created_at": TimestampField,
+}
+
+# Comment update response fields (simplified)
+workflow_comment_update_fields = {
+    "id": fields.String,
+    "updated_at": TimestampField,
+}
+
+# Comment resolve response fields
+workflow_comment_resolve_fields = {
+    "id": fields.String,
+    "resolved": fields.Boolean,
+    "resolved_at": TimestampField,
+    "resolved_by": fields.String,
+}
+
+# Reply creation response fields (simplified)
+workflow_comment_reply_create_fields = {
+    "id": fields.String,
+    "created_at": TimestampField,
+}
+
+# Reply update response fields
+workflow_comment_reply_update_fields = {
+    "id": fields.String,
+    "updated_at": TimestampField,
+}

api/libs/attr_map.py

@@ -0,0 +1,163 @@
+"""
+Type-safe attribute storage inspired by Netty's AttributeKey/AttributeMap pattern.
+
+Provides loosely-coupled typed attribute storage where only code with access
+to the same AttrKey instance can read/write the corresponding attribute.
+
+    SESSION_KEY: AttrKey[Session] = AttrKey("session", Session)
+    attrs = AttrMap()
+    attrs.set(SESSION_KEY, session)
+    session = attrs.get(SESSION_KEY)  # -> Session (raises if not set)
+    session = attrs.get_or_none(SESSION_KEY)  # -> Session | None
+
+Note: AttrMap is NOT thread-safe. Each instance should be confined to a single
+thread/context (e.g., one AttrMap per Sandbox/VirtualEnvironment instance).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Generic, TypeVar, cast, final, overload
+
+T = TypeVar("T")
+D = TypeVar("D")
+
+
+@final
+class AttrKey(Generic[T]):
+    """
+    A type-safe key for attribute storage.
+
+    Identity-based: different AttrKey instances with same name are distinct keys.
+    This enables different modules to define keys independently without collision.
+    """
+
+    __slots__ = ("_name", "_type")
+
+    def __init__(self, name: str, type_: type[T]) -> None:
+        self._name = name
+        self._type = type_
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def type_(self) -> type[T]:
+        return self._type
+
+    def __repr__(self) -> str:
+        return f"AttrKey({self._name!r}, {self._type.__name__})"
+
+    def __hash__(self) -> int:
+        return id(self)
+
+    def __eq__(self, other: object) -> bool:
+        return self is other
+
+
+class AttrMapKeyError(KeyError):
+    """Raised when a required attribute is not set."""
+
+    key: AttrKey[Any]
+
+    def __init__(self, key: AttrKey[Any]) -> None:
+        self.key = key
+        super().__init__(f"Required attribute '{key.name}' (type: {key.type_.__name__}) is not set")
+
+
+class AttrMapTypeError(TypeError):
+    """Raised when attribute value type doesn't match the key's declared type."""
+
+    key: AttrKey[Any]
+    expected_type: type[Any]
+    actual_type: type[Any]
+
+    def __init__(self, key: AttrKey[Any], expected_type: type[Any], actual_type: type[Any]) -> None:
+        self.key = key
+        self.expected_type = expected_type
+        self.actual_type = actual_type
+        super().__init__(
+            f"Attribute '{key.name}' expects type '{expected_type.__name__}', got '{actual_type.__name__}'"
+        )
+
+
+@final
+class AttrMap:
+    """
+    Thread-confined container for storing typed attributes using AttrKey instances.
+
+    NOT thread-safe. Each instance should be owned by a single context
+    (e.g., one AttrMap per Sandbox/VirtualEnvironment instance).
+    """
+
+    __slots__ = ("_data",)
+
+    def __init__(self) -> None:
+        self._data: dict[AttrKey[Any], Any] = {}
+
+    def set(self, key: AttrKey[T], value: T, *, validate: bool = True) -> None:
+        """
+        Store an attribute. Raises AttrMapTypeError if validate=True and type mismatches.
+
+        Note: Runtime validation only checks outer type (e.g., `list` not `list[str]`).
+        """
+        if validate and not isinstance(value, key.type_):
+            raise AttrMapTypeError(key, key.type_, type(value))
+        self._data[key] = value
+
+    def get(self, key: AttrKey[T]) -> T:
+        """Retrieve an attribute. Raises AttrMapKeyError if not set."""
+        if key not in self._data:
+            raise AttrMapKeyError(key)
+        return cast(T, self._data[key])
+
+    def get_or_none(self, key: AttrKey[T]) -> T | None:
+        """Retrieve an attribute, returning None if not set."""
+        return cast(T | None, self._data.get(key))
+
+    @overload
+    def get_or_default(self, key: AttrKey[T], default: T) -> T: ...
+
+    @overload
+    def get_or_default(self, key: AttrKey[T], default: D) -> T | D: ...
+
+    def get_or_default(self, key: AttrKey[T], default: T | D) -> T | D:
+        """Retrieve an attribute, returning default if not set."""
+        if key in self._data:
+            return cast(T, self._data[key])
+        return default
+
+    def has(self, key: AttrKey[Any]) -> bool:
+        """Check if an attribute is set."""
+        return key in self._data
+
+    def remove(self, key: AttrKey[Any]) -> bool:
+        """Remove an attribute. Returns True if it was present."""
+        if key in self._data:
+            del self._data[key]
+            return True
+        return False
+
+    def set_if_absent(self, key: AttrKey[T], value: T, *, validate: bool = True) -> T:
+        """
+        Set attribute only if not already set. Returns existing or newly set value.
+
+        Raises AttrMapTypeError if validate=True and type mismatches.
+        """
+        if key in self._data:
+            return cast(T, self._data[key])
+        if validate and not isinstance(value, key.type_):
+            raise AttrMapTypeError(key, key.type_, type(value))
+        self._data[key] = value
+        return value
+
+    def clear(self) -> None:
+        """Remove all attributes."""
+        self._data.clear()
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def __repr__(self) -> str:
+        keys = [k.name for k in self._data]
+        return f"AttrMap({keys})"

api/libs/external_api.py

@@ -17,7 +17,6 @@ def http_status_message(code):
 
 
 def register_external_error_handlers(api: Api):
-    @api.errorhandler(HTTPException)
     def handle_http_exception(e: HTTPException):
         got_request_exception.send(current_app, exception=e)
 
@@ -74,27 +73,18 @@ def register_external_error_handlers(api: Api):
                     headers["Set-Cookie"] = build_force_logout_cookie_headers()
             return data, status_code, headers
 
-    _ = handle_http_exception
-
-    @api.errorhandler(ValueError)
     def handle_value_error(e: ValueError):
         got_request_exception.send(current_app, exception=e)
         status_code = 400
         data = {"code": "invalid_param", "message": str(e), "status": status_code}
         return data, status_code
 
-    _ = handle_value_error
-
-    @api.errorhandler(AppInvokeQuotaExceededError)
     def handle_quota_exceeded(e: AppInvokeQuotaExceededError):
         got_request_exception.send(current_app, exception=e)
         status_code = 429
         data = {"code": "too_many_requests", "message": str(e), "status": status_code}
         return data, status_code
 
-    _ = handle_quota_exceeded
-
-    @api.errorhandler(Exception)
     def handle_general_exception(e: Exception):
         got_request_exception.send(current_app, exception=e)
 
@@ -113,7 +103,10 @@ def register_external_error_handlers(api: Api):
 
         return data, status_code
 
-    _ = handle_general_exception
+    api.errorhandler(HTTPException)(handle_http_exception)
+    api.errorhandler(ValueError)(handle_value_error)
+    api.errorhandler(AppInvokeQuotaExceededError)(handle_quota_exceeded)
+    api.errorhandler(Exception)(handle_general_exception)
 
 
 class ExternalApi(Api):

api/migrations/versions/2026_02_09_1726-227822d22895_add_workflow_comments_table.py

@@ -0,0 +1,109 @@
+"""Add workflow comments table
+
+Revision ID: 227822d22895
+Revises: 6b5f9f8b1a2c
+Create Date: 2026-02-09 17:26:15.255980
+
+"""
+
+from alembic import op
+import models as models
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = "227822d22895"
+down_revision = "6b5f9f8b1a2c"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "workflow_comments",
+        sa.Column("id", models.types.StringUUID(), server_default=sa.text("uuidv7()"), nullable=False),
+        sa.Column("tenant_id", models.types.StringUUID(), nullable=False),
+        sa.Column("app_id", models.types.StringUUID(), nullable=False),
+        sa.Column("position_x", sa.Float(), nullable=False),
+        sa.Column("position_y", sa.Float(), nullable=False),
+        sa.Column("content", sa.Text(), nullable=False),
+        sa.Column("created_by", models.types.StringUUID(), nullable=False),
+        sa.Column("created_at", sa.DateTime(), server_default=sa.text("CURRENT_TIMESTAMP"), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), server_default=sa.text("CURRENT_TIMESTAMP"), nullable=False),
+        sa.Column("resolved", sa.Boolean(), server_default=sa.text("false"), nullable=False),
+        sa.Column("resolved_at", sa.DateTime(), nullable=True),
+        sa.Column("resolved_by", models.types.StringUUID(), nullable=True),
+        sa.PrimaryKeyConstraint("id", name="workflow_comments_pkey"),
+    )
+    with op.batch_alter_table("workflow_comments", schema=None) as batch_op:
+        batch_op.create_index("workflow_comments_app_idx", ["tenant_id", "app_id"], unique=False)
+        batch_op.create_index("workflow_comments_created_at_idx", ["created_at"], unique=False)
+
+    op.create_table(
+        "workflow_comment_replies",
+        sa.Column("id", models.types.StringUUID(), server_default=sa.text("uuidv7()"), nullable=False),
+        sa.Column("comment_id", models.types.StringUUID(), nullable=False),
+        sa.Column("content", sa.Text(), nullable=False),
+        sa.Column("created_by", models.types.StringUUID(), nullable=False),
+        sa.Column("created_at", sa.DateTime(), server_default=sa.text("CURRENT_TIMESTAMP"), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), server_default=sa.text("CURRENT_TIMESTAMP"), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["comment_id"],
+            ["workflow_comments.id"],
+            name=op.f("workflow_comment_replies_comment_id_fkey"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id", name="workflow_comment_replies_pkey"),
+    )
+    with op.batch_alter_table("workflow_comment_replies", schema=None) as batch_op:
+        batch_op.create_index("comment_replies_comment_idx", ["comment_id"], unique=False)
+        batch_op.create_index("comment_replies_created_at_idx", ["created_at"], unique=False)
+
+    op.create_table(
+        "workflow_comment_mentions",
+        sa.Column("id", models.types.StringUUID(), server_default=sa.text("uuidv7()"), nullable=False),
+        sa.Column("comment_id", models.types.StringUUID(), nullable=False),
+        sa.Column("reply_id", models.types.StringUUID(), nullable=True),
+        sa.Column("mentioned_user_id", models.types.StringUUID(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["comment_id"],
+            ["workflow_comments.id"],
+            name=op.f("workflow_comment_mentions_comment_id_fkey"),
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["reply_id"],
+            ["workflow_comment_replies.id"],
+            name=op.f("workflow_comment_mentions_reply_id_fkey"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id", name="workflow_comment_mentions_pkey"),
+    )
+    with op.batch_alter_table("workflow_comment_mentions", schema=None) as batch_op:
+        batch_op.create_index("comment_mentions_comment_idx", ["comment_id"], unique=False)
+        batch_op.create_index("comment_mentions_reply_idx", ["reply_id"], unique=False)
+        batch_op.create_index("comment_mentions_user_idx", ["mentioned_user_id"], unique=False)
+
+    # ### end Alembic commands ###
+
+
+def downgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table("workflow_comment_mentions", schema=None) as batch_op:
+        batch_op.drop_index("comment_mentions_user_idx")
+        batch_op.drop_index("comment_mentions_reply_idx")
+        batch_op.drop_index("comment_mentions_comment_idx")
+
+    op.drop_table("workflow_comment_mentions")
+    with op.batch_alter_table("workflow_comment_replies", schema=None) as batch_op:
+        batch_op.drop_index("comment_replies_created_at_idx")
+        batch_op.drop_index("comment_replies_comment_idx")
+
+    op.drop_table("workflow_comment_replies")
+    with op.batch_alter_table("workflow_comments", schema=None) as batch_op:
+        batch_op.drop_index("workflow_comments_created_at_idx")
+        batch_op.drop_index("workflow_comments_app_idx")
+
+    op.drop_table("workflow_comments")
+    # ### end Alembic commands ###

api/models/__init__.py

@@ -98,6 +98,7 @@ from .trigger import (
     TriggerSubscription,
     WorkflowSchedulePlan,
 )
+from .comment import WorkflowComment, WorkflowCommentMention, WorkflowCommentReply
 from .web import PinnedConversation, SavedMessage
 from .workflow import (
     ConversationVariable,
@@ -205,6 +206,9 @@ __all__ = [
     "UploadFile",
     "Whitelist",
     "Workflow",
+    "WorkflowComment",
+    "WorkflowCommentMention",
+    "WorkflowCommentReply",
     "WorkflowAppLog",
     "WorkflowAppLogCreatedFrom",
     "WorkflowArchiveLog",

api/models/comment.py

@@ -0,0 +1,210 @@
+"""Workflow comment models."""
+
+from datetime import datetime
+from typing import Optional
+
+from sqlalchemy import Index, func
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from .account import Account
+from .base import Base
+from .engine import db
+from .types import StringUUID
+
+
+class WorkflowComment(Base):
+    """Workflow comment model for canvas commenting functionality.
+
+    Comments are associated with apps rather than specific workflow versions,
+    since an app has only one draft workflow at a time and comments should persist
+    across workflow version changes.
+
+    Attributes:
+        id: Comment ID
+        tenant_id: Workspace ID
+        app_id: App ID (primary association, comments belong to apps)
+        position_x: X coordinate on canvas
+        position_y: Y coordinate on canvas
+        content: Comment content
+        created_by: Creator account ID
+        created_at: Creation time
+        updated_at: Last update time
+        resolved: Whether comment is resolved
+        resolved_at: Resolution time
+        resolved_by: Resolver account ID
+    """
+
+    __tablename__ = "workflow_comments"
+    __table_args__ = (
+        db.PrimaryKeyConstraint("id", name="workflow_comments_pkey"),
+        Index("workflow_comments_app_idx", "tenant_id", "app_id"),
+        Index("workflow_comments_created_at_idx", "created_at"),
+    )
+
+    id: Mapped[str] = mapped_column(StringUUID, server_default=db.text("uuidv7()"))
+    tenant_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
+    app_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
+    position_x: Mapped[float] = mapped_column(db.Float)
+    position_y: Mapped[float] = mapped_column(db.Float)
+    content: Mapped[str] = mapped_column(db.Text, nullable=False)
+    created_by: Mapped[str] = mapped_column(StringUUID, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(db.DateTime, nullable=False, server_default=func.current_timestamp())
+    updated_at: Mapped[datetime] = mapped_column(
+        db.DateTime, nullable=False, server_default=func.current_timestamp(), onupdate=func.current_timestamp()
+    )
+    resolved: Mapped[bool] = mapped_column(db.Boolean, nullable=False, server_default=db.text("false"))
+    resolved_at: Mapped[datetime | None] = mapped_column(db.DateTime)
+    resolved_by: Mapped[str | None] = mapped_column(StringUUID)
+
+    # Relationships
+    replies: Mapped[list["WorkflowCommentReply"]] = relationship(
+        "WorkflowCommentReply", back_populates="comment", cascade="all, delete-orphan"
+    )
+    mentions: Mapped[list["WorkflowCommentMention"]] = relationship(
+        "WorkflowCommentMention", back_populates="comment", cascade="all, delete-orphan"
+    )
+
+    @property
+    def created_by_account(self):
+        """Get creator account."""
+        if hasattr(self, "_created_by_account_cache"):
+            return self._created_by_account_cache
+        return db.session.get(Account, self.created_by)
+
+    def cache_created_by_account(self, account: Account | None) -> None:
+        """Cache creator account to avoid extra queries."""
+        self._created_by_account_cache = account
+
+    @property
+    def resolved_by_account(self):
+        """Get resolver account."""
+        if hasattr(self, "_resolved_by_account_cache"):
+            return self._resolved_by_account_cache
+        if self.resolved_by:
+            return db.session.get(Account, self.resolved_by)
+        return None
+
+    def cache_resolved_by_account(self, account: Account | None) -> None:
+        """Cache resolver account to avoid extra queries."""
+        self._resolved_by_account_cache = account
+
+    @property
+    def reply_count(self):
+        """Get reply count."""
+        return len(self.replies)
+
+    @property
+    def mention_count(self):
+        """Get mention count."""
+        return len(self.mentions)
+
+    @property
+    def participants(self):
+        """Get all participants (creator + repliers + mentioned users)."""
+        participant_ids = set()
+
+        # Add comment creator
+        participant_ids.add(self.created_by)
+
+        # Add reply creators
+        participant_ids.update(reply.created_by for reply in self.replies)
+
+        # Add mentioned users
+        participant_ids.update(mention.mentioned_user_id for mention in self.mentions)
+
+        # Get account objects
+        participants = []
+        for user_id in participant_ids:
+            account = db.session.get(Account, user_id)
+            if account:
+                participants.append(account)
+
+        return participants
+
+
+class WorkflowCommentReply(Base):
+    """Workflow comment reply model.
+
+    Attributes:
+        id: Reply ID
+        comment_id: Parent comment ID
+        content: Reply content
+        created_by: Creator account ID
+        created_at: Creation time
+    """
+
+    __tablename__ = "workflow_comment_replies"
+    __table_args__ = (
+        db.PrimaryKeyConstraint("id", name="workflow_comment_replies_pkey"),
+        Index("comment_replies_comment_idx", "comment_id"),
+        Index("comment_replies_created_at_idx", "created_at"),
+    )
+
+    id: Mapped[str] = mapped_column(StringUUID, server_default=db.text("uuidv7()"))
+    comment_id: Mapped[str] = mapped_column(
+        StringUUID, db.ForeignKey("workflow_comments.id", ondelete="CASCADE"), nullable=False
+    )
+    content: Mapped[str] = mapped_column(db.Text, nullable=False)
+    created_by: Mapped[str] = mapped_column(StringUUID, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(db.DateTime, nullable=False, server_default=func.current_timestamp())
+    updated_at: Mapped[datetime] = mapped_column(
+        db.DateTime, nullable=False, server_default=func.current_timestamp(), onupdate=func.current_timestamp()
+    )
+    # Relationships
+    comment: Mapped["WorkflowComment"] = relationship("WorkflowComment", back_populates="replies")
+
+    @property
+    def created_by_account(self):
+        """Get creator account."""
+        if hasattr(self, "_created_by_account_cache"):
+            return self._created_by_account_cache
+        return db.session.get(Account, self.created_by)
+
+    def cache_created_by_account(self, account: Account | None) -> None:
+        """Cache creator account to avoid extra queries."""
+        self._created_by_account_cache = account
+
+
+class WorkflowCommentMention(Base):
+    """Workflow comment mention model.
+
+    Mentions are only for internal accounts since end users
+    cannot access workflow canvas and commenting features.
+
+    Attributes:
+        id: Mention ID
+        comment_id: Parent comment ID
+        mentioned_user_id: Mentioned account ID
+    """
+
+    __tablename__ = "workflow_comment_mentions"
+    __table_args__ = (
+        db.PrimaryKeyConstraint("id", name="workflow_comment_mentions_pkey"),
+        Index("comment_mentions_comment_idx", "comment_id"),
+        Index("comment_mentions_reply_idx", "reply_id"),
+        Index("comment_mentions_user_idx", "mentioned_user_id"),
+    )
+
+    id: Mapped[str] = mapped_column(StringUUID, server_default=db.text("uuidv7()"))
+    comment_id: Mapped[str] = mapped_column(
+        StringUUID, db.ForeignKey("workflow_comments.id", ondelete="CASCADE"), nullable=False
+    )
+    reply_id: Mapped[str | None] = mapped_column(
+        StringUUID, db.ForeignKey("workflow_comment_replies.id", ondelete="CASCADE"), nullable=True
+    )
+    mentioned_user_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
+
+    # Relationships
+    comment: Mapped["WorkflowComment"] = relationship("WorkflowComment", back_populates="mentions")
+    reply: Mapped[Optional["WorkflowCommentReply"]] = relationship("WorkflowCommentReply")
+
+    @property
+    def mentioned_user_account(self):
+        """Get mentioned account."""
+        if hasattr(self, "_mentioned_user_account_cache"):
+            return self._mentioned_user_account_cache
+        return db.session.get(Account, self.mentioned_user_id)
+
+    def cache_mentioned_user_account(self, account: Account | None) -> None:
+        """Cache mentioned account to avoid extra queries."""
+        self._mentioned_user_account_cache = account

api/models/dataset.py

@@ -1688,7 +1688,7 @@ class PipelineRecommendedPlugin(TypeBase):
     )
 
 
-class SegmentAttachmentBinding(Base):
+class SegmentAttachmentBinding(TypeBase):
     __tablename__ = "segment_attachment_bindings"
     __table_args__ = (
         sa.PrimaryKeyConstraint("id", name="segment_attachment_binding_pkey"),
@@ -1701,13 +1701,17 @@ class SegmentAttachmentBinding(Base):
         ),
         sa.Index("segment_attachment_binding_attachment_idx", "attachment_id"),
     )
-    id: Mapped[str] = mapped_column(StringUUID, default=lambda: str(uuidv7()))
+    id: Mapped[str] = mapped_column(
+        StringUUID, insert_default=lambda: str(uuidv7()), default_factory=lambda: str(uuidv7()), init=False
+    )
     tenant_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
     dataset_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
     document_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
     segment_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
     attachment_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
-    created_at: Mapped[datetime] = mapped_column(sa.DateTime, nullable=False, server_default=func.current_timestamp())
+    created_at: Mapped[datetime] = mapped_column(
+        sa.DateTime, nullable=False, server_default=func.current_timestamp(), init=False
+    )
 
 
 class DocumentSegmentSummary(Base):

api/models/model.py

@@ -352,6 +352,7 @@ class AppMode(StrEnum):
     CHAT = "chat"
     ADVANCED_CHAT = "advanced-chat"
     AGENT_CHAT = "agent-chat"
+    AGENT = "agent"
     CHANNEL = "channel"
     RAG_PIPELINE = "rag-pipeline"
 
@@ -838,7 +839,7 @@ class AppModelConfig(TypeBase):
         return self
 
 
-class RecommendedApp(Base):  # bug
+class RecommendedApp(TypeBase):
     __tablename__ = "recommended_apps"
     __table_args__ = (
         sa.PrimaryKeyConstraint("id", name="recommended_app_pkey"),
@@ -846,20 +847,37 @@ class RecommendedApp(Base):  # bug
         sa.Index("recommended_app_is_listed_idx", "is_listed", "language"),
     )
 
-    id = mapped_column(StringUUID, primary_key=True, default=lambda: str(uuid4()))
-    app_id = mapped_column(StringUUID, nullable=False)
-    description = mapped_column(sa.JSON, nullable=False)
+    id: Mapped[str] = mapped_column(
+        StringUUID,
+        primary_key=True,
+        insert_default=lambda: str(uuid4()),
+        default_factory=lambda: str(uuid4()),
+        init=False,
+    )
+    app_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
+    description: Mapped[Any] = mapped_column(sa.JSON, nullable=False)
     copyright: Mapped[str] = mapped_column(String(255), nullable=False)
     privacy_policy: Mapped[str] = mapped_column(String(255), nullable=False)
-    custom_disclaimer: Mapped[str] = mapped_column(LongText, default="")
     category: Mapped[str] = mapped_column(String(255), nullable=False)
+    custom_disclaimer: Mapped[str] = mapped_column(LongText, default="")
     position: Mapped[int] = mapped_column(sa.Integer, nullable=False, default=0)
     is_listed: Mapped[bool] = mapped_column(sa.Boolean, nullable=False, default=True)
     install_count: Mapped[int] = mapped_column(sa.Integer, nullable=False, default=0)
-    language = mapped_column(String(255), nullable=False, server_default=sa.text("'en-US'"))
-    created_at = mapped_column(sa.DateTime, nullable=False, server_default=func.current_timestamp())
-    updated_at = mapped_column(
-        sa.DateTime, nullable=False, server_default=func.current_timestamp(), onupdate=func.current_timestamp()
+    language: Mapped[str] = mapped_column(
+        String(255),
+        nullable=False,
+        server_default=sa.text("'en-US'"),
+        default="en-US",
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        sa.DateTime, nullable=False, server_default=func.current_timestamp(), init=False
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        sa.DateTime,
+        nullable=False,
+        server_default=func.current_timestamp(),
+        onupdate=func.current_timestamp(),
+        init=False,
     )
 
     @property

api/models/workflow.py

@@ -61,7 +61,7 @@ from factories import variable_factory
 from libs import helper
 
 from .account import Account
-from .base import Base, DefaultFieldsMixin, TypeBase
+from .base import Base, DefaultFieldsDCMixin, TypeBase
 from .engine import db
 from .enums import CreatorUserRole, DraftVariableType, ExecutionOffLoadType, WorkflowRunTriggeredFrom
 from .types import EnumText, LongText, StringUUID
@@ -742,8 +742,8 @@ class WorkflowRun(Base):
     exceptions_count: Mapped[int] = mapped_column(sa.Integer, server_default=sa.text("0"), nullable=True)
 
     pause: Mapped[Optional["WorkflowPause"]] = orm.relationship(
-        "WorkflowPause",
-        primaryjoin="WorkflowRun.id == foreign(WorkflowPause.workflow_run_id)",
+        lambda: WorkflowPause,
+        primaryjoin=lambda: WorkflowRun.id == orm.foreign(WorkflowPause.workflow_run_id),
         uselist=False,
         # require explicit preloading.
         lazy="raise",
@@ -1196,6 +1196,18 @@ class WorkflowAppLogCreatedFrom(StrEnum):
         raise ValueError(f"invalid workflow app log created from value {value}")
 
 
+class WorkflowAppLogDict(TypedDict):
+    id: str
+    tenant_id: str
+    app_id: str
+    workflow_id: str
+    workflow_run_id: str
+    created_from: WorkflowAppLogCreatedFrom
+    created_by_role: CreatorUserRole
+    created_by: str
+    created_at: datetime
+
+
 class WorkflowAppLog(TypeBase):
     """
     Workflow App execution log, excluding workflow debugging records.
@@ -1273,8 +1285,8 @@ class WorkflowAppLog(TypeBase):
         created_by_role = CreatorUserRole(self.created_by_role)
         return db.session.get(EndUser, self.created_by) if created_by_role == CreatorUserRole.END_USER else None
 
-    def to_dict(self):
-        return {
+    def to_dict(self) -> WorkflowAppLogDict:
+        result: WorkflowAppLogDict = {
             "id": self.id,
             "tenant_id": self.tenant_id,
             "app_id": self.app_id,
@@ -1285,6 +1297,7 @@ class WorkflowAppLog(TypeBase):
             "created_by": self.created_by,
             "created_at": self.created_at,
         }
+        return result
 
 
 class WorkflowArchiveLog(TypeBase):
@@ -1941,7 +1954,7 @@ def is_system_variable_editable(name: str) -> bool:
     return name in _EDITABLE_SYSTEM_VARIABLE
 
 
-class WorkflowPause(DefaultFieldsMixin, Base):
+class WorkflowPause(DefaultFieldsDCMixin, TypeBase):
     """
     WorkflowPause records the paused state and related metadata for a specific workflow run.
 
@@ -1980,6 +1993,11 @@ class WorkflowPause(DefaultFieldsMixin, Base):
         nullable=False,
     )
 
+    # state_object_key stores the object key referencing the serialized runtime state
+    # of the `GraphEngine`. This object captures the complete execution context of the
+    # workflow at the moment it was paused, enabling accurate resumption.
+    state_object_key: Mapped[str] = mapped_column(String(length=255), nullable=False)
+
     # `resumed_at` records the timestamp when the suspended workflow was resumed.
     # It is set to `NULL` if the workflow has not been resumed.
     #
@@ -1988,25 +2006,23 @@ class WorkflowPause(DefaultFieldsMixin, Base):
     resumed_at: Mapped[datetime | None] = mapped_column(
         sa.DateTime,
         nullable=True,
+        default=None,
     )
 
-    # state_object_key stores the object key referencing the serialized runtime state
-    # of the `GraphEngine`. This object captures the complete execution context of the
-    # workflow at the moment it was paused, enabling accurate resumption.
-    state_object_key: Mapped[str] = mapped_column(String(length=255), nullable=False)
-
-    # Relationship to WorkflowRun
+    # Relationship to WorkflowRun (uses lambda to resolve across Base/TypeBase registries)
     workflow_run: Mapped["WorkflowRun"] = orm.relationship(
+        lambda: WorkflowRun,
         foreign_keys=[workflow_run_id],
         # require explicit preloading.
         lazy="raise",
         uselist=False,
-        primaryjoin="WorkflowPause.workflow_run_id == WorkflowRun.id",
+        primaryjoin=lambda: WorkflowPause.workflow_run_id == WorkflowRun.id,
         back_populates="pause",
+        init=False,
     )
 
 
-class WorkflowPauseReason(DefaultFieldsMixin, Base):
+class WorkflowPauseReason(DefaultFieldsDCMixin, TypeBase):
     __tablename__ = "workflow_pause_reasons"
 
     # `pause_id` represents the identifier of the pause,
@@ -2049,16 +2065,20 @@ class WorkflowPauseReason(DefaultFieldsMixin, Base):
         lazy="raise",
         uselist=False,
         primaryjoin="WorkflowPauseReason.pause_id == WorkflowPause.id",
+        init=False,
     )
 
     @classmethod
-    def from_entity(cls, pause_reason: PauseReason) -> "WorkflowPauseReason":
+    def from_entity(cls, *, pause_id: str, pause_reason: PauseReason) -> "WorkflowPauseReason":
         if isinstance(pause_reason, HumanInputRequired):
             return cls(
-                type_=PauseReasonType.HUMAN_INPUT_REQUIRED, form_id=pause_reason.form_id, node_id=pause_reason.node_id
+                pause_id=pause_id,
+                type_=PauseReasonType.HUMAN_INPUT_REQUIRED,
+                form_id=pause_reason.form_id,
+                node_id=pause_reason.node_id,
             )
         elif isinstance(pause_reason, SchedulingPause):
-            return cls(type_=PauseReasonType.SCHEDULED_PAUSE, message=pause_reason.message, node_id="")
+            return cls(pause_id=pause_id, type_=PauseReasonType.SCHEDULED_PAUSE, message=pause_reason.message)
         else:
             raise AssertionError(f"Unknown pause reason type: {pause_reason}")
 

api/models/workflow_features.py

@@ -0,0 +1,26 @@
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+
+class WorkflowFeatures(StrEnum):
+    SANDBOX = "sandbox"
+    SPEECH_TO_TEXT = "speech_to_text"
+    TEXT_TO_SPEECH = "text_to_speech"
+    RETRIEVER_RESOURCE = "retriever_resource"
+    SENSITIVE_WORD_AVOIDANCE = "sensitive_word_avoidance"
+    FILE_UPLOAD = "file_upload"
+    SUGGESTED_QUESTIONS_AFTER_ANSWER = "suggested_questions_after_answer"
+
+
+@dataclass(frozen=True)
+class WorkflowFeature:
+    enabled: bool
+    config: Mapping[str, Any]
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any] | None) -> "WorkflowFeature":
+        if data is None or not isinstance(data, dict):
+            return cls(enabled=False, config={})
+        return cls(enabled=bool(data.get("enabled", False)), config=data)

api/pyproject.toml

@@ -41,23 +41,23 @@ dependencies = [
     "openpyxl~=3.1.5",
     "opik~=1.11.2",
     "litellm==1.83.0",                                    # Pinned to avoid madoka dependency issue
-    "opentelemetry-api==1.40.0",
-    "opentelemetry-distro==0.61b0",
-    "opentelemetry-exporter-otlp==1.40.0",
-    "opentelemetry-exporter-otlp-proto-common==1.40.0",
-    "opentelemetry-exporter-otlp-proto-grpc==1.40.0",
-    "opentelemetry-exporter-otlp-proto-http==1.40.0",
-    "opentelemetry-instrumentation==0.61b0",
-    "opentelemetry-instrumentation-celery==0.61b0",
-    "opentelemetry-instrumentation-flask==0.61b0",
-    "opentelemetry-instrumentation-httpx==0.61b0",
-    "opentelemetry-instrumentation-redis==0.61b0",
-    "opentelemetry-instrumentation-sqlalchemy==0.61b0",
+    "opentelemetry-api==1.41.0",
+    "opentelemetry-distro==0.62b0",
+    "opentelemetry-exporter-otlp==1.41.0",
+    "opentelemetry-exporter-otlp-proto-common==1.41.0",
+    "opentelemetry-exporter-otlp-proto-grpc==1.41.0",
+    "opentelemetry-exporter-otlp-proto-http==1.41.0",
+    "opentelemetry-instrumentation==0.62b0",
+    "opentelemetry-instrumentation-celery==0.62b0",
+    "opentelemetry-instrumentation-flask==0.62b0",
+    "opentelemetry-instrumentation-httpx==0.62b0",
+    "opentelemetry-instrumentation-redis==0.62b0",
+    "opentelemetry-instrumentation-sqlalchemy==0.62b0",
     "opentelemetry-propagator-b3==1.41.0",
-    "opentelemetry-proto==1.40.0",
-    "opentelemetry-sdk==1.40.0",
-    "opentelemetry-semantic-conventions==0.61b0",
-    "opentelemetry-util-http==0.61b0",
+    "opentelemetry-proto==1.41.0",
+    "opentelemetry-sdk==1.41.0",
+    "opentelemetry-semantic-conventions==0.62b0",
+    "opentelemetry-util-http==0.62b0",
     "pandas[excel,output-formatting,performance]~=3.0.2",
     "psycogreen~=1.0.2",
     "psycopg2-binary~=2.9.11",
@@ -88,7 +88,7 @@ dependencies = [
     "croniter>=6.2.2",
     "weaviate-client==4.20.5",
     "apscheduler>=3.11.2",
-    "weave>=0.52.16",
+    "weave>=0.52.36",
     "fastopenapi[flask]>=0.7.0",
     "bleach~=6.3.0",
 ]
@@ -166,7 +166,7 @@ dev = [
     "import-linter>=2.3",
     "types-redis>=4.6.0.20241004",
     "celery-types>=0.23.0",
-    "mypy~=1.20.0",
+    "mypy~=1.20.1",
     # "locust>=2.40.4",  # Temporarily removed due to compatibility issues. Uncomment when resolved.
     "sseclient-py>=1.8.0",
     "pytest-timeout>=2.4.0",

api/pyrightconfig.json

@@ -47,7 +47,6 @@
   "reportMissingTypeArgument": "hint",
   "reportUnnecessaryComparison": "hint",
   "reportUnnecessaryIsInstance": "hint",
-  "reportUntypedFunctionDecorator": "hint",
   "reportUnnecessaryTypeIgnoreComment": "hint",
   "reportAttributeAccessIssue": "hint",
   "pythonVersion": "3.12",

api/repositories/sqlalchemy_api_workflow_run_repository.py

@@ -41,7 +41,6 @@ from libs.datetime_utils import naive_utc_now
 from libs.helper import convert_datetime_to_date
 from libs.infinite_scroll_pagination import InfiniteScrollPagination
 from libs.time_parser import get_time_threshold
-from libs.uuid_utils import uuidv7
 from models.enums import WorkflowRunTriggeredFrom
 from models.human_input import HumanInputForm
 from models.workflow import WorkflowAppLog, WorkflowArchiveLog, WorkflowPause, WorkflowPauseReason, WorkflowRun
@@ -744,12 +743,11 @@ class DifyAPISQLAlchemyWorkflowRunRepository(APIWorkflowRunRepository):
             # Upload the state file
 
             # Create the pause record
-            pause_model = WorkflowPause()
-            pause_model.id = str(uuidv7())
-            pause_model.workflow_id = workflow_run.workflow_id
-            pause_model.workflow_run_id = workflow_run.id
-            pause_model.state_object_key = state_obj_key
-            pause_model.created_at = naive_utc_now()
+            pause_model = WorkflowPause(
+                workflow_id=workflow_run.workflow_id,
+                workflow_run_id=workflow_run.id,
+                state_object_key=state_obj_key,
+            )
             pause_reason_models = []
             for reason in pause_reasons:
                 if isinstance(reason, HumanInputRequired):

api/repositories/workflow_collaboration_repository.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+import json
+from typing import TypedDict
+
+from extensions.ext_redis import redis_client
+
+SESSION_STATE_TTL_SECONDS = 3600
+WORKFLOW_ONLINE_USERS_PREFIX = "workflow_online_users:"
+WORKFLOW_LEADER_PREFIX = "workflow_leader:"
+WORKFLOW_SKILL_LEADER_PREFIX = "workflow_skill_leader:"
+WS_SID_MAP_PREFIX = "ws_sid_map:"
+
+
+class WorkflowSessionInfo(TypedDict):
+    user_id: str
+    username: str
+    avatar: str | None
+    sid: str
+    connected_at: int
+    graph_active: bool
+    active_skill_file_id: str | None
+
+
+class SidMapping(TypedDict):
+    workflow_id: str
+    user_id: str
+
+
+class WorkflowCollaborationRepository:
+    def __init__(self) -> None:
+        self._redis = redis_client
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(redis_client={self._redis})"
+
+    @staticmethod
+    def workflow_key(workflow_id: str) -> str:
+        return f"{WORKFLOW_ONLINE_USERS_PREFIX}{workflow_id}"
+
+    @staticmethod
+    def leader_key(workflow_id: str) -> str:
+        return f"{WORKFLOW_LEADER_PREFIX}{workflow_id}"
+
+    @staticmethod
+    def skill_leader_key(workflow_id: str, file_id: str) -> str:
+        return f"{WORKFLOW_SKILL_LEADER_PREFIX}{workflow_id}:{file_id}"
+
+    @staticmethod
+    def sid_key(sid: str) -> str:
+        return f"{WS_SID_MAP_PREFIX}{sid}"
+
+    @staticmethod
+    def _decode(value: str | bytes | None) -> str | None:
+        if value is None:
+            return None
+        if isinstance(value, bytes):
+            return value.decode("utf-8")
+        return value
+
+    def refresh_session_state(self, workflow_id: str, sid: str) -> None:
+        workflow_key = self.workflow_key(workflow_id)
+        sid_key = self.sid_key(sid)
+        if self._redis.exists(workflow_key):
+            self._redis.expire(workflow_key, SESSION_STATE_TTL_SECONDS)
+        if self._redis.exists(sid_key):
+            self._redis.expire(sid_key, SESSION_STATE_TTL_SECONDS)
+
+    def set_session_info(self, workflow_id: str, session_info: WorkflowSessionInfo) -> None:
+        workflow_key = self.workflow_key(workflow_id)
+        self._redis.hset(workflow_key, session_info["sid"], json.dumps(session_info))
+        self._redis.set(
+            self.sid_key(session_info["sid"]),
+            json.dumps({"workflow_id": workflow_id, "user_id": session_info["user_id"]}),
+            ex=SESSION_STATE_TTL_SECONDS,
+        )
+        self.refresh_session_state(workflow_id, session_info["sid"])
+
+    def get_session_info(self, workflow_id: str, sid: str) -> WorkflowSessionInfo | None:
+        raw = self._redis.hget(self.workflow_key(workflow_id), sid)
+        value = self._decode(raw)
+        if not value:
+            return None
+        try:
+            session_info = json.loads(value)
+        except (TypeError, json.JSONDecodeError):
+            return None
+
+        if not isinstance(session_info, dict):
+            return None
+        if "user_id" not in session_info or "username" not in session_info or "sid" not in session_info:
+            return None
+
+        return {
+            "user_id": str(session_info["user_id"]),
+            "username": str(session_info["username"]),
+            "avatar": session_info.get("avatar"),
+            "sid": str(session_info["sid"]),
+            "connected_at": int(session_info.get("connected_at") or 0),
+            "graph_active": bool(session_info.get("graph_active")),
+            "active_skill_file_id": session_info.get("active_skill_file_id"),
+        }
+
+    def set_graph_active(self, workflow_id: str, sid: str, active: bool) -> None:
+        session_info = self.get_session_info(workflow_id, sid)
+        if not session_info:
+            return
+        session_info["graph_active"] = bool(active)
+        self._redis.hset(self.workflow_key(workflow_id), sid, json.dumps(session_info))
+        self.refresh_session_state(workflow_id, sid)
+
+    def is_graph_active(self, workflow_id: str, sid: str) -> bool:
+        session_info = self.get_session_info(workflow_id, sid)
+        if not session_info:
+            return False
+        return bool(session_info.get("graph_active") or False)
+
+    def set_active_skill_file(self, workflow_id: str, sid: str, file_id: str | None) -> None:
+        session_info = self.get_session_info(workflow_id, sid)
+        if not session_info:
+            return
+        session_info["active_skill_file_id"] = file_id
+        self._redis.hset(self.workflow_key(workflow_id), sid, json.dumps(session_info))
+        self.refresh_session_state(workflow_id, sid)
+
+    def get_active_skill_file_id(self, workflow_id: str, sid: str) -> str | None:
+        session_info = self.get_session_info(workflow_id, sid)
+        if not session_info:
+            return None
+        return session_info.get("active_skill_file_id")
+
+    def get_sid_mapping(self, sid: str) -> SidMapping | None:
+        raw = self._redis.get(self.sid_key(sid))
+        if not raw:
+            return None
+        value = self._decode(raw)
+        if not value:
+            return None
+        try:
+            return json.loads(value)
+        except (TypeError, json.JSONDecodeError):
+            return None
+
+    def delete_session(self, workflow_id: str, sid: str) -> None:
+        self._redis.hdel(self.workflow_key(workflow_id), sid)
+        self._redis.delete(self.sid_key(sid))
+
+    def session_exists(self, workflow_id: str, sid: str) -> bool:
+        return bool(self._redis.hexists(self.workflow_key(workflow_id), sid))
+
+    def sid_mapping_exists(self, sid: str) -> bool:
+        return bool(self._redis.exists(self.sid_key(sid)))
+
+    def get_session_sids(self, workflow_id: str) -> list[str]:
+        raw_sids = self._redis.hkeys(self.workflow_key(workflow_id))
+        decoded_sids: list[str] = []
+        for sid in raw_sids:
+            decoded = self._decode(sid)
+            if decoded:
+                decoded_sids.append(decoded)
+        return decoded_sids
+
+    def list_sessions(self, workflow_id: str) -> list[WorkflowSessionInfo]:
+        sessions_json = self._redis.hgetall(self.workflow_key(workflow_id))
+        users: list[WorkflowSessionInfo] = []
+
+        for session_info_json in sessions_json.values():
+            value = self._decode(session_info_json)
+            if not value:
+                continue
+            try:
+                session_info = json.loads(value)
+            except (TypeError, json.JSONDecodeError):
+                continue
+
+            if not isinstance(session_info, dict):
+                continue
+            if "user_id" not in session_info or "username" not in session_info or "sid" not in session_info:
+                continue
+
+            users.append(
+                {
+                    "user_id": str(session_info["user_id"]),
+                    "username": str(session_info["username"]),
+                    "avatar": session_info.get("avatar"),
+                    "sid": str(session_info["sid"]),
+                    "connected_at": int(session_info.get("connected_at") or 0),
+                    "graph_active": bool(session_info.get("graph_active")),
+                    "active_skill_file_id": session_info.get("active_skill_file_id"),
+                }
+            )
+
+        return users
+
+    def get_current_leader(self, workflow_id: str) -> str | None:
+        raw = self._redis.get(self.leader_key(workflow_id))
+        return self._decode(raw)
+
+    def get_skill_leader(self, workflow_id: str, file_id: str) -> str | None:
+        raw = self._redis.get(self.skill_leader_key(workflow_id, file_id))
+        return self._decode(raw)
+
+    def set_leader_if_absent(self, workflow_id: str, sid: str) -> bool:
+        return bool(self._redis.set(self.leader_key(workflow_id), sid, nx=True, ex=SESSION_STATE_TTL_SECONDS))
+
+    def set_leader(self, workflow_id: str, sid: str) -> None:
+        self._redis.set(self.leader_key(workflow_id), sid, ex=SESSION_STATE_TTL_SECONDS)
+
+    def set_skill_leader(self, workflow_id: str, file_id: str, sid: str) -> None:
+        self._redis.set(self.skill_leader_key(workflow_id, file_id), sid, ex=SESSION_STATE_TTL_SECONDS)
+
+    def delete_leader(self, workflow_id: str) -> None:
+        self._redis.delete(self.leader_key(workflow_id))
+
+    def delete_skill_leader(self, workflow_id: str, file_id: str) -> None:
+        self._redis.delete(self.skill_leader_key(workflow_id, file_id))
+
+    def expire_leader(self, workflow_id: str) -> None:
+        self._redis.expire(self.leader_key(workflow_id), SESSION_STATE_TTL_SECONDS)
+
+    def expire_skill_leader(self, workflow_id: str, file_id: str) -> None:
+        self._redis.expire(self.skill_leader_key(workflow_id, file_id), SESSION_STATE_TTL_SECONDS)
+
+    def get_active_skill_session_sids(self, workflow_id: str, file_id: str) -> list[str]:
+        sessions = self.list_sessions(workflow_id)
+        return [session["sid"] for session in sessions if session.get("active_skill_file_id") == file_id]

api/services/annotation_service.py

@@ -1,11 +1,8 @@
 import logging
 import uuid
-
-import pandas as pd
-
-logger = logging.getLogger(__name__)
 from typing import TypedDict
 
+import pandas as pd
 from sqlalchemy import delete, or_, select, update
 from werkzeug.datastructures import FileStorage
 from werkzeug.exceptions import NotFound
@@ -24,6 +21,8 @@ from tasks.annotation.disable_annotation_reply_task import disable_annotation_re
 from tasks.annotation.enable_annotation_reply_task import enable_annotation_reply_task
 from tasks.annotation.update_annotation_to_index_task import update_annotation_to_index_task
 
+logger = logging.getLogger(__name__)
+
 
 class AnnotationJobStatusDict(TypedDict):
     job_id: str
@@ -46,9 +45,50 @@ class AnnotationSettingDisabledDict(TypedDict):
     enabled: bool
 
 
+class EnableAnnotationArgs(TypedDict):
+    """Expected shape of the args dict passed to enable_app_annotation."""
+
+    score_threshold: float
+    embedding_provider_name: str
+    embedding_model_name: str
+
+
+class UpsertAnnotationArgs(TypedDict, total=False):
+    """Expected shape of the args dict passed to up_insert_app_annotation_from_message."""
+
+    answer: str
+    content: str
+    message_id: str
+    question: str
+
+
+class InsertAnnotationArgs(TypedDict):
+    """Expected shape of the args dict passed to insert_app_annotation_directly."""
+
+    question: str
+    answer: str
+
+
+class UpdateAnnotationArgs(TypedDict, total=False):
+    """Expected shape of the args dict passed to update_app_annotation_directly.
+
+    Both fields are optional at the type level; the service validates at runtime
+    and raises ValueError if either is missing.
+    """
+
+    answer: str
+    question: str
+
+
+class UpdateAnnotationSettingArgs(TypedDict):
+    """Expected shape of the args dict passed to update_app_annotation_setting."""
+
+    score_threshold: float
+
+
 class AppAnnotationService:
     @classmethod
-    def up_insert_app_annotation_from_message(cls, args: dict, app_id: str) -> MessageAnnotation:
+    def up_insert_app_annotation_from_message(cls, args: UpsertAnnotationArgs, app_id: str) -> MessageAnnotation:
         # get app info
         current_user, current_tenant_id = current_account_with_tenant()
         app = db.session.scalar(
@@ -62,8 +102,9 @@ class AppAnnotationService:
         if answer is None:
             raise ValueError("Either 'answer' or 'content' must be provided")
 
-        if args.get("message_id"):
-            message_id = str(args["message_id"])
+        raw_message_id = args.get("message_id")
+        if raw_message_id:
+            message_id = str(raw_message_id)
             message = db.session.scalar(
                 select(Message).where(Message.id == message_id, Message.app_id == app.id).limit(1)
             )
@@ -87,9 +128,10 @@ class AppAnnotationService:
                     account_id=current_user.id,
                 )
         else:
-            question = args.get("question")
-            if not question:
+            maybe_question = args.get("question")
+            if not maybe_question:
                 raise ValueError("'question' is required when 'message_id' is not provided")
+            question = maybe_question
 
             annotation = MessageAnnotation(app_id=app.id, content=answer, question=question, account_id=current_user.id)
         db.session.add(annotation)
@@ -110,7 +152,7 @@ class AppAnnotationService:
         return annotation
 
     @classmethod
-    def enable_app_annotation(cls, args: dict, app_id: str) -> AnnotationJobStatusDict:
+    def enable_app_annotation(cls, args: EnableAnnotationArgs, app_id: str) -> AnnotationJobStatusDict:
         enable_app_annotation_key = f"enable_app_annotation_{str(app_id)}"
         cache_result = redis_client.get(enable_app_annotation_key)
         if cache_result is not None:
@@ -217,7 +259,7 @@ class AppAnnotationService:
         return annotations
 
     @classmethod
-    def insert_app_annotation_directly(cls, args: dict, app_id: str) -> MessageAnnotation:
+    def insert_app_annotation_directly(cls, args: InsertAnnotationArgs, app_id: str) -> MessageAnnotation:
         # get app info
         current_user, current_tenant_id = current_account_with_tenant()
         app = db.session.scalar(
@@ -251,7 +293,7 @@ class AppAnnotationService:
         return annotation
 
     @classmethod
-    def update_app_annotation_directly(cls, args: dict, app_id: str, annotation_id: str):
+    def update_app_annotation_directly(cls, args: UpdateAnnotationArgs, app_id: str, annotation_id: str):
         # get app info
         _, current_tenant_id = current_account_with_tenant()
         app = db.session.scalar(
@@ -270,7 +312,11 @@ class AppAnnotationService:
         if question is None:
             raise ValueError("'question' is required")
 
-        annotation.content = args["answer"]
+        answer = args.get("answer")
+        if answer is None:
+            raise ValueError("'answer' is required")
+
+        annotation.content = answer
         annotation.question = question
 
         db.session.commit()
@@ -613,7 +659,7 @@ class AppAnnotationService:
 
     @classmethod
     def update_app_annotation_setting(
-        cls, app_id: str, annotation_setting_id: str, args: dict
+        cls, app_id: str, annotation_setting_id: str, args: UpdateAnnotationSettingArgs
     ) -> AnnotationSettingDict:
         current_user, current_tenant_id = current_account_with_tenant()
         # get app info

api/services/app_dsl_service.py

@@ -455,7 +455,7 @@ class AppDslService:
             app.updated_by = account.id
 
             self._session.add(app)
-            self._session.commit()
+            self._session.flush()
             app_was_created.send(app, account=account)
 
         # save dependencies
@@ -468,7 +468,7 @@ class AppDslService:
 
         # Initialize app based on mode
         match app_mode:
-            case AppMode.ADVANCED_CHAT | AppMode.WORKFLOW:
+            case AppMode.ADVANCED_CHAT | AppMode.WORKFLOW | AppMode.AGENT:
                 workflow_data = data.get("workflow")
                 if not workflow_data or not isinstance(workflow_data, dict):
                     raise ValueError("Missing workflow data for workflow/advanced chat app")
@@ -556,7 +556,7 @@ class AppDslService:
             },
         }
 
-        if app_mode in {AppMode.ADVANCED_CHAT, AppMode.WORKFLOW}:
+        if app_mode in {AppMode.ADVANCED_CHAT, AppMode.WORKFLOW, AppMode.AGENT}:
             cls._append_workflow_export_data(
                 export_data=export_data, app_model=app_model, include_secret=include_secret, workflow_id=workflow_id
             )

api/services/app_generate_service.py

@@ -56,7 +56,6 @@ class AppGenerateService:
                 try:
                     start_task()
                 except Exception:
-                    logger.exception("Failed to enqueue streaming task")
                     return False
                 started = True
                 return True
@@ -117,8 +116,84 @@ class AppGenerateService:
         try:
             request_id = rate_limit.enter(request_id)
             effective_mode = (
-                AppMode.AGENT_CHAT if app_model.is_agent and app_model.mode != AppMode.AGENT_CHAT else app_model.mode
+                AppMode.AGENT_CHAT
+                if app_model.is_agent and app_model.mode not in {AppMode.AGENT_CHAT, AppMode.AGENT}
+                else app_model.mode
             )
+
+            if (
+                effective_mode in {AppMode.COMPLETION, AppMode.CHAT, AppMode.AGENT_CHAT}
+                and dify_config.AGENT_V2_TRANSPARENT_UPGRADE
+            ):
+                from services.workflow.virtual_workflow import VirtualWorkflowSynthesizer
+
+                try:
+                    workflow = VirtualWorkflowSynthesizer.ensure_workflow(app_model)
+                    logger.info(
+                        "[AGENT_V2_UPGRADE] Transparent upgrade for app %s (mode=%s), wf=%s",
+                        app_model.id,
+                        effective_mode,
+                        workflow.id,
+                    )
+
+                    upgraded_args = dict(args)
+                    if "query" not in upgraded_args or not upgraded_args.get("query"):
+                        inputs = upgraded_args.get("inputs", {})
+                        upgraded_args["query"] = inputs.get("query", "") or inputs.get("input", "") or str(inputs)
+                    args = upgraded_args
+
+                    if streaming:
+                        with rate_limit_context(rate_limit, request_id):
+                            payload = AppExecutionParams.new(
+                                app_model=app_model,
+                                workflow=workflow,
+                                user=user,
+                                args=args,
+                                invoke_from=invoke_from,
+                                streaming=True,
+                                call_depth=0,
+                            )
+                            payload_json = payload.model_dump_json()
+
+                        def on_subscribe():
+                            workflow_based_app_execution_task.delay(payload_json)
+
+                        on_subscribe = cls._build_streaming_task_on_subscribe(on_subscribe)
+                        generator = AdvancedChatAppGenerator()
+                        subscribe_mode = AppMode.value_of(app_model.mode)
+                        return rate_limit.generate(
+                            generator.convert_to_event_stream(
+                                generator.retrieve_events(
+                                    subscribe_mode,
+                                    payload.workflow_run_id,
+                                    on_subscribe=on_subscribe,
+                                ),
+                            ),
+                            request_id=request_id,
+                        )
+                    else:
+                        advanced_generator = AdvancedChatAppGenerator()
+                        return rate_limit.generate(
+                            advanced_generator.convert_to_event_stream(
+                                advanced_generator.generate(
+                                    app_model=app_model,
+                                    workflow=workflow,
+                                    user=user,
+                                    args=args,
+                                    invoke_from=invoke_from,
+                                    workflow_run_id=str(uuid.uuid4()),
+                                    streaming=False,
+                                )
+                            ),
+                            request_id=request_id,
+                        )
+                except Exception:
+                    logger.warning(
+                        "[AGENT_V2_UPGRADE] Transparent upgrade failed for app %s, falling back to legacy",
+                        app_model.id,
+                        exc_info=True,
+                    )
+
             match effective_mode:
                 case AppMode.COMPLETION:
                     return rate_limit.generate(
@@ -147,6 +222,54 @@ class AppGenerateService:
                         ),
                         request_id=request_id,
                     )
+                case AppMode.AGENT:
+                    workflow_id = args.get("workflow_id")
+                    workflow = cls._get_workflow(app_model, invoke_from, workflow_id)
+
+                    if streaming:
+                        with rate_limit_context(rate_limit, request_id):
+                            payload = AppExecutionParams.new(
+                                app_model=app_model,
+                                workflow=workflow,
+                                user=user,
+                                args=args,
+                                invoke_from=invoke_from,
+                                streaming=True,
+                                call_depth=0,
+                            )
+                            payload_json = payload.model_dump_json()
+
+                        def on_subscribe():
+                            workflow_based_app_execution_task.delay(payload_json)
+
+                        on_subscribe = cls._build_streaming_task_on_subscribe(on_subscribe)
+                        generator = AdvancedChatAppGenerator()
+                        return rate_limit.generate(
+                            generator.convert_to_event_stream(
+                                generator.retrieve_events(
+                                    AppMode.AGENT,
+                                    payload.workflow_run_id,
+                                    on_subscribe=on_subscribe,
+                                ),
+                            ),
+                            request_id=request_id,
+                        )
+                    else:
+                        advanced_generator = AdvancedChatAppGenerator()
+                        return rate_limit.generate(
+                            advanced_generator.convert_to_event_stream(
+                                advanced_generator.generate(
+                                    app_model=app_model,
+                                    workflow=workflow,
+                                    user=user,
+                                    args=args,
+                                    invoke_from=invoke_from,
+                                    workflow_run_id=str(uuid.uuid4()),
+                                    streaming=False,
+                                )
+                            ),
+                            request_id=request_id,
+                        )
                 case AppMode.ADVANCED_CHAT:
                     workflow_id = args.get("workflow_id")
                     workflow = cls._get_workflow(app_model, invoke_from, workflow_id)

api/services/app_model_config_service.py

@@ -14,5 +14,5 @@ class AppModelConfigService:
                 return AgentChatAppConfigManager.config_validate(tenant_id, config)
             case AppMode.COMPLETION:
                 return CompletionAppConfigManager.config_validate(tenant_id, config)
-            case AppMode.WORKFLOW | AppMode.ADVANCED_CHAT | AppMode.CHANNEL | AppMode.RAG_PIPELINE:
+            case AppMode.WORKFLOW | AppMode.ADVANCED_CHAT | AppMode.AGENT | AppMode.CHANNEL | AppMode.RAG_PIPELINE:
                 raise ValueError(f"Invalid app mode: {app_mode}")

api/services/app_runtime_upgrade_service.py

@@ -0,0 +1,443 @@
+"""Service for upgrading Classic runtime apps to Sandboxed runtime via clone-and-convert.
+
+The upgrade flow:
+1. Clone the source app via DSL export/import
+2. On the cloned app's draft workflow, convert Agent nodes to LLM nodes
+3. Rewrite variable references for all LLM nodes (old output names → new generation-based names)
+4. Enable sandbox feature flag
+
+The original app is never modified; the user gets a new sandboxed copy.
+"""
+
+import json
+import logging
+import re
+import uuid
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from models import App, Workflow
+from models.workflow_features import WorkflowFeatures
+from services.app_dsl_service import AppDslService, ImportMode
+
+logger = logging.getLogger(__name__)
+
+_VAR_REWRITES: dict[str, list[str]] = {
+    "text": ["generation", "content"],
+    "reasoning_content": ["generation", "reasoning_content"],
+}
+
+_PASSTHROUGH_KEYS = (
+    "version",
+    "error_strategy",
+    "default_value",
+    "retry_config",
+    "parent_node_id",
+    "isInLoop",
+    "loop_id",
+    "isInIteration",
+    "iteration_id",
+)
+
+
+class AppRuntimeUpgradeService:
+    """Upgrades a Classic-runtime app to Sandboxed runtime by cloning and converting.
+
+    Holds an active SQLAlchemy session; the caller is responsible for commit/rollback.
+    """
+
+    session: Session
+
+    def __init__(self, session: Session) -> None:
+        self.session = session
+
+    def upgrade(self, app_model: App, account: Any) -> dict[str, Any]:
+        """Clone *app_model* and upgrade the clone to sandboxed runtime.
+
+        Returns:
+            dict with keys: result, new_app_id, converted_agents, skipped_agents.
+        """
+        workflow = self._get_draft_workflow(app_model)
+        if not workflow:
+            return {"result": "no_draft"}
+
+        if workflow.get_feature(WorkflowFeatures.SANDBOX).enabled:
+            return {"result": "already_sandboxed"}
+
+        new_app = self._clone_app(app_model, account)
+        new_workflow = self._get_draft_workflow(new_app)
+        if not new_workflow:
+            return {"result": "no_draft"}
+
+        graph = json.loads(new_workflow.graph) if new_workflow.graph else {}
+        nodes = graph.get("nodes", [])
+
+        converted, skipped = _convert_agent_nodes(nodes)
+        _enable_computer_use_for_existing_llm_nodes(nodes)
+
+        llm_node_ids = {n["id"] for n in nodes if n.get("data", {}).get("type") == "llm"}
+        _rewrite_variable_references(nodes, llm_node_ids)
+
+        new_workflow.graph = json.dumps(graph)
+
+        features = json.loads(new_workflow.features) if new_workflow.features else {}
+        features.setdefault("sandbox", {})["enabled"] = True
+        new_workflow.features = json.dumps(features)
+
+        return {
+            "result": "success",
+            "new_app_id": str(new_app.id),
+            "converted_agents": converted,
+            "skipped_agents": skipped,
+        }
+
+    def _get_draft_workflow(self, app_model: App) -> Workflow | None:
+        stmt = select(Workflow).where(
+            Workflow.tenant_id == app_model.tenant_id,
+            Workflow.app_id == app_model.id,
+            Workflow.version == "draft",
+        )
+        return self.session.scalar(stmt)
+
+    def _clone_app(self, app_model: App, account: Any) -> App:
+        dsl_service = AppDslService(self.session)
+        yaml_content = dsl_service.export_dsl(app_model=app_model, include_secret=True)
+        result = dsl_service.import_app(
+            account=account,
+            import_mode=ImportMode.YAML_CONTENT,
+            yaml_content=yaml_content,
+            name=f"{app_model.name} (Sandboxed)",
+        )
+        stmt = select(App).where(App.id == result.app_id)
+        new_app = self.session.scalar(stmt)
+        if not new_app:
+            raise RuntimeError(f"Cloned app not found: {result.app_id}")
+        return new_app
+
+
+# ---------------------------------------------------------------------------
+# Pure conversion functions (no DB access)
+# ---------------------------------------------------------------------------
+
+
+def _convert_agent_nodes(nodes: list[dict[str, Any]]) -> tuple[int, int]:
+    """Convert Agent nodes to LLM nodes in-place. Returns (converted_count, skipped_count)."""
+    converted = 0
+
+    for node in nodes:
+        data = node.get("data", {})
+        if data.get("type") != "agent":
+            continue
+
+        node_id = node.get("id", "?")
+        node["data"] = _agent_data_to_llm_data(data)
+        logger.info("Converted agent node %s to LLM", node_id)
+        converted += 1
+
+    return converted, 0
+
+
+def _agent_data_to_llm_data(agent_data: dict[str, Any]) -> dict[str, Any]:
+    """Map an Agent node's data dict to an LLM node's data dict.
+
+    Always returns a valid LLM data dict. If the agent has no model selected,
+    produces an empty LLM node with agent mode (computer_use) enabled.
+    """
+    params = agent_data.get("agent_parameters") or {}
+
+    model_param = params.get("model", {}) if isinstance(params, dict) else {}
+    model_value = model_param.get("value") if isinstance(model_param, dict) else None
+
+    if isinstance(model_value, dict) and model_value.get("provider") and model_value.get("model"):
+        model_config = {
+            "provider": model_value["provider"],
+            "name": model_value["model"],
+            "mode": model_value.get("mode", "chat"),
+            "completion_params": model_value.get("completion_params", {}),
+        }
+    else:
+        model_config = {"provider": "", "name": "", "mode": "chat", "completion_params": {}}
+
+    tools_param = params.get("tools", {})
+    tools_value = tools_param.get("value", []) if isinstance(tools_param, dict) else []
+    tools_meta, tool_settings = _convert_tools(tools_value if isinstance(tools_value, list) else [])
+
+    instruction_param = params.get("instruction", {})
+    instruction = instruction_param.get("value", "") if isinstance(instruction_param, dict) else ""
+
+    query_param = params.get("query", {})
+    query_value = query_param.get("value", "") if isinstance(query_param, dict) else ""
+
+    has_tools = bool(tools_meta)
+    prompt_template = _build_prompt_template(
+        instruction,
+        query_value,
+        skill=has_tools,
+        tools=tools_value if has_tools else None,
+    )
+
+    max_iter_param = params.get("maximum_iterations", {})
+    max_iterations = max_iter_param.get("value", 100) if isinstance(max_iter_param, dict) else 100
+
+    context_config = _extract_context(params)
+    vision_config = _extract_vision(params)
+
+    llm_data: dict[str, Any] = {
+        "type": "llm",
+        "title": agent_data.get("title", "LLM"),
+        "desc": agent_data.get("desc", ""),
+        "model": model_config,
+        "prompt_template": prompt_template,
+        "prompt_config": {"jinja2_variables": []},
+        "memory": agent_data.get("memory"),
+        "context": context_config,
+        "vision": vision_config,
+        "computer_use": True,
+        "structured_output_switch_on": False,
+        "reasoning_format": "separated",
+        "tools": tools_meta,
+        "tool_settings": tool_settings,
+        "max_iterations": max_iterations,
+    }
+
+    for key in _PASSTHROUGH_KEYS:
+        if key in agent_data:
+            llm_data[key] = agent_data[key]
+
+    return llm_data
+
+
+def _extract_context(params: dict[str, Any]) -> dict[str, Any]:
+    """Extract context config from agent_parameters for LLM node format.
+
+    Agent stores context as a variable selector in agent_parameters.context.value,
+    e.g. ["knowledge_retrieval_node_id", "result"]. Maps to LLM ContextConfig.
+    """
+    if not isinstance(params, dict):
+        return {"enabled": False}
+
+    ctx_param = params.get("context", {})
+    ctx_value = ctx_param.get("value") if isinstance(ctx_param, dict) else None
+
+    if isinstance(ctx_value, list) and len(ctx_value) >= 2 and all(isinstance(s, str) for s in ctx_value):
+        return {"enabled": True, "variable_selector": ctx_value}
+
+    return {"enabled": False}
+
+
+def _extract_vision(params: dict[str, Any]) -> dict[str, Any]:
+    """Extract vision config from agent_parameters for LLM node format."""
+    if not isinstance(params, dict):
+        return {"enabled": False}
+
+    vision_param = params.get("vision", {})
+    vision_value = vision_param.get("value") if isinstance(vision_param, dict) else None
+
+    if isinstance(vision_value, dict) and vision_value.get("enabled"):
+        return vision_value
+
+    if isinstance(vision_value, bool) and vision_value:
+        return {"enabled": True}
+
+    return {"enabled": False}
+
+
+def _enable_computer_use_for_existing_llm_nodes(nodes: list[dict[str, Any]]) -> None:
+    """Enable computer_use for existing LLM nodes that have tools configured.
+
+    After upgrade, the sandbox runtime requires computer_use=true for tool calling.
+    Existing LLM nodes from classic mode may have tools but computer_use=false.
+    """
+    for node in nodes:
+        data = node.get("data", {})
+        if data.get("type") != "llm":
+            continue
+
+        tools = data.get("tools", [])
+        if tools and not data.get("computer_use"):
+            data["computer_use"] = True
+            logger.info("Enabled computer_use for LLM node %s with %d tools", node.get("id", "?"), len(tools))
+
+
+def _convert_tools(
+    tools_input: list[dict[str, Any]],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Convert agent tool dicts to (ToolMetadata[], ToolSetting[]).
+
+    Agent tools in graph JSON already use provider_name/settings/parameters —
+    the same field names as LLM ToolMetadata. We pass them through with defaults
+    for any missing fields.
+    """
+    tools_meta: list[dict[str, Any]] = []
+    tool_settings: list[dict[str, Any]] = []
+
+    for ts in tools_input:
+        if not isinstance(ts, dict):
+            continue
+
+        provider_name = ts.get("provider_name", "")
+        tool_name = ts.get("tool_name", "")
+        tool_type = ts.get("type", "builtin")
+
+        tools_meta.append(
+            {
+                "enabled": True,
+                "type": tool_type,
+                "provider_name": provider_name,
+                "tool_name": tool_name,
+                "plugin_unique_identifier": ts.get("plugin_unique_identifier"),
+                "credential_id": ts.get("credential_id"),
+                "parameters": ts.get("parameters", {}),
+                "settings": ts.get("settings", {}) or ts.get("tool_configuration", {}),
+                "extra": ts.get("extra", {}),
+            }
+        )
+
+        tool_settings.append(
+            {
+                "type": tool_type,
+                "provider": provider_name,
+                "tool_name": tool_name,
+                "enabled": True,
+            }
+        )
+
+    return tools_meta, tool_settings
+
+
+def _build_prompt_template(
+    instruction: Any,
+    query: Any,
+    *,
+    skill: bool = False,
+    tools: list[dict[str, Any]] | None = None,
+) -> list[dict[str, Any]]:
+    """Build LLM prompt_template from Agent instruction and query values.
+
+    When *skill* is True each message gets ``"skill": True`` so the sandbox
+    engine treats the prompt as a skill document.
+
+    When *tools* is provided, tool reference placeholders
+    (``§[tool].[provider].[name].[uuid]§``) are appended to the system
+    message and the corresponding ``ToolReference`` entries are placed in the
+    message's ``metadata.tools`` dict so the skill assembler can resolve them.
+    Tools from the same provider are grouped into a single token list.
+    """
+    messages: list[dict[str, Any]] = []
+
+    system_text = instruction if isinstance(instruction, str) else (str(instruction) if instruction else "")
+    metadata: dict[str, Any] | None = None
+
+    if tools:
+        tool_refs: dict[str, dict[str, Any]] = {}
+        provider_groups: dict[str, list[str]] = {}
+        for ts in tools:
+            if not isinstance(ts, dict):
+                continue
+            tool_uuid = str(uuid.uuid4())
+            provider_id = ts.get("provider_name", "")
+            tool_name = ts.get("tool_name", "")
+            tool_type = ts.get("type", "builtin")
+
+            token = f"§[tool].[{provider_id}].[{tool_name}].[{tool_uuid}]§"
+            provider_groups.setdefault(provider_id, []).append(token)
+            tool_refs[tool_uuid] = {
+                "type": tool_type,
+                "configuration": {"fields": []},
+                "enabled": True,
+                **({"credential_id": ts.get("credential_id")} if ts.get("credential_id") else {}),
+            }
+
+        if provider_groups:
+            group_texts: list[str] = []
+            for tokens in provider_groups.values():
+                if len(tokens) == 1:
+                    group_texts.append(tokens[0])
+                else:
+                    group_texts.append("[" + ",".join(tokens) + "]")
+            all_tools_text = " ".join(group_texts)
+            system_text = f"{system_text}\n\n{all_tools_text}" if system_text else all_tools_text
+            metadata = {"tools": tool_refs, "files": []}
+
+    if system_text:
+        msg: dict[str, Any] = {"role": "system", "text": system_text, "skill": skill}
+        if metadata:
+            msg["metadata"] = metadata
+        messages.append(msg)
+
+    if isinstance(query, list) and len(query) >= 2:
+        template_ref = "{{#" + ".".join(str(s) for s in query) + "#}}"
+        messages.append({"role": "user", "text": template_ref, "skill": skill})
+    elif query:
+        messages.append({"role": "user", "text": str(query), "skill": skill})
+
+    if not messages:
+        messages.append({"role": "user", "text": "", "skill": skill})
+
+    return messages
+
+
+def _rewrite_variable_references(nodes: list[dict[str, Any]], llm_ids: set[str]) -> None:
+    """Recursively walk all node data and rewrite variable references for LLM nodes.
+
+    Handles two forms:
+    - Structured selectors: [node_id, "text"] → [node_id, "generation", "content"]
+    - Template strings: {{#node_id.text#}} → {{#node_id.generation.content#}}
+    """
+    if not llm_ids:
+        return
+
+    escaped_ids = [re.escape(nid) for nid in llm_ids]
+    patterns: list[tuple[re.Pattern[str], str]] = []
+    for old_name, new_path in _VAR_REWRITES.items():
+        pattern = re.compile(r"\{\{#(" + "|".join(escaped_ids) + r")\." + re.escape(old_name) + r"#\}\}")
+        replacement = r"{{#\1." + ".".join(new_path) + r"#}}"
+        patterns.append((pattern, replacement))
+
+    for node in nodes:
+        data = node.get("data", {})
+        _walk_and_rewrite(data, llm_ids, patterns)
+
+
+def _walk_and_rewrite(
+    obj: Any,
+    llm_ids: set[str],
+    template_patterns: list[tuple[re.Pattern[str], str]],
+) -> Any:
+    """Recursively rewrite variable references in a nested data structure."""
+    if isinstance(obj, dict):
+        for key, value in obj.items():
+            obj[key] = _walk_and_rewrite(value, llm_ids, template_patterns)
+        return obj
+
+    if isinstance(obj, list):
+        if _is_variable_selector(obj, llm_ids):
+            return _rewrite_selector(obj)
+        for i, item in enumerate(obj):
+            obj[i] = _walk_and_rewrite(item, llm_ids, template_patterns)
+        return obj
+
+    if isinstance(obj, str):
+        for pattern, replacement in template_patterns:
+            obj = pattern.sub(replacement, obj)
+        return obj
+
+    return obj
+
+
+def _is_variable_selector(lst: list, llm_ids: set[str]) -> bool:
+    """Check if a list is a structured variable selector pointing to an LLM node output."""
+    if len(lst) < 2:
+        return False
+    if not all(isinstance(s, str) for s in lst):
+        return False
+    return lst[0] in llm_ids and lst[1] in _VAR_REWRITES
+
+
+def _rewrite_selector(selector: list[str]) -> list[str]:
+    """Rewrite [node_id, "text"] → [node_id, "generation", "content"]."""
+    old_field = selector[1]
+    new_path = _VAR_REWRITES[old_field]
+    return [selector[0]] + new_path + selector[2:]

api/services/app_service.py

@@ -10,6 +10,7 @@ from sqlalchemy import select
 
 from configs import dify_config
 from constants.model_template import default_app_templates
+from services.workflow.graph_factory import WorkflowGraphFactory
 from core.agent.entities import AgentToolEntity
 from core.errors.error import LLMBadRequestError, ProviderTokenNotInitError
 from core.model_manager import ModelManager
@@ -52,6 +53,8 @@ class AppService:
             filters.append(App.mode == AppMode.ADVANCED_CHAT)
         elif args["mode"] == "agent-chat":
             filters.append(App.mode == AppMode.AGENT_CHAT)
+        elif args["mode"] == "agent":
+            filters.append(App.mode == AppMode.AGENT)
 
         if args.get("is_created_by_me", False):
             filters.append(App.created_by == user_id)
@@ -169,6 +172,10 @@ class AppService:
 
         db.session.commit()
 
+        if app_mode == AppMode.AGENT:
+            model_dict = default_model_config.get("model") if default_model_config else None
+            self._init_agent_workflow(app, account, model_dict)
+
         app_was_created.send(app, account=account)
 
         if FeatureService.get_system_features().webapp_auth.enabled:
@@ -180,6 +187,34 @@ class AppService:
 
         return app
 
+    @staticmethod
+    def _init_agent_workflow(app: App, account: Any, model_dict: dict | None) -> None:
+        """Create the default single-agent-node workflow for a new Agent app."""
+        from services.workflow_service import WorkflowService
+
+        model_config = model_dict or {
+            "provider": "openai",
+            "name": "gpt-4o",
+            "mode": "chat",
+            "completion_params": {},
+        }
+
+        graph = WorkflowGraphFactory.create_single_agent_graph(
+            model_config=model_config,
+            is_chat=True,
+        )
+
+        workflow_service = WorkflowService()
+        workflow_service.sync_draft_workflow(
+            app_model=app,
+            graph=graph,
+            features={},
+            unique_hash=None,
+            account=account,
+            environment_variables=[],
+            conversation_variables=[],
+        )
+
     def get_app(self, app: App) -> App:
         """
         Get App

api/services/llm_generation_service.py

@@ -0,0 +1,37 @@
+"""
+LLM Generation Detail Service.
+
+Provides methods to query and attach generation details to workflow node executions
+and messages, avoiding N+1 query problems.
+"""
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from core.app.entities.llm_generation_entities import LLMGenerationDetailData
+from models import LLMGenerationDetail
+
+
+class LLMGenerationService:
+    """Service for handling LLM generation details."""
+
+    def __init__(self, session: Session):
+        self._session = session
+
+    def get_generation_detail_for_message(self, message_id: str) -> LLMGenerationDetailData | None:
+        """Query generation detail for a specific message."""
+        stmt = select(LLMGenerationDetail).where(LLMGenerationDetail.message_id == message_id)
+        detail = self._session.scalars(stmt).first()
+        return detail.to_domain_model() if detail else None
+
+    def get_generation_details_for_messages(
+        self,
+        message_ids: list[str],
+    ) -> dict[str, LLMGenerationDetailData]:
+        """Batch query generation details for multiple messages."""
+        if not message_ids:
+            return {}
+
+        stmt = select(LLMGenerationDetail).where(LLMGenerationDetail.message_id.in_(message_ids))
+        details = self._session.scalars(stmt).all()
+        return {detail.message_id: detail.to_domain_model() for detail in details if detail.message_id}

api/services/storage_ticket_service.py

@@ -0,0 +1,153 @@
+"""Storage ticket service for generating opaque download/upload URLs.
+
+This service provides a ticket-based approach for file access. Instead of exposing
+the real storage key in URLs, it generates a random UUID token and stores the mapping
+in Redis with a TTL.
+
+Usage:
+    from services.storage_ticket_service import StorageTicketService
+
+    # Generate a download ticket
+    url = StorageTicketService.create_download_url("path/to/file.txt", expires_in=300)
+
+    # Generate an upload ticket
+    url = StorageTicketService.create_upload_url("path/to/file.txt", expires_in=300, max_bytes=10*1024*1024)
+
+URL format:
+    {FILES_API_URL}/files/storage-files/{token}
+
+The token is validated by looking up the Redis key, which contains:
+    - op: "download" or "upload"
+    - storage_key: the real storage path
+    - max_bytes: (upload only) maximum allowed upload size
+    - filename: suggested filename for Content-Disposition header
+"""
+
+import logging
+from typing import Literal
+from uuid import uuid4
+
+from pydantic import BaseModel
+
+from configs import dify_config
+from extensions.ext_redis import redis_client
+
+logger = logging.getLogger(__name__)
+
+TICKET_KEY_PREFIX = "storage_files"
+DEFAULT_DOWNLOAD_TTL = 300  # 5 minutes
+DEFAULT_UPLOAD_TTL = 300  # 5 minutes
+DEFAULT_MAX_UPLOAD_BYTES = 100 * 1024 * 1024  # 100MB
+
+
+class StorageTicket(BaseModel):
+    """Represents a storage access ticket."""
+
+    op: Literal["download", "upload"]
+    storage_key: str
+    max_bytes: int | None = None  # upload only
+    filename: str | None = None  # suggested filename for download
+
+
+class StorageTicketService:
+    """Service for creating and validating storage access tickets."""
+
+    @classmethod
+    def create_download_url(
+        cls,
+        storage_key: str,
+        *,
+        expires_in: int = DEFAULT_DOWNLOAD_TTL,
+        filename: str | None = None,
+    ) -> str:
+        """Create a download ticket and return the URL.
+
+        Args:
+            storage_key: The real storage path
+            expires_in: TTL in seconds (default 300)
+            filename: Suggested filename for Content-Disposition header
+
+        Returns:
+            Full URL with token
+        """
+        if filename is None:
+            filename = storage_key.rsplit("/", 1)[-1]
+
+        ticket = StorageTicket(op="download", storage_key=storage_key, filename=filename)
+        token = cls._store_ticket(ticket, expires_in)
+        return cls._build_url(token)
+
+    @classmethod
+    def create_upload_url(
+        cls,
+        storage_key: str,
+        *,
+        expires_in: int = DEFAULT_UPLOAD_TTL,
+        max_bytes: int = DEFAULT_MAX_UPLOAD_BYTES,
+    ) -> str:
+        """Create an upload ticket and return the URL.
+
+        Args:
+            storage_key: The real storage path
+            expires_in: TTL in seconds (default 300)
+            max_bytes: Maximum allowed upload size in bytes
+
+        Returns:
+            Full URL with token
+        """
+        ticket = StorageTicket(op="upload", storage_key=storage_key, max_bytes=max_bytes)
+        token = cls._store_ticket(ticket, expires_in)
+        return cls._build_url(token)
+
+    @classmethod
+    def get_ticket(cls, token: str) -> StorageTicket | None:
+        """Retrieve a ticket by token.
+
+        Args:
+            token: The UUID token from the URL
+
+        Returns:
+            StorageTicket if found and valid, None otherwise
+        """
+        key = cls._ticket_key(token)
+        try:
+            data = redis_client.get(key)
+            if data is None:
+                return None
+            if isinstance(data, bytes):
+                data = data.decode("utf-8")
+            return StorageTicket.model_validate_json(data)
+        except Exception:
+            logger.warning("Failed to retrieve storage ticket: %s", token, exc_info=True)
+            return None
+
+    @classmethod
+    def _store_ticket(cls, ticket: StorageTicket, ttl: int) -> str:
+        """Store a ticket in Redis and return the token."""
+        token = str(uuid4())
+        key = cls._ticket_key(token)
+        value = ticket.model_dump_json()
+        redis_client.setex(key, ttl, value)
+        return token
+
+    @classmethod
+    def _ticket_key(cls, token: str) -> str:
+        """Generate Redis key for a token."""
+        return f"{TICKET_KEY_PREFIX}:{token}"
+
+    @classmethod
+    def _build_url(cls, token: str) -> str:
+        """Build the full URL for a token.
+
+        FILES_API_URL is dedicated to sandbox runtime file access (agentbox/e2b/etc.).
+        This endpoint must be routable from the runtime environment.
+        """
+        base_url = dify_config.FILES_API_URL.strip()
+        if not base_url:
+            raise ValueError(
+                "FILES_API_URL is required for sandbox runtime file access. "
+                "Set FILES_API_URL to a URL reachable by your sandbox runtime. "
+                "For public sandbox environments (e.g. e2b), use a public domain or IP."
+            )
+        base_url = base_url.rstrip("/")
+        return f"{base_url}/files/storage-files/{token}"

api/services/tools/mcp_tools_manage_service.py

@@ -17,6 +17,7 @@ from core.helper import encrypter
 from core.helper.provider_cache import NoOpProviderCredentialCache
 from core.mcp.auth.auth_flow import auth
 from core.mcp.auth_client import MCPClientWithAuthRetry
+from core.mcp.entities import AuthActionType, AuthResult
 from core.mcp.error import MCPAuthError, MCPError
 from core.mcp.types import Tool as MCPTool
 from core.tools.entities.api_entities import ToolProviderApiEntity
@@ -496,7 +497,13 @@ class MCPToolManageService:
         ) as mcp_client:
             return mcp_client.list_tools()
 
-    def execute_auth_actions(self, auth_result: Any) -> dict[str, str]:
+    _ACTION_TO_OAUTH: dict[AuthActionType, OAuthDataType] = {
+        AuthActionType.SAVE_CLIENT_INFO: OAuthDataType.CLIENT_INFO,
+        AuthActionType.SAVE_TOKENS: OAuthDataType.TOKENS,
+        AuthActionType.SAVE_CODE_VERIFIER: OAuthDataType.CODE_VERIFIER,
+    }
+
+    def execute_auth_actions(self, auth_result: AuthResult) -> dict[str, str]:
         """
         Execute the actions returned by the auth function.
 
@@ -508,19 +515,13 @@ class MCPToolManageService:
         Returns:
             The response from the auth result
         """
-        from core.mcp.entities import AuthAction, AuthActionType
-
-        action: AuthAction
         for action in auth_result.actions:
             if action.provider_id is None or action.tenant_id is None:
                 continue
 
-            if action.action_type == AuthActionType.SAVE_CLIENT_INFO:
-                self.save_oauth_data(action.provider_id, action.tenant_id, action.data, OAuthDataType.CLIENT_INFO)
-            elif action.action_type == AuthActionType.SAVE_TOKENS:
-                self.save_oauth_data(action.provider_id, action.tenant_id, action.data, OAuthDataType.TOKENS)
-            elif action.action_type == AuthActionType.SAVE_CODE_VERIFIER:
-                self.save_oauth_data(action.provider_id, action.tenant_id, action.data, OAuthDataType.CODE_VERIFIER)
+            oauth_type = self._ACTION_TO_OAUTH.get(action.action_type)
+            if oauth_type is not None:
+                self.save_oauth_data(action.provider_id, action.tenant_id, action.data, oauth_type)
 
         return auth_result.response
 

api/services/tools/workflow_tools_manage_service.py

@@ -4,7 +4,7 @@ from datetime import datetime
 
 from graphon.model_runtime.utils.encoders import jsonable_encoder
 from sqlalchemy import delete, or_, select
-from sqlalchemy.orm import Session
+from sqlalchemy.orm import sessionmaker
 
 from core.tools.__base.tool_provider import ToolProviderController
 from core.tools.entities.api_entities import ToolApiEntity, ToolProviderApiEntity
@@ -42,32 +42,43 @@ class WorkflowToolManageService:
         labels: list[str] | None = None,
     ):
         # check if the name is unique
-        existing_workflow_tool_provider = db.session.scalar(
-            select(WorkflowToolProvider)
-            .where(
-                WorkflowToolProvider.tenant_id == tenant_id,
-                # name or app_id
-                or_(WorkflowToolProvider.name == name, WorkflowToolProvider.app_id == workflow_app_id),
+        existing_workflow_tool_provider: WorkflowToolProvider | None = None
+        with sessionmaker(db.engine, expire_on_commit=False).begin() as _session:
+            # query if the name or app_id exists
+            existing_workflow_tool_provider = _session.scalar(
+                select(WorkflowToolProvider)
+                .where(
+                    WorkflowToolProvider.tenant_id == tenant_id,
+                    # name or app_id
+                    or_(WorkflowToolProvider.name == name, WorkflowToolProvider.app_id == workflow_app_id),
+                )
+                .limit(1)
             )
-            .limit(1)
-        )
 
+        # if the name or app_id exists raise error
         if existing_workflow_tool_provider is not None:
             raise ValueError(f"Tool with name {name} or app_id {workflow_app_id} already exists")
 
-        app: App | None = db.session.scalar(
-            select(App).where(App.id == workflow_app_id, App.tenant_id == tenant_id).limit(1)
-        )
+        # query the app
+        app: App | None = None
+        with sessionmaker(db.engine, expire_on_commit=False).begin() as _session:
+            app = _session.scalar(select(App).where(App.id == workflow_app_id, App.tenant_id == tenant_id).limit(1))
 
+        # if not found raise error
         if app is None:
             raise ValueError(f"App {workflow_app_id} not found")
 
+        # query the workflow
         workflow: Workflow | None = app.workflow
+
+        # if not found raise error
         if workflow is None:
             raise ValueError(f"Workflow not found for app {workflow_app_id}")
 
+        # check if workflow configuration is synced
         WorkflowToolConfigurationUtils.ensure_no_human_input_nodes(workflow.graph_dict)
 
+        # create workflow tool provider
         workflow_tool_provider = WorkflowToolProvider(
             tenant_id=tenant_id,
             user_id=user_id,
@@ -87,13 +98,15 @@ class WorkflowToolManageService:
             logger.warning(e, exc_info=True)
             raise ValueError(str(e))
 
-        with Session(db.engine, expire_on_commit=False) as session, session.begin():
-            session.add(workflow_tool_provider)
+        with sessionmaker(db.engine, expire_on_commit=False).begin() as _session:
+            _session.add(workflow_tool_provider)
 
+        # keep the session open to make orm instances in the same session
         if labels is not None:
             ToolLabelManager.update_tool_labels(
                 ToolTransformService.workflow_provider_to_controller(workflow_tool_provider), labels
             )
+
         return {"result": "success"}
 
     @classmethod
@@ -112,6 +125,7 @@ class WorkflowToolManageService:
     ):
         """
         Update a workflow tool.
+
         :param user_id: the user id
         :param tenant_id: the tenant id
         :param workflow_tool_id: workflow tool id
@@ -187,28 +201,32 @@ class WorkflowToolManageService:
     def list_tenant_workflow_tools(cls, user_id: str, tenant_id: str) -> list[ToolProviderApiEntity]:
         """
         List workflow tools.
+
         :param user_id: the user id
         :param tenant_id: the tenant id
         :return: the list of tools
         """
-        db_tools = db.session.scalars(
-            select(WorkflowToolProvider).where(WorkflowToolProvider.tenant_id == tenant_id)
-        ).all()
+
+        providers: list[WorkflowToolProvider] = []
+        with sessionmaker(db.engine, expire_on_commit=False).begin() as _session:
+            providers = list(
+                _session.scalars(select(WorkflowToolProvider).where(WorkflowToolProvider.tenant_id == tenant_id)).all()
+            )
 
         # Create a mapping from provider_id to app_id
-        provider_id_to_app_id = {provider.id: provider.app_id for provider in db_tools}
+        provider_id_to_app_id = {provider.id: provider.app_id for provider in providers}
 
         tools: list[WorkflowToolProviderController] = []
-        for provider in db_tools:
+        for provider in providers:
             try:
                 tools.append(ToolTransformService.workflow_provider_to_controller(provider))
             except Exception:
                 # skip deleted tools
                 logger.exception("Failed to load workflow tool provider %s", provider.id)
 
-        labels = ToolLabelManager.get_tools_labels([t for t in tools if isinstance(t, ToolProviderController)])
+        labels = ToolLabelManager.get_tools_labels([tool for tool in tools if isinstance(tool, ToolProviderController)])
 
-        result = []
+        result: list[ToolProviderApiEntity] = []
 
         for tool in tools:
             workflow_app_id = provider_id_to_app_id.get(tool.provider_id)
@@ -233,17 +251,18 @@ class WorkflowToolManageService:
     def delete_workflow_tool(cls, user_id: str, tenant_id: str, workflow_tool_id: str):
         """
         Delete a workflow tool.
+
         :param user_id: the user id
         :param tenant_id: the tenant id
         :param workflow_tool_id: the workflow tool id
         """
-        db.session.execute(
-            delete(WorkflowToolProvider).where(
-                WorkflowToolProvider.tenant_id == tenant_id, WorkflowToolProvider.id == workflow_tool_id
-            )
-        )
 
-        db.session.commit()
+        with sessionmaker(db.engine).begin() as _session:
+            _ = _session.execute(
+                delete(WorkflowToolProvider).where(
+                    WorkflowToolProvider.tenant_id == tenant_id, WorkflowToolProvider.id == workflow_tool_id
+                )
+            )
 
         return {"result": "success"}
 
@@ -251,47 +270,59 @@ class WorkflowToolManageService:
     def get_workflow_tool_by_tool_id(cls, user_id: str, tenant_id: str, workflow_tool_id: str):
         """
         Get a workflow tool.
+
         :param user_id: the user id
         :param tenant_id: the tenant id
         :param workflow_tool_id: the workflow tool id
         :return: the tool
         """
-        db_tool: WorkflowToolProvider | None = db.session.scalar(
-            select(WorkflowToolProvider)
-            .where(WorkflowToolProvider.tenant_id == tenant_id, WorkflowToolProvider.id == workflow_tool_id)
-            .limit(1)
-        )
-        return cls._get_workflow_tool(tenant_id, db_tool)
+
+        tool_provider: WorkflowToolProvider | None = None
+        with sessionmaker(db.engine, expire_on_commit=False).begin() as _session:
+            tool_provider = _session.scalar(
+                select(WorkflowToolProvider)
+                .where(WorkflowToolProvider.tenant_id == tenant_id, WorkflowToolProvider.id == workflow_tool_id)
+                .limit(1)
+            )
+
+        return cls._get_workflow_tool(tenant_id, tool_provider)
 
     @classmethod
     def get_workflow_tool_by_app_id(cls, user_id: str, tenant_id: str, workflow_app_id: str):
         """
         Get a workflow tool.
+
         :param user_id: the user id
         :param tenant_id: the tenant id
         :param workflow_app_id: the workflow app id
         :return: the tool
         """
-        db_tool: WorkflowToolProvider | None = db.session.scalar(
-            select(WorkflowToolProvider)
-            .where(WorkflowToolProvider.tenant_id == tenant_id, WorkflowToolProvider.app_id == workflow_app_id)
-            .limit(1)
-        )
-        return cls._get_workflow_tool(tenant_id, db_tool)
+
+        with sessionmaker(db.engine, expire_on_commit=False).begin() as _session:
+            tool_provider: WorkflowToolProvider | None = _session.scalar(
+                select(WorkflowToolProvider)
+                .where(WorkflowToolProvider.tenant_id == tenant_id, WorkflowToolProvider.app_id == workflow_app_id)
+                .limit(1)
+            )
+
+        return cls._get_workflow_tool(tenant_id, tool_provider)
 
     @classmethod
     def _get_workflow_tool(cls, tenant_id: str, db_tool: WorkflowToolProvider | None):
         """
         Get a workflow tool.
+
         :db_tool: the database tool
         :return: the tool
         """
         if db_tool is None:
             raise ValueError("Tool not found")
 
-        workflow_app: App | None = db.session.scalar(
-            select(App).where(App.id == db_tool.app_id, App.tenant_id == db_tool.tenant_id).limit(1)
-        )
+        workflow_app: App | None = None
+        with sessionmaker(db.engine, expire_on_commit=False).begin() as _session:
+            workflow_app = _session.scalar(
+                select(App).where(App.id == db_tool.app_id, App.tenant_id == db_tool.tenant_id).limit(1)
+            )
 
         if workflow_app is None:
             raise ValueError(f"App {db_tool.app_id} not found")
@@ -331,28 +362,32 @@ class WorkflowToolManageService:
     def list_single_workflow_tools(cls, user_id: str, tenant_id: str, workflow_tool_id: str) -> list[ToolApiEntity]:
         """
         List workflow tool provider tools.
+
         :param user_id: the user id
         :param tenant_id: the tenant id
         :param workflow_tool_id: the workflow tool id
         :return: the list of tools
         """
-        db_tool: WorkflowToolProvider | None = db.session.scalar(
-            select(WorkflowToolProvider)
-            .where(WorkflowToolProvider.tenant_id == tenant_id, WorkflowToolProvider.id == workflow_tool_id)
-            .limit(1)
-        )
 
-        if db_tool is None:
+        provider: WorkflowToolProvider | None = None
+        with sessionmaker(db.engine, expire_on_commit=False).begin() as _session:
+            provider = _session.scalar(
+                select(WorkflowToolProvider)
+                .where(WorkflowToolProvider.tenant_id == tenant_id, WorkflowToolProvider.id == workflow_tool_id)
+                .limit(1)
+            )
+
+        if provider is None:
             raise ValueError(f"Tool {workflow_tool_id} not found")
 
-        tool = ToolTransformService.workflow_provider_to_controller(db_tool)
+        tool = ToolTransformService.workflow_provider_to_controller(provider)
         workflow_tools: list[WorkflowTool] = tool.get_tools(tenant_id)
         if len(workflow_tools) == 0:
             raise ValueError(f"Tool {workflow_tool_id} not found")
 
         return [
             ToolTransformService.convert_tool_entity_to_api_entity(
-                tool=tool.get_tools(db_tool.tenant_id)[0],
+                tool=tool.get_tools(provider.tenant_id)[0],
                 labels=ToolLabelManager.get_tool_labels(tool),
                 tenant_id=tenant_id,
             )

api/services/workflow/entities.py

@@ -152,6 +152,29 @@ class TriggerLogResponse(BaseModel):
     model_config = ConfigDict(use_enum_values=True)
 
 
+class NestedNodeParameterSchema(BaseModel):
+    """Schema for a single parameter in a nested node."""
+
+    name: str
+    type: str = "string"
+    description: str = ""
+
+
+class NestedNodeGraphRequest(BaseModel):
+    """Request for generating a nested node graph."""
+
+    parent_node_id: str
+    parameter_key: str
+    context_source: list[str] = Field(default_factory=list)
+    parameter_schema: NestedNodeParameterSchema
+
+
+class NestedNodeGraphResponse(BaseModel):
+    """Response containing the generated nested node graph."""
+
+    graph: dict[str, Any]
+
+
 class WorkflowScheduleCFSPlanEntity(BaseModel):
     """
     CFS plan entity.