RiskeyL · Oct 26, 2026 · Oct 26, 2026
@@ -1226,8 +1226,8 @@ Traces of app runs are delivered to the configured LLMOps provider (Langfuse, La
 | Variable | Default | Description |
 |---|---|---|
 | `OPS_TRACE_UNIFIED_ENABLED` | `false` | Set to `true` to give LangSmith and Arize/Phoenix traces a common structure for workflow runs, nodes, and their parent-child relationships. The default `false` uses each provider's original tracing implementation. Other providers are unaffected.<br/><br/>Each app still needs LLMOps enabled and a provider configured. |
-| `OPS_AGENT_TRACE_ENABLED` | `false` | Set to `true` to include Agent model and tool calls in the traces of Agent apps and of Workflow and Chatflow apps with an Agent node. Agents inside a [workflow tool](/en/self-host/use-dify/workspace/tools#workflow) that the app calls aren't included. Also set `DIFY_AGENT_APPLICATION_TRACING_ENABLED` to `true`.<br/><br/>While this is `false`, the tracing settings of Agent, Workflow, and Chatflow apps say Agent tracing isn't available. Each app still needs tracing enabled, a provider configured, and **Capture Agent internals** on (the default). |
-| `DIFY_AGENT_APPLICATION_TRACING_ENABLED` | `false` | The agent backend's half of `OPS_AGENT_TRACE_ENABLED`; set both to `true` to trace Agents.<br/><br/>Set it in `docker/envs/core-services/dify-agent.env`, not `shared.env`: the agent backend doesn't read that file. |
+| `OPS_AGENT_TRACE_ENABLED` | `false` | Set to `true` to include Agent model and tool calls in the traces of Agent apps and of Workflow and Chatflow apps with a new Agent node. Agents inside a [workflow tool](/en/self-host/use-dify/workspace/tools#workflow) that the app calls aren't included. Also set `DIFY_AGENT_APPLICATION_TRACING_ENABLED` to `true`.<br/><br/>While this is `false`, the tracing settings of Agent, Workflow, and Chatflow apps say Agent tracing isn't available. Each app still needs tracing enabled, a provider configured, and **Capture Agent internals** on (the default). |
+| `DIFY_AGENT_APPLICATION_TRACING_ENABLED` | `false` | The agent backend's half of `OPS_AGENT_TRACE_ENABLED`; set both to `true` to trace Agents.<br/><br/>Set it in `docker/envs/core-services/dify-agent.env`, not `shared.env`: the agent backend doesn't read that file.<br/><br/>While it's on, an Agent run that its app traces goes to the app's tracing provider instead of [trajectory export](#agent-trajectory-export). |
 | `ENABLE_APPLICATION_TRACE_RECONCILE_TASK` | `true` | Used only when `OPS_AGENT_TRACE_ENABLED` is `true`. Runs a background job every 30 seconds that resends Agent traces still waiting for delivery and deletes the Agent trace data Dify stores after the retention period (7 days by default). Traces already delivered to your tracing provider stay there. |
 | `OPS_TRACE_RETRYABLE_DISPATCH_MAX_RETRIES` | `780` | How many times a trace delivery is retried after a transient failure before the trace is dropped. <br/><br/>The default retry window (retries × `OPS_TRACE_RETRYABLE_DISPATCH_DELAY_SECONDS`) is sized to outlast the one-hour workflow limit plus the export grace period. <br/><br/>Today only Arize/Phoenix tracing of nested workflows hits this path (a child trace arriving before its parent's context). Cannot be `0`. |
 | `OPS_TRACE_RETRYABLE_DISPATCH_DELAY_SECONDS` | `5` | Seconds between those retries; the total tolerance window is delay × max retries (about 65 minutes at defaults).<br/><br/>Lower delivers nested traces sooner but exhausts the retry budget faster. Cannot be `0`. |
@@ -1439,10 +1439,16 @@ Replaces the former `DIFY_AGENT_SHELLCTL_AUTH_TOKEN`, which still works as a leg
 
 Default: `true`
 
-Shows the new Agent in the web UI: the **Agents** item in the main navigation and the new Agent node in the workflow node picker. 
+Shows the new Agent in the web UI: the **Agents** item in the main navigation and the new Agent node in the node picker of Workflow apps.
 
 Set to `false` to hide it and fall back to the classic Agent node. Replaces `ENABLE_AGENT_V2`, which still works as a fallback.
 
+### NEXT_PUBLIC_ENABLE_AGENT_V2_IN_CHATFLOW
+
+Default: `false`
+
+Set to `true` to add the new Agent node to the node picker of Chatflow apps too. Works only while `NEXT_PUBLIC_ENABLE_AGENT_V2` is `true`.
+
 ### UPLOAD_SKILL_FILE_SIZE_LIMIT
 
 Default: `50`
@@ -1556,7 +1562,7 @@ Before switching to `openshell`, have these in place:
 - An OpenShell gateway, version 0.0.106 or later, reachable from the `agent_backend` container.
 - Gateway credentials: a bearer token, an mTLS client certificate pair, or both. Compose ships no certificate mount, so mount the files into `agent_backend` yourself, read-only and readable by UID 1001.
 - A runtime image that the gateway can start sandboxes from.
-- A shared volume for the persistent files agents keep across conversations, created outside Compose so that `docker compose down -v` can't delete it.
+- A shared volume for the persistent files agents keep across conversations, created outside Compose so that `docker compose down -v` can't delete it. If the deployment serves tenants that don't trust each other, give each its own OpenShell workspace and volume. A shared volume can't reliably keep one tenant out of another's persistent files.
 - A network path from the sandboxes back to Dify:
   - Callback addresses the sandboxes can reach.
   - A route to the agent backend's `/agent-stub` path. The base Compose file doesn't publish the agent backend's port 5050, and that port also serves the API that starts agent runs, so expose only `/agent-stub`, for example through a reverse proxy.
@@ -1582,7 +1588,7 @@ The bundled sandbox's egress proxy doesn't cover OpenShell sandboxes. To restric
 | `DIFY_AGENT_OPENSHELL_INSECURE` | `false` | Connects to the gateway over plaintext gRPC instead of TLS, without using the TLS paths. A bearer token, if set, is still sent over that connection.<br/><br/>Only for local development against a plaintext gateway. |
 | `DIFY_AGENT_OPENSHELL_WORKSPACE` | `default` | OpenShell workspace in which the agent backend creates and manages sandboxes. This is a namespace on the gateway, not a Dify workspace. |
 | `DIFY_AGENT_OPENSHELL_SANDBOX_IMAGE` | `docker.io/library/dify-agent-runtime:latest` | Container image the gateway starts for each sandbox. The default is the tag that the build command in the OpenShell setup guide produces.<br/><br/>The image must be available to the gateway's compute driver, not only to the Docker daemon running Dify: load it into the gateway's Docker daemon, or push it to a registry the gateway pulls from and use that reference.<br/><br/>Set it explicitly. If no env file sets it, the agent backend falls back to `langgenius/dify-agent-local-sandbox:latest`, which may be an older image that can't start under OpenShell. |
-| `DIFY_AGENT_OPENSHELL_DRIVER_CONFIG` | (empty) | Required for the `openshell` backend. JSON the gateway's compute driver applies to every sandbox; it must mount the shared volume at `DIFY_AGENT_OPENSHELL_SHARED_MOUNT_PATH`. Its shape depends on the driver.<br/><br/>Invalid JSON or an empty object stops the agent backend from starting. Dify doesn't check the mounts themselves, so the agent backend starts even if the volume is mounted at another path. Double-check the target.<br/><br/>Example for the Docker driver: `{"docker":{"mounts":[{"type":"volume","source":"dify-agent-shared","target":"/mnt/dify-agent-shared","read_only":false}]}}` |
+| `DIFY_AGENT_OPENSHELL_DRIVER_CONFIG` | (empty) | Required for the `openshell` backend. JSON the gateway's compute driver applies to every sandbox; it must mount the shared volume at `DIFY_AGENT_OPENSHELL_SHARED_MOUNT_PATH`. Its shape depends on the driver.<br/><br/>Invalid JSON or an empty object stops the agent backend from starting. Dify doesn't check the mounts themselves, so the agent backend starts even if the volume is mounted at another path. Double-check the target.<br/><br/>Example for the Docker driver (single-tenant, such as local development): `{"docker":{"mounts":[{"type":"volume","source":"dify-agent-shared","target":"/mnt/dify-agent-shared","read_only":false}]}}` |
 | `DIFY_AGENT_OPENSHELL_SHARED_MOUNT_PATH` | `/mnt/dify-agent-shared` | Where the shared volume is mounted inside each sandbox; must match the mount target in `DIFY_AGENT_OPENSHELL_DRIVER_CONFIG`. Agents' persistent files are saved here each time you click **Apply** in an Agent's build chat.<br/><br/>Must be an absolute path, or the agent backend won't start. |
 | `DIFY_AGENT_OPENSHELL_SHELLCTL_AUTH_TOKEN` | (empty) | Required for the `openshell` backend; the agent backend won't start without it. Shared secret that authenticates the agent backend to the command service it starts inside each sandbox. Set any random string.<br/><br/>Separate from `DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN`, which secures the bundled sandbox. |
 | `DIFY_AGENT_OPENSHELL_EGRESS_ALLOW` | (empty) | Comma-separated `host:port` endpoints that sandboxes may connect to, with no scheme or path. Empty sends no network policy, so egress follows the gateway's default.<br/><br/>When set, sandboxes reach only the listed endpoints, so package installs and web access stop working unless their hosts are listed. Include the hosts of `DIFY_AGENT_STUB_API_BASE_URL` and `DIFY_AGENT_SANDBOX_FILES_BASE_URL`, or agent runs can't call back into Dify.<br/><br/>A malformed entry stops the agent backend from starting.<br/><br/>Example: `agent.example.com:443,dify.example.com:443` |
@@ -1595,11 +1601,13 @@ The bundled sandbox's egress proxy doesn't cover OpenShell sandboxes. To restric
 
 ### Agent Trajectory Export
 
-To see what your agents did in a tracing backend you already run, turn on trajectory export. The agent backend then sends a trace of each agent run, with its model requests and tool calls, to an OpenTelemetry collector over OTLP/HTTP. One collector receives the runs of every workspace on the deployment.
+To see what your agents did in a tracing backend you already run, turn on trajectory export. The agent backend then sends traces of agent runs, with their model requests and tool calls, to an OpenTelemetry collector over OTLP/HTTP. One collector receives the runs of every workspace on the deployment.
 
 Every span carries the IDs of its workspace, app, agent, end user, conversation, workflow run, and node, so you can narrow traces to one app or one conversation by attributes such as `dify.app_id` or `dify.conversation.id`. These IDs are exported even with content export off.
 
-Trajectory export is separate from [LLMOps Trace Delivery](#llmops-trace-delivery), which app builders set up per app with providers such as Langfuse, and from the [OpenTelemetry instrumentation](#otlp-/-opentelemetry-configuration) of the API and Worker. Their settings don't affect it.
+Trajectory export is separate from the [OpenTelemetry instrumentation](#otlp-/-opentelemetry-configuration) of the API and Worker.
+
+It isn't separate from [LLMOps Trace Delivery](#llmops-trace-delivery), which app builders set up per app with providers such as Langfuse. With Agent tracing turned on there, a run that its app traces goes only to the app's tracing provider, and every other Agent run reaches the collector.
 
 To turn it on:
 

@@ -223,11 +223,11 @@ To share the agent across workspaces, click **Export Agent** from its menu. This
 
 <AccordionGroup>
   <Accordion title="Agents doesn't appear in the navigation or the node list">
-    The deployment's `.env` predates 1.16.0, so the Agents switch is missing or still off.
+    If only Chatflow apps lack the node, turn on [`NEXT_PUBLIC_ENABLE_AGENT_V2_IN_CHATFLOW`](/en/self-host/deploy/configuration/environments#next_public_enable_agent_v2_in_chatflow); it's off by default.
 
-    Sync it with `.env.example` (the switch is [`NEXT_PUBLIC_ENABLE_AGENT_V2`](/en/self-host/deploy/configuration/environments#next_public_enable_agent_v2)), then recreate the web container (`docker compose up -d web`) and hard-refresh the browser.
+    Otherwise, the deployment's `.env` predates 1.16.0, so the Agents switch is missing or still off.
 
-    In Chatflow apps the node's absence is expected: it's available in Workflow apps only.
+    Sync it with `.env.example` (the switch is [`NEXT_PUBLIC_ENABLE_AGENT_V2`](/en/self-host/deploy/configuration/environments#next_public_enable_agent_v2)), then recreate the web container (`docker compose up -d web`) and hard-refresh the browser.
 
     If other members see **Agents** but you don't, the cause is your workspace role: the entry needs the Editor role or above.
   </Accordion>

@@ -13,7 +13,7 @@ You can keep up to 500 skills in the library and share them workspace-wide. When
 Use skills in:
 
 - [Agent apps](/en/self-host/use-dify/build/new-agent/build#skills)
-- [New Agent nodes](/en/self-host/use-dify/nodes/agent#new-agent) in Workflow apps
+- [New Agent nodes](/en/self-host/use-dify/nodes/agent#new-agent) in Workflow and Chatflow apps
 
 <Info>
 Creating and managing skills requires the Editor role or above.

@@ -14,11 +14,9 @@ The dashboard tracks four metrics over time to show how your application perform
 **Average User Interactions**: Engagement depth per session  
 **Token Usage**: Resource consumption and costs
 
-Use the time selector to view trends over different periods. Click **"Tracing app performance"** to connect external observability platforms like Langfuse or LangSmith for deeper analytics.
+Use the time selector to view trends over different periods. Click **"Tracing app performance"** to connect external observability platforms like [Langfuse](/en/self-host/use-dify/monitor/integrations/integrate-langfuse) or [LangSmith](/en/self-host/use-dify/monitor/integrations/integrate-langsmith) for deeper analytics.
 
-For an Agent, open the same tracing settings from the Agent's **Monitoring** section.
-
-To see inputs and outputs in the traces of an Agent app or a workflow with an Agent node, turn on **Capture content** under **Agent data capture**. It covers every node in those traces, not only the Agent.
+For an [Agent](/en/self-host/use-dify/build/new-agent/overview), open the same tracing settings from the Agent's **Monitoring** section. They apply to the Agent's own runs, such as its chats, web app, and API calls. When the Agent runs inside a Workflow or Chatflow, that app's tracing settings apply instead.
 
 <Note>
 Agent tracing is off by default. Enable it by setting:
@@ -27,4 +25,11 @@ Agent tracing is off by default. Enable it by setting:
 - `DIFY_AGENT_APPLICATION_TRACING_ENABLED` = `true`
 
 See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) for details.
-</Note>
+</Note>
+
+In the tracing settings, **Agent data capture** sets what the traces include for Agent apps and for workflows with a [new Agent node](/en/self-host/use-dify/nodes/agent#new-agent):
+
+- **Capture Agent internals**: the Agent's model and tool calls. Turn it off to keep these steps out of your tracing provider; the trace then shows the Agent as a single step.
+- **Capture content**: the inputs and outputs of every step in the trace, not only the Agent's. Turning it on sends prompts, user messages, and replies to your tracing provider.
+
+In other workflows, including those with only a classic Agent node, these switches have no effect.
@@ -128,7 +128,7 @@ description: Run an agent as a step in your workflow, reasoning and using tools
   </Warning>
 
   <Note>
-  The new Agent node is in beta and available in Workflow apps only. It's on by default on Docker Compose, with its runtime bundled in.
+  The new Agent node is in beta. It's on by default on Docker Compose, with its runtime bundled in. In Chatflow apps, it's available once you turn on [`NEXT_PUBLIC_ENABLE_AGENT_V2_IN_CHATFLOW`](/en/self-host/deploy/configuration/environments#next_public_enable_agent_v2_in_chatflow).
 
   For production, replace [`DIFY_AGENT_SERVER_SECRET_KEY`](/en/self-host/deploy/configuration/environments#dify_agent_server_secret_key) and [`DIFY_AGENT_API_TOKEN`](/en/self-host/deploy/configuration/environments#dify_agent_api_token) with your own random values.
   </Note>
@@ -230,5 +230,13 @@ description: Run an agent as a step in your workflow, reasoning and using tools
 
   The node fails if the model's answer has no route or names one that doesn't exist. To keep the workflow running instead of stopping there, set **Error Handling** to **Fail Branch** and connect that branch to a fallback.
 
+  <a id="in-a-chatflow"></a>
+
+  ## In a Chatflow
+
+  Each turn picks up where the last one left off, so the agent can build on what the user already said. Two Agent nodes in the same Chatflow remember separately.
+
+  When you update the agent, in **Agents** or on the node, conversations already in progress keep the setup they started with. Start a new conversation to try the change.
+
   </Tab>
 </Tabs>