Skip to main content
Security Notice: Agent Environment Variable Exfiltration RiskThis notice applies to Dify Enterprise 3.12.x when agents are configured with environment variables and network access.The agent runtime in Dify Enterprise 3.12.x applies pattern-based masking to reduce the likelihood that sensitive environment variable values appear in plaintext in user-visible responses or tool execution outputs. However, this mechanism alone may not reliably prevent an agent that can access such values and the network from encoding (e.g., Base64, hexadecimal, character splitting, or other obfuscation techniques) those values before transmitting them to network endpoints accessible to the runtime.Operators are responsible for configuring Agent permissions and access in a manner appropriate to the sensitivity of their systems, data, and credentials. We strongly recommend:
  • Avoiding injection of long-lived credentials into the agent environment.
  • Using short-lived, least-privilege tokens where possible.
  • Restricting network egress to the minimum required destinations.
This is an inherent limitation of pattern-based redaction when used by itself.
The new Agent is in beta. It requires the agent-backend service and a sandbox environment in your cluster; see Agent Sandbox Deployment to enable them.For production, replace agentBackend.serverSecretKey in your Helm values with your own random value.
An Agent is an AI worker you set up once and then put to work. It’s a different kind of agent than the classic Agent app:
  • It works in a sandbox of its own: it runs commands, installs programs, and reads and writes files, so it takes on open-ended work rather than just calling the tools you configured.
  • You build it once and use it two ways: on its own as a chat app, or as a step inside a workflow.
Create, configure, and manage your agents on the Agents page. Open one anytime to refine it or revisit an earlier version.
The Agents page appears only for members with the Manage Agents permission; the Owner, Admin, and Editor roles have it by default. See Permission Reference for details.

​
Capability and Task

An Agent separates what it is from what you ask it to do:
  • Its capability (think of it as the agent’s soul) is who the agent is. The role and prompt you write, the model it runs on, and the knowledge, skills, Dify tools, and files you give it. You shape it once and keep refining it as you learn what the agent needs.
  • Its task is what you ask it to do on a given run. When the agent works on its own, the task is the message you send it. When it works inside a workflow, the task is the instruction you give the node.
It’s the same split as hiring someone: you choose a person for what they can do, then give them a specific task. Strong results need both: the right person for the job and a clear brief.

​
Two Ways to Use an Agent

​
On Its Own

The agent runs as its own chat app. You give it tasks by chatting, and you can publish it as a web app or call it through the service API.
Session isolation depends on how your cluster runs sandboxes. On a standard deployment with the sandbox gateway, each agent session gets its own sandbox pod with per-session filesystem isolation.With the shared-sandbox fallback, all sessions share one sandbox container. Isolation between end users is weaker, so be cautious about exposing the agent to end users who need isolation from each other.
Each conversation has its own memory: how much the agent keeps in mind depends on the model’s context window, and a new conversation starts fresh. Choose this when a single capable worker can reach the goal on its own: a support assistant that looks things up and answers, or a research agent that gathers sources and summarizes them.

​
Inside a Workflow

You invite the agent into an Agent node to handle one step of a larger process. There you set only the task you want done. It’s like asking a colleague to take care of one thing: you describe the task, and they bring their own skills to it. Choose this when the work needs structure around it: several steps in a set order, branching on conditions, other kinds of nodes, or a few specialized agents handing off to each other. However the agent runs, its sessions collect in one place: the Logs page, where each row carries its source (the agent’s web app or a workflow that uses it).