> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# New Agent

> Build an agent once, then put it to work as a standalone app or inside a workflow

<Warning>
  **Security Notice: Agent Environment Variable Exfiltration Risk**

  This 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.
</Warning>

<Note>
  The new Agent is in beta. It requires the agent-backend service and a sandbox environment in your cluster; see [Agent Sandbox Deployment](/en/3.12.x/deploy/advanced-configuration/agent-sandbox) to enable them.

  For production, replace `agentBackend.serverSecretKey` in your Helm values with your own random value.
</Note>

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](/en/3.12.x/use/build/agent):

* 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](/en/3.12.x/use/build/new-agent/build) it **once** and use it **two ways**: on its own as a chat app, or as [a step](/en/3.12.x/use/nodes/agent#new-agent) inside a workflow.

Create, configure, and manage your agents on the **Agents** page. Open one anytime to refine it or revisit an earlier version.

<Info>
  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](/en/3.12.x/use/workspace/permission-reference) for details.
</Info>

## 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.

<Warning>
  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.
</Warning>

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](/en/3.12.x/use/nodes/agent#new-agent) 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.