Traceary

Catalog / Dify

1.16.0

v1.16.0

1 month agosecurityaddedfixedOriginal notes

Introducing Dify Agent (Beta): A New Agent Experience in Dify

[!WARNING] You should provide Dify Agent services ⚠️only to trusted, non-malicious users⚠️.

As many of you know, the shell-based LLM agent paradigm has brought a major leap in agent capabilities and changed how we think about agents. Meanwhile, Skills provide a standardized way to package and distribute capabilities, making it easier to build powerful agents.

Today, we are launching Dify Agent. Like other leading agents, it runs in a Linux sandbox. This release includes:

  • A builder for creating Dify Agents

    • You can build Dify Agents through the UI: set a base prompt, upload Skills and files, and connect tools and knowledge from the Dify ecosystem.
    • We also provide an agent that helps you build Dify Agents. Through conversation, it can configure the Linux sandbox environment, install required packages, and create new Skills and files that your Dify Agent can use later.

  • Dify Workflow integration for Dify Agent

    • You can use an existing Dify Agent in a Dify Workflow, or temporarily create an inline Dify Agent. It will execute the task defined by the workflow node, generate the required output, and pass it to the next node.

  • A new web app experience

    • The Dify Agent you build can be published and used as a web app. While the user experience remains familiar, it is now powered by Dify Agent.

Docs: https://docs.dify.ai/en/self-host/use-dify/build/new-agent/overview

⚠️ Action Required

OpenAI GPT-5.6 Compatibility Notice

The OpenAI plugin previously defaulted to using the Chat Completions API, which was deprecated by OpenAI earlier this year and has increasingly poor support for newer model series. The newly released GPT-5.6 family has many unusual and unique parameter combination restrictions when used with Chat Completions, because OpenAI now provides only minimal compatibility support for Chat Completions with new models. This is not a Dify system issue.

The default API type for new configurations has been changed from Chat Completions to Responses. However, users who previously saved a custom API key with the old default (Chat Completions) will retain that setting, which may cause unexpected errors that appear to originate from Dify.

If you have previously configured a custom OpenAI API key, please check your API type setting and switch to Responses if it is still set to Chat Completions, especially when using GPT-5.6 or later models.

New Features

Agent App (Open Beta)

  • Agent App enters open beta and is now enabled by default for all users. It introduces a built-in sandbox for code execution and shell commands, a skill system that lets agents call tools and APIs, an agent roster for managing and reusing agents across a workspace, and support for referencing new agents from workflow agent nodes.

Smarter AI Workflow Generation

  • The ⌘K → /create and /refine AI workflow generator has been enhanced end-to-end: the low-value "Ideal output" field was removed, static example chips replaced with AI-generated suggestions grounded in your workspace context, and node config generation is now parallelized for faster results. A configurable timeout (WORKFLOW_GENERATION_TIMEOUT_MS, default 180s) prevents long-running generations from hanging.

MCP Protocol Upgrade

  • The workflow-as-MCP server now supports MCP protocol 2025-06-18 with version negotiation and structured tool output, while remaining backward compatible with older clients. MCPClient connections can now inject dynamic HTTP request headers at runtime using placeholders (e.g. {{request.headers.X-Custom-Auth}}), enabling per-request authentication passthrough.

Web App Customization

  • App owners can now customize the chat input placeholder text (up to 64 chars) for Chatbot, Agent, and Chatflow web apps. The customization UI has been refined with clearer naming ("Custom Frontend" / "Branding") and better label handling. App descriptions are now displayed on chat and text-generation app screens with a collapsible view to avoid pushing the input form off screen.

Workflow Reliability & Operations

  • Workflow run archives can now be exported, and active runs are properly aborted during Celery warm shutdown to prevent orphaned tasks. Redis connections are more resilient with TCP keepalive support and expanded retry coverage. Model providers now receive app_id for provider-side cost attribution (e.g. Bedrock requestMetadata, OpenAI metadata, Vertex AI labels). OAuth and SSO login flows now preserve redirect URLs more reliably, with a dedicated error view for failed SSO completions.

Bug Fixes

Workflow & Agent

  • Fixed multiple issues with workflow draft imports losing references, node settlement after failures, retry detail visibility, and HITL resume state restoration
  • Fixed SSE stream corruption with Unicode separators, agent final answer clearing after stream completion, and conversation title being overwritten with empty values
  • Fixed workflow archive retry hardening, multi-worker collaboration support, and chat tree out-of-order parent nodes
  • Fixed knowledge retrieval failures not being surfaced to users, and End output variable name collisions in built-in templates

Authentication & Access Control

  • Fixed open redirect vulnerabilities in post-login and auth redirect flows
  • Fixed login redirects not staying on current deployment, auth prefix duplication, and change email not working
  • Fixed editor permission issues: editors can now view logs, no longer query billing subscriptions, and can no longer manage members
  • Fixed trace config changes not requiring edit access, and trial app access hardening for recommended apps

Models & Plugins

  • Fixed custom model cache not being cleared on deletion, model plugin debugging failures, and Xinference credential context handling
  • Fixed max token params not being disableable in follow-up model parameters
  • Fixed plugin provider cache stampedes, marketplace installation callbacks, and plugin permission settings

Web & UI

  • Fixed app creation from Learn Dify, node search field input, workspace avatar consistency, and navigation profile display
  • Fixed Streamdown fullscreen table actions, marketplace page header jitter, and install dialog accessibility
  • Fixed chat attachments scrolling out of view, HITL input save button visibility, and app card meta overflow
  • Fixed monitoring chart zero-value display, member invitation state handling, dark mode background, and Unicode characters in form field names
  • Fixed markdown file-preview link downloads, Notion sync empty state, and blog UTM attribution under CSP

Other

  • Fixed infinite loop in batch document deletion, invalid UTF-8 cache payloads, and swallowed document indexing errors
  • Fixed PostgreSQL 18 native uuidv7() support and ADB-PG 7.0 compatibility
  • Fixed CAN_REPLACE_LOGO defaulting to true, unsupported language errors in execute_code, and CLI --insecure flag not skipping TLS verification

Improvements

Performance

  • Eliminated N+1 queries in advanced-chat workflow run lists and TokenBufferMemory message file loading
  • Faster frontend startup via lazy-loaded Vite plugins and console contract shards
  • Reduced database load by caching setup status, compressing large plugin model objects in Redis with zstd, and retrieving published workflows via direct foreign key

Architecture & Code Quality

  • Migrated all console API endpoints to generated OpenAPI contracts with BaseModel, and frontend console contracts to generated routes and types
  • Propagated explicit database sessions across backend paths for consistency and testability
  • Replaced legacy app context providers with Jotai atoms across the frontend
  • Upgraded to TypeScript 7 and Vite+ toolchain, enforced strict ESLint rules, and disallowed new direct SQLAlchemy in controllers

Security Enhancements

This release includes several security hardening fixes, some of which were addressed after the 1.16.0-rc1 release:

  • SQL injection: Closed a SQL injection vulnerability and enhanced SQL query safety with metadata key validation
  • SSRF: Fixed an SSRF bypass via raw httpx.get in API tool schema fetch
  • Open redirects: Prevented open redirects in post-login and auth redirect flows
  • Sandbox enforcement: Chatflow API now checks workflow_id and sandbox plan; sandbox plan will not execute special workflows
  • Landlock protection: Agent HOME directory protected with Landlock; downgraded to v1 for broader kernel compatibility
  • CVE dependency upgrades: httplib2, setuptools, wandb; python-engineio, python-socketio; fickling, pillow, click

Environment Variable Changes

Added

Variable Default File Description
AGENT_BACKEND_BASE_URL http://localhost:5050 api/.env.example Base URL for the Agent backend service
AGENT_BACKEND_STREAM_READ_TIMEOUT_SECONDS 30 api/.env.example Stream read timeout for Agent backend
AGENT_BACKEND_STREAM_MAX_RECONNECTS 3 api/.env.example Max reconnection attempts for Agent backend streams
AGENT_BACKEND_RUN_TIMEOUT_SECONDS 1200 api/.env.example Overall run timeout for Agent backend
API_WEBSOCKET_WORKER_AMOUNT 1 docker/envs/core-services/shared.env.example Number of WebSocket API workers
DIFY_AGENT_REDIS_URL (empty, derived from REDIS_PASSWORD) docker/envs/core-services/dify-agent.env.example Redis URL for Dify Agent
DIFY_AGENT_REDIS_PREFIX dify-agent docker/envs/core-services/dify-agent.env.example Redis key prefix for Dify Agent
DIFY_AGENT_SHUTDOWN_GRACE_SECONDS 30 docker/envs/core-services/dify-agent.env.example Grace period before forced shutdown
DIFY_AGENT_RUN_RETENTION_SECONDS 259200 docker/envs/core-services/dify-agent.env.example Retention period for agent run records
DIFY_AGENT_PLUGIN_DAEMON_URL (empty, derived from PLUGIN_DAEMON_URL) docker/envs/core-services/dify-agent.env.example Plugin daemon URL for Dify Agent
DIFY_AGENT_PLUGIN_DAEMON_API_KEY (empty, derived from PLUGIN_DAEMON_KEY) docker/envs/core-services/dify-agent.env.example Plugin daemon API key for Dify Agent
DIFY_AGENT_INNER_API_URL (empty, derived from PLUGIN_DIFY_INNER_API_URL) docker/envs/core-services/dify-agent.env.example Inner API URL for Dify Agent
DIFY_AGENT_INNER_API_KEY (empty) docker/envs/core-services/dify-agent.env.example Inner API key (must match INNER_API_KEY_FOR_PLUGIN, not INNER_API_KEY)
DIFY_AGENT_SHELLCTL_ENTRYPOINT http://local_sandbox:5004 docker/envs/core-services/dify-agent.env.example Shellctl entrypoint URL
DIFY_AGENT_SHELLCTL_AUTH_TOKEN (empty) docker/envs/core-services/dify-agent.env.example Auth token for shellctl
DIFY_AGENT_STUB_API_BASE_URL http://agent_backend:5050/agent-stub docker/envs/core-services/dify-agent.env.example Base URL for Agent Stub API
DIFY_AGENT_SERVER_SECRET_KEY (dev default) docker/envs/core-services/dify-agent.env.example JWE encryption key for Agent Stub bearer tokens. Replace in production with python -c 'import secrets; print(secrets.token_urlsafe(32))'
DIFY_AGENT_SHELL_REDACT_PATTERNS (empty) docker/envs/core-services/dify-agent.env.example Patterns for redacting shell output
SHELLCTL_ENABLE_PATH_ISOLATION true docker/envs/core-services/local-sandbox.env.example Enable path isolation in shellctl
NEW_USER_DEFAULT_PLUGIN_IDS (empty) api/.env.example Comma-separated plugin IDs to auto-install for new users
NEW_USER_DEFAULT_MODELS (empty) api/.env.example Default models for new users
WORKFLOW_GENERATION_TIMEOUT_MS 180000 docker/envs/core-services/shared.env.example Timeout for AI workflow generation
WORKFLOW_GENERATOR_NODE_BUILDER_MAX_WORKERS 6 api/.env.example Max parallel workers for node config generation
REDIS_KEEPALIVE true api/.env.example Enable Redis TCP keepalive
REDIS_KEEPALIVE_IDLE 30 api/.env.example Redis keepalive idle time (seconds)
REDIS_KEEPALIVE_INTERVAL 10 api/.env.example Redis keepalive interval (seconds)
REDIS_KEEPALIVE_COUNT 10 api/.env.example Redis keepalive probe count
NEXT_PUBLIC_ENABLE_AGENT_V2 true docker/envs/core-services/web.env.example Enable Agent App v2 (replaces ENABLE_AGENT_V2)

Removed

Variable Old Default File Notes
ENABLE_AGENT_V2 false docker/envs/core-services/web.env.example Replaced by NEXT_PUBLIC_ENABLE_AGENT_V2 (now defaults to true)

Modified

Variable Old New File
NEXT_PUBLIC_ENABLE_FEATURE_PREVIEW false true docker/envs/core-services/web.env.example

Docker Compose Changes

  • New services: agent_backend (langgenius/dify-agent-backend:1.16.0) and local_sandbox (langgenius/dify-agent-local-sandbox:1.16.0)
  • api and worker services now depend on agent_backend
  • API_WEBSOCKET_WORKER_AMOUNT is now configurable (was hardcoded to 1)
  • WORKFLOW_GENERATION_TIMEOUT_MS added to web service

Database Migrations

This release includes 9 new database migrations:

  • 2026_05_25_1143-97e2e1a644e8_add_workflow_version_to_workflow_agent_.py
  • 2026_06_12_1100-0b2f2c8a9d1e_add_agent_role.py
  • 2026_06_18_2300-b2515f9d4c2a_agent_drive_skill_metadata_refactor.py
  • 2026_06_24_1900-a6f1c9d2e8b4_add_input_placeholder_to_sites.py
  • 2026_06_24_2015-e4f5a6b7c8d9_add_agent_config_drafts.py
  • 2026_06_25_1100-a2b3c4d5e6f7_add_agent_backing_app_id.py
  • 2026_06_25_1500-7a1c2d9e4b60_add_workflow_run_archive_index_tables.py
  • 2026_06_26_1000-c3d4e5f6a7b8_add_agent_active_config_is_published.py

Run flask db upgrade after updating the code.

Upgrade Guide

[!IMPORTANT]

  • This release includes 8 new database migrations. Run database migrations as part of the upgrade.
  • 28 new environment variables, 1 removed, and 1 modified. Review the Environment Variable Changes section and update your .env accordingly.
  • Docker Compose configuration changed significantly: two new services (agent_backend, local_sandbox) were added. If you maintain a customized docker-compose.yaml, review the changes and re-apply local customizations carefully.
  • DIFY_AGENT_SERVER_SECRET_KEY ships with a development default. You must replace it in production with a securely generated key: python -c 'import secrets; print(secrets.token_urlsafe(32))'
  • ENABLE_AGENT_V2 has been renamed to NEXT_PUBLIC_ENABLE_AGENT_V2 and now defaults to true. Remove the old variable from your env files.
  • OpenAI GPT-5.6 users: If you have previously configured a custom OpenAI API key, verify your API type is set to Responses (not Chat Completions). See the Known Issues section above.

Docker Compose Deployments

  1. Back up your customized docker-compose YAML and env files.

    cd docker
cp docker-compose.yaml docker-compose.yaml.$(date +%s).bak
cp .env .env.$(date +%s).bak 2>/dev/null || true

  2. Get the latest code from the release branch or tag.

    git fetch --tags
git checkout 1.16.0

  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. Review the new environment variables (especially DIFY_AGENT_SERVER_SECRET_KEY) and update your .env file. Re-apply any local customizations.

  6. Upgrade services.

    docker compose up -d

Source Code Deployments

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

  2. Get the latest code from the release tag.

    git fetch --tags
git checkout 1.16.0

  3. Update Python dependencies.

    cd api
uv sync

  4. Run the migration script.

    uv run flask db upgrade

  5. Configure the new Agent backend service. Refer to the dify-agent section in docker/envs/core-services/dify-agent.env.example for required environment variables.

  6. Restart the API server, Worker, and Web frontend Server.

What's Changed

These notes run past the length kept in the archive. The rest is on the publisher’s page.