1.13.0 - Human-in-the-Loop and Workflow Execution Upgrades

[QuantumGhost]

🚀 New Features

Human-in-the-Loop (HITL)

We are introducing the Human Input node, a major update that transforms how AI and humans
collaborate within Dify workflows.

Background

Previously, workflows were binary: either fully automated or fully manual. This created a "trust gap" in
high-stakes scenarios where AI speed is needed but human judgment is essential. With HITL, we are making h
uman oversight a native part of the workflow architecture, allowing you to embed
review steps directly into the execution graph.

Key Capabilities

• Native Workflow Pausing: Insert a "Human Input" node to suspend workflow execution at critical decision points.
• Review & Edit: The node generates a UI where humans can review AI outputs and modify variables (e.g., editing a draft or correcting data) before the process continues.
• Action-Based Routing: Configure custom buttons (like "Approve," "Reject," or "Escalate") that determine
  the subsequent path of the workflow.
• Flexible Delivery Methods: Human input forms can be delivered via Webapp or Email. In cloud environments, Email delivery availability may depend on plan/feature settings.

🛠 Architecture Updates

To support the stateful pause/resume mechanism required by HITL and provide event‑subscription APIs, we refactored the execution engine: Workflow‑based streaming executions and Advanced Chat executions now run in Celery workers, while non‑streaming WORKFLOW runs still execute in the API process.
All pause/resume paths (e.g., HITL) are resumed via Celery, and events are streamed back through Redis Pub/Sub.

For Large Deployments & Self-Hosted Users:

We have introduced a new Celery queue named workflow_based_app_execution. While standard setups will work out of the box, high-throughput environments should consider the following optimizations to ensure stability and performance:

1. Scale Workers: Adjust the number of workers consuming the workflow_based_app_execution queue based on your specific workload.
2. Dedicated Redis (Optional): For large-scale deployments, we recommend configuring the new PUBSUB_REDIS_URL environment variable to point to a dedicated Redis instance. Using Redis Cluster mode with Sharded PubSub is strongly advised to ensure horizontal scalability.

⚠️ Important Upgrade Note

New Celery Queue Required: workflow_based_app_execution

Please ensure your deployment configuration (Docker Compose, Helm Chart, etc.) includes workers listening to the new workflow_based_app_execution queue.
This queue is required for workflow‑based streaming executions and all resume flows (e.g., HITL); otherwise, streaming executions and resume tasks will not be processed.

🔧 Operational Note

Additional Celery Queue: api_token

If ENABLE_API_TOKEN_LAST_USED_UPDATE_TASK=true, ensure your deployment also has workers listening to api_token.
This queue is used by the scheduled batch update task for API token last_used_at timestamps.

⚙️ Configuration Changes

We have introduced several new environment variables to support the architectural changes. Large deployments should pay special attention to the PubSub Redis configurations to ensure scalability.

• PUBSUB_REDIS_URL (Critical): Specifies the Redis URL used for PubSub communication between the API and Celery workers. If left empty, it defaults to the standard REDIS_* configuration.
• PUBSUB_REDIS_CHANNEL_TYPE (Critical): Defines the channel type for streaming events. Options are pubsub (default) or sharded. We highly recommend using sharded for high-throughput environments.
• PUBSUB_REDIS_USE_CLUSTERS (Critical): Set to true to enable Redis cluster mode for PubSub. Combined with sharded PubSub, this is essential for horizontal scaling.

Other Additions:

• WEB_FORM_SUBMIT_RATE_LIMIT_MAX_ATTEMPTS: Maximum number of web form submissions allowed per IP within the rate limit window (Default: 30).
• WEB_FORM_SUBMIT_RATE_LIMIT_WINDOW_SECONDS: Time window in seconds for web form submission rate limiting (Default: 60).
• HUMAN_INPUT_GLOBAL_TIMEOUT_SECONDS: Maximum seconds a workflow run can stay paused waiting for human input before global timeout (Default: 604800, 7 days).
• ENABLE_HUMAN_INPUT_TIMEOUT_TASK: Enables the background task that checks for expired human input requests (Default: true).
• HUMAN_INPUT_TIMEOUT_TASK_INTERVAL: Sets the interval (in minutes) for the timeout check task (Default: 1).
• ENABLE_API_TOKEN_LAST_USED_UPDATE_TASK: Enables the periodic background task that batch-updates API token last_used_at timestamps (Default: true).
• API_TOKEN_LAST_USED_UPDATE_INTERVAL: Sets the interval (in minutes) for batch-updating API token last_used_at timestamps (Default: 30).
• SANDBOX_EXPIRED_RECORDS_CLEAN_BATCH_MAX_INTERVAL: Maximum random delay (in milliseconds) between retention cleanup batches to reduce DB pressure spikes (Default: 200).

📌 Additional Changelog Highlights

Reliability & Correctness

• Added migration-time deduplication and a unique constraint for tenant default models to prevent duplicate default model records.
• Fixed a tools-deletion edge case caused by provider ID type mismatch.
• Fixed a FastOpenAPI integration regression where authenticated users could be resolved as anonymous in remote file APIs.
• Fixed message event type detection for file-related responses, and hid the workspace invite action for non-manager users.

Performance & Scalability

• Reduced backend load and console latency with plugin manifest pre-caching and AppListApi query optimizations.
• Improved large-data task stability with split DB sessions, batched cleanup execution, index tuning, and configurable inter-batch throttling for retention cleanup jobs.

API & Platform Capabilities

• Added a Service API endpoint for end-user lookup with tenant/app scope enforcement.
• Improved workflow run history refresh behavior during run state transitions.
• Enhanced MCP Tool integration by extracting and reporting usage metadata (for example, token/cost fields) from MCP responses.

Security

• Removed dynamic new Function evaluation from ECharts parsing and now return explicit parsing errors for unsupported chart code.

Localization

• Added Dutch (nl-NL) language support across backend language mapping and web localization resources.

---

Upgrade Guide

Important

If you use custom CELERY_QUEUES, make sure workflow_based_app_execution is included.
If ENABLE_API_TOKEN_LAST_USED_UPDATE_TASK=true, also include api_token.

For background and details, see ⚠️ Important Upgrade Note and 🔧 Operational Note above.

Docker Compose Deployments

1. Back up your customized docker-compose YAML file (optional)

   cd docker
   cp docker-compose.yaml docker-compose.yaml.$(date +%s).bak

2. Get the latest code from the main branch

   git checkout main
   git pull origin main

3. Stop the service. Please execute in the docker directory

   docker compose down

4. Back up data

   tar -cvf volumes-$(date +%s).tgz volumes

5. Upgrade services

   docker compose up -d

Note

If you encounter errors like below

2025/11/26 11:37:57 /app/internal/db/pg/pg.go:30
[error] failed to initialize database, got error failed to connect to `host=db_postgres user=postgres database=dify_plugin`: hostname resolving error (lookup db_postgres on 127.0.0.11:53: server misbehaving)

2025/11/26 11:37:57 /app/internal/db/pg/pg.go:34
[error] failed to initialize database, got error failed to connect to `host=db_postgres user=postgres database=postgres`: hostname > resolving error (lookup db_postgres on 127.0.0.11:53: server misbehaving)
2025/11/26 11:37:57 init.go:99: [PANIC]failed to init dify plugin db: failed to connect to `host=db_postgres user=postgres database=postgres`: hostname resolving error (lookup db_postgres on 127.0.0.11:53: server misbehaving)
panic: [PANIC]failed to init dify plugin db: failed to connect to `host=db_postgres user=postgres database=postgres`: hostname resolving error (lookup db_postgres on 127.0.0.11:53: server misbehaving)

Please use the following command instead. For details, please read this #28706

docker compose --profile postgresql up -d

Source Code Deployments

1. Stop the API server, Worker, and Web frontend Server.

2. Get the latest code from the release branch:

   git checkout 1.13.0

3. Update Python dependencies:

   cd api
   uv sync

4. Then, let's run the migration script:

   uv run flask db upgrade

5. Finally, run the API server, Worker, and Web frontend Server again.

---

What's Changed

• refactor(api): replace reqparse with Pydantic models in trial.py by @Sean-Kenneth-Doherty in refactor(api): replace reqparse with Pydantic models in trial.py #31789
• refactor: plugin detail panel components for better maintainability and code organization. by @CodingOnStar in refactor: plugin detail panel components for better maintainability and code organization. #31870
• fix: remove api reference doc link en prefix by @hyoban in fix: remove api reference doc link en prefix #31910
• fix: missing import console_ns by @hjlarry in fix: missing import console_ns #31916
• fix: fix mcp server status is not right by @fatelei in fix: fix mcp server status is not right #31826
• test: try fix test, clear test log in CI by @hyoban in test: try fix test, clear test log in CI #31912
• fix: fix mcp output schema is union type frontend crash by @fatelei in fix: fix mcp output schema is union type frontend crash #31779
• fix: auto summary env by @zxhlyh in fix: auto summary env #31930
• refactor(datasets): extract hooks and components with comprehensive tests by @CodingOnStar in refactor(datasets): extract hooks and components with comprehensive tests #31707
• fix: include locale in appList query key for localization support inuseExploreAppList by @CodingOnStar in fix: include locale in appList query key for localization support inuseExploreAppList #31921
• chore: assign code owners for test directories by @laipz8200 in chore: assign code owners for test directories #31940
• refactor(web): extract complex components into modular structure with comprehensive tests by @CodingOnStar in refactor(web): extract complex components into modular structure with comprehensive tests #31729
• fix: fix delete_draft_variables_batch cycle forever by @fatelei in fix: fix delete_draft_variables_batch cycle forever #31934
• chore: bump version in docker-compose and package manager to 1.12.1 by @QuantumGhost in chore: bump version in docker-compose and package manager to 1.12.1 #31947
• chore: update CODEOWNERS to specify test file patterns for base components by @CodingOnStar in chore: update CODEOWNERS to specify test file patterns for base components #31941
• feat: use latest hash to sync draft by @fatelei in feat: use latest hash to sync draft #31924
• fix: remove staleTime/gcTime overrides from trigger query hooks and use orpc contract by @lyzno1 in fix: remove staleTime/gcTime overrides from trigger query hooks and use orpc contract #31863
• feat: account delete cleanup by @GareArc in feat: account delete cleanup #31519
• test: fix test by @hyoban in test: fix test #31975
• fix: fix miss use db.session by @fatelei in fix: fix miss use db.session #31971
• chore: sticky the applist header in explore page by @iamjoel in chore: sticky the applist header in explore page #31967
• fix(web): add rewrite rule to fix Serwist precaching 404 errors by @majiayu000 in fix(web): add rewrite rule to fix Serwist precaching 404 errors #31770
• fix: fix uuid_generate_v4 only used in postgresql by @fatelei in fix: fix uuid_generate_v4 only used in postgresql #31304
• chore: migrate to eslint-better-tailwind by @hyoban in chore: migrate to eslint-better-tailwind #31969
• feat: pre-cache all the plugin manifests before checking updates by @Stream29 in feat: pre-cache all the plugin manifests before checking updates #31942
• perf(api): Optimize the response time of AppListApi endpoint by @QuantumGhost in perf(api): Optimize the response time of AppListApi endpoint #31999
• chore: Remove redundant double space in variable type description (core/variables/variables.py) by @WH-2099 in chore: Remove redundant double space in variable type description (core/variables/variables.py) #32002
• refactor: strip external imports in workflow template transform by @WH-2099 in refactor: strip external imports in workflow template transform #32017
• chore: remove .codex/skills directory by @longway-code in chore: remove .codex/skills directory #32022
• fix: fix agent node tool type is not right by @fatelei in fix: fix agent node tool type is not right #32008
• fix: make flask upgrade-db fail on error by @longbingljw in fix: make flask upgrade-db fail on error #32024
• chore: update HITL auto deploy workflow by @QuantumGhost in chore: update HITL auto deploy workflow #32040
• fix: fix tool type is miss by @fatelei in fix: fix tool type is miss #32042
• perf: use batch delete method instead of single delete by @QuantumGhost in perf: use batch delete method instead of single delete #32036
• fix(api): return proper HTTP 204 status code in DELETE endpoints by @NeatGuyCoding in fix(api): return proper HTTP 204 status code in DELETE endpoints #32012
• test: only remove text coverage in CI by @hyoban in test: only remove text coverage in CI #32043
• chore: update deploy branches for deploy-hitl.yaml by @QuantumGhost in chore: update deploy branches for deploy-hitl.yaml #32051
• fix: redis for api token by @zyssyz123 in fix: redis for api token #31861
• fix: batch delete document db session block by @JohnJyong in fix: batch delete document db session block #32062
• fix: remove unexpected scrollbar in KB Retrieval settings by @crazywoola in fix: remove unexpected scrollbar in KB Retrieval settings #32082
• refactor: remove unnecessary type: async_workflow_service.py by @kongdayan in refactor: remove unnecessary type: async_workflow_service.py #32081
• refactor: partition Celery task sessions into smaller, discrete execu… by @fatelei in refactor: partition Celery task sessions into smaller, discrete execu… #32085
• feat: extract mcp tool usage by @fatelei in feat: extract mcp tool usage #31802
• fix: search model provider list by @zxhlyh in fix: search model provider list #32106
• refactor: document_indexing_update_task split database session by @fatelei in refactor: document_indexing_update_task split database session #32105
• test: stable test by @hyoban in test: stable test #32108
• refactor: decouple database operations from knowledge retrieval nodes by @fatelei in refactor: decouple database operations from knowledge retrieval nodes #31981
• feat: Service API - add end-user lookup endpoint by @BeautyyuYanli in feat: Service API - add end-user lookup endpoint #32015
• fix: pass user timezone from app context to the date picker component. by @ZeroZ-lab in fix: pass user timezone from app context to the date picker component. #31831
• fix: fix trigger output schema miss by @fatelei in fix: fix trigger output schema miss #32116
• feat: Human Input Node by @QuantumGhost in feat: Human Input Node #32060
• chore(api): update launch.json.template by @QuantumGhost in chore(api): update launch.json.template #32124
• style: update banner item styles and enhance dark/light theme variables by @Yessenia-d in style: update banner item styles and enhance dark/light theme variables #32111
• chore: fix type for useTranslation in #i18n by @hyoban in chore: fix type for useTranslation in #i18n #32134
• refactor: document_indexing_sync_task split db session by @fatelei in refactor: document_indexing_sync_task split db session #32129
• fix(api): register knowledge pipeline service API routes by @tokezooo in fix(api): register knowledge pipeline service API routes #32097
• fix(api): serialize pipeline file-upload created_at by @tokezooo in fix(api): serialize pipeline file-upload created_at #32098
• chore: detect utilities in css by @hyoban in chore: detect utilities in css #32143
• chore: introduce css icons by @hyoban in chore: introduce css icons #32004
• refactor(api): tighten OTel decorator typing by @shuv-amp in refactor(api): tighten OTel decorator typing #32163
• fix(api): clean up orphaned pending accounts on member removal by @eureka928 in fix(api): clean up orphaned pending accounts on member removal #32151
• fix: When the user is a non-sandbox user and has a paid balance, the … by @zyssyz123 in fix: When the user is a non-sandbox user and has a paid balance, the … #32173
• refactor: import component css in globals.css by @hyoban in refactor: import component css in globals.css #32180
• fix(api): include file marker for workflow tool file outputs by @OiPunk in fix(api): include file marker for workflow tool file outputs #32114
• fix(web): fill workflow tool output descriptions from schema by @OiPunk in fix(web): fill workflow tool output descriptions from schema #32117
• fix: replace sendBeacon with fetch keepalive for autosave on page close by @veeceey in fix: replace sendBeacon with fetch keepalive for autosave on page close #32088
• test: add comprehensive tests for Human Input Node functionality by @WTW0313 in test: add comprehensive tests for Human Input Node functionality #32191
• chore(api): update launch.json.example to include new workflow_based_app_execution. by @Nov1c444 in chore(api): update launch.json.example to include new workflow_based_app_execution. #32184
• refactor: extract sub-components and custom hooks from UpdateDSLModal and Metadata components by @CodingOnStar in refactor: extract sub-components and custom hooks from UpdateDSLModal and Metadata components #32045
• fix: fix no dify home directory lead permission error by @fatelei in fix: fix no dify home directory lead permission error #32169
• refactor: type safe env, update to zod v4 by @hyoban in refactor: type safe env, update to zod v4 #32035
• feat: enhancement celery configuration by @ruanimal in feat: enhancement celery configuration #32145
• fix(console): keep conversation updated_at unchanged when marking read by @OiPunk in fix(console): keep conversation updated_at unchanged when marking read #32133
• chore: allow draft run single node without connect to other node by @hjlarry in chore: allow draft run single node without connect to other node #31977
• chore(deps): bump axios from 1.13.2 to 1.13.5 in /sdks/nodejs-client by @dependabot[bot] in chore(deps): bump axios from 1.13.2 to 1.13.5 in /sdks/nodejs-client #32199
• fix: Fix the display of state icon of base node by @WTW0313 in fix: Fix the display of state icon of base node #32208
• chore(api): consume tasks in workflow_based_app_execution queue in start-worker script by @QuantumGhost in chore(api): consume tasks in workflow_based_app_execution queue in start-worker script #32214
• fix(api): excessive high CPU usage caused by RedisClientWrapper by @QuantumGhost in fix(api): excessive high CPU usage caused by RedisClientWrapper #32212
• fix: fix all tools is deleted by @fatelei in fix: fix all tools is deleted #32207
• fix: add unique constraint to tenant_default_models to prevent duplic… by @qiaofenlin in fix: add unique constraint to tenant_default_models to prevent duplic… #31221
• feat: support nl-NL language by @fatelei in feat: support nl-NL language #32216
• fix: fix get_message_event_type return wrong message type by @fatelei in fix: fix get_message_event_type return wrong message type #32019
• docs(api): mark SetupApi as unauthenticated by design by @41tair in docs(api): mark SetupApi as unauthenticated by design #32224
• feat(workflow): enhance workflow run history management and UI updates by @WTW0313 in feat(workflow): enhance workflow run history management and UI updates #32230
• chore(deps): bump cryptography from 46.0.3 to 46.0.5 in /api by @dependabot[bot] in chore(deps): bump cryptography from 46.0.3 to 46.0.5 in /api #32218
• chore(deps): bump google-api-python-client from 2.90.0 to 2.189.0 in /api by @dependabot[bot] in chore(deps): bump google-api-python-client from 2.90.0 to 2.189.0 in /api #32102
• feat(tests): add mock for useInvalidateWorkflowRunHistory in pipeline run tests by @WTW0313 in feat(tests): add mock for useInvalidateWorkflowRunHistory in pipeline run tests #32234
• fix: fix use fastopenapi lead user is anonymouse by @fatelei in fix: fix use fastopenapi lead user is anonymouse #32236
• fix: update index to optimize message clean performance by @hj24 in fix: update index to optimize message clean performance #32238
• fix: hide invite button if current user is not workspace manager by @douxc in fix: hide invite button if current user is not workspace manager #31744
• chore: bump version to 1.13.0 by @QuantumGhost in chore: bump version to 1.13.0 #32147

New Contributors

• @Sean-Kenneth-Doherty made their first contribution in refactor(api): replace reqparse with Pydantic models in trial.py #31789
• @WH-2099 made their first contribution in chore: Remove redundant double space in variable type description (core/variables/variables.py) #32002
• @longway-code made their first contribution in chore: remove .codex/skills directory #32022
• @kongdayan made their first contribution in refactor: remove unnecessary type: async_workflow_service.py #32081
• @tokezooo made their first contribution in fix(api): register knowledge pipeline service API routes #32097
• @shuv-amp made their first contribution in refactor(api): tighten OTel decorator typing #32163
• @OiPunk made their first contribution in fix(api): include file marker for workflow tool file outputs #32114
• @veeceey made their first contribution in fix: replace sendBeacon with fetch keepalive for autosave on page close #32088

Full Changelog: 1.12.1...1.13.0

---

This discussion was created from the release 1.13.0 - Human-in-the-Loop and Workflow Execution Upgrades.

[hmy11002]

weaviate always none

[amirreza-noori]

It's kind of funny — the feature is called Human-in-the-Loop, but users can't actually add a Human Input node inside the Loop node.

[veeceey]

Great release — the Human Input node is a meaningful addition that addresses a real gap in workflow design. The ability to pause execution at decision points and route based on human actions (approve/reject/escalate) makes workflows viable for use cases that previously required external orchestration or manual workarounds.

Architecture / Deployment:

• The move to Celery workers for streaming workflow executions is a significant change. For anyone running self-hosted with custom CELERY_QUEUES, the requirement to add workflow_based_app_execution is easy to miss — glad it's called out prominently. It would be helpful if the application logged a warning at startup when streaming workflow tasks are enqueued but no worker is consuming that queue.
• The PUBSUB_REDIS_CHANNEL_TYPE=sharded recommendation for high-throughput environments is solid advice. Worth noting for others: if you're already running Redis Cluster, switching to sharded PubSub avoids the broadcast overhead of standard PubSub across cluster nodes.

HITL Design:

• The 7-day default timeout (HUMAN_INPUT_GLOBAL_TIMEOUT_SECONDS=604800) seems reasonable for most approval workflows. For teams with strict SLA requirements, it would be useful to have per-node timeout configuration in addition to the global default — is that on the roadmap?
• Email delivery for human input forms is a strong choice for async review workflows. Are there plans to support webhook-based delivery (e.g., Slack, Teams) as additional channels?

Reliability fixes worth highlighting:

• The migration-time deduplication + unique constraint for tenant default models (fix: add unique constraint to tenant_default_models to prevent duplic… #31221) is the kind of defensive data integrity fix that prevents hard-to-debug issues down the line.
• The RedisClientWrapper CPU fix (fix(api): excessive high CPU usage caused by RedisClientWrapper #32212) is important for anyone who noticed elevated CPU after upgrading — worth checking if you're seeing unexplained load.

Solid work from the team and the new contributors. Looking forward to seeing how the HITL pattern evolves in future releases.