Skip to main content
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.

​
Create an Agent

From Agents, click Create > Create from Blank and give the agent a name; optionally add a role such as Research Assistant and a description. Then you shape everything else in Configure. To create an agent from a shared DSL file, choose Import DSL file. Library skills reattach automatically when your workspace has skills with the same names; embedded skills and files aren’t included, so add them after importing.
Create requires the Create agents permission, and Import DSL file requires Import and export agent DSL.The Owner, Admins, and Editors hold both by default; other members can hold them through a custom role.

​
Configure Its Capabilities

Set up each capability by hand, or describe what you want and build it by chatting in Build mode. Everything you set up in Configure is saved as the agent’s capabilities and used in every task later. Separately, the agent works inside its own sandbox, where it runs commands and handles files as it goes. The agent’s capabilities can only be changed here: even if an end user asks a published agent to change its own prompt, skills, or tools, it won’t.

​
Model

Pick the chat model the agent runs on. Favor models that are strong at reasoning and natively support tool calling, since the agent has to judge when to act, which tool fits, and how to read the result.
Agent performance rises and falls with the model, so pick a recent one.Older models often can’t make full use of the sandbox: a common symptom is an agent that never runs commands or installs tools, even when the task needs it.

​
Prompt

In the prompt, set the agent’s role and how it should approach its work. Be specific about how it should reason, when to lean on its tools, and what to avoid. A few things worth covering:
  • Persona and goal: who the agent acts as and what it’s trying to achieve.
  • Approach: the steps or order you expect for a typical task.
  • Tool and file use: when to reach for each, named explicitly.
  • Output: the format, length, or tone you want back.
You can point the agent at a specific skill, file, or tool, or leave the choice to the agent:
  • Reference it in the prompt with / to send the agent straight to it, right where you want it used. Best when a step depends on a specific one.
  • Just add it to its section and let the agent decide on its own when to use it. Best when you’d rather trust the agent’s judgment than script every move.

​
Skills

A skill is a procedure the agent follows for one specific task. Unlike the prompt, which sets the agent’s overall role, a skill covers just that task. For example, a support agent’s prompt might set its role as a customer helper that handles any issue, while its refund-requests skill covers only refunds: look up the order, refund only within 30 days, and end with a help-center link. Click Add and choose which kind of skill to add:
  • Choose Add from library to add a library skill shared workspace-wide. You can add up to 20 library skills to an agent, and it follows the latest published version of each.
  • Choose Upload skill.zip to add a .zip or .skill package as an embedded skill, one the agent keeps to itself. The package needs a SKILL.md inside and can be up to 50 MB by default, adjustable with UPLOAD_SKILL_FILE_SIZE_LIMIT. To share an embedded skill with other agents, make it a library skill.
You can also have the agent create embedded skills for you in Build mode.
To make a Dify tool or file part of the agent’s own capabilities, add it to the agent directly rather than inside a skill package.

​
Files

Files are reference documents the agent can read while it works, like specs, templates, or guidelines. Unlike a skill, a file is just material to read, not a procedure to run. Size limits depend on file type; each is a default you can adjust with environment variables: You can also have the agent create files and save them here in Build mode.
Files the agent creates and saves are capped at 50 MB each by default, adjustable with DIFY_AGENT_STUB_UPLOAD_FILE_SIZE_LIMIT. See Environment Variables for details.

​
Tools

Give the agent Dify tools so it can act beyond the chat: plugins, custom APIs, workflows, and MCP servers from your workspace. Some tools need authentication before use.
Beyond the Dify tools you add here, the agent can also install and run command-line tools on its own inside the sandbox when it needs one. Those tools don’t appear in the Tools list.Tools the agent installs in Build mode can stay available after publishing, while anything installed during a published run is temporary.

​
Environment Variables

Security Notice: Agent Environment Variable Exfiltration RiskThis notice applies to Dify Enterprise 3.13.x when agents are configured with environment variables and network access.The agent runtime in Dify Enterprise 3.13.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.
Under Advanced Settings, you can add environment variables: key-value pairs the agent can read in its sandbox while it works. Say your agent’s skills all work with the same order system: one checks stock, one files orders, one pulls reports. Store the system’s address here as ORDER_API_URL, and every script reads it by name. To switch from the test system to the production one, update this one value, and all of them follow. Import a .env file to add several at once. You can also have the agent set them up in Build mode.
Values stored here can surface in command output the agent reads. To mask sensitive strings from it, set DIFY_AGENT_SHELL_REDACT_PATTERNS. See Environment Variables for details.

​
Build by Chatting

Instead of setting everything up by hand, you can build the agent by describing what it should do, and as you chat it sets up skills, files, and environment variables itself. For example, your first message might be:
You’re talking to the live agent: test it as you build, watch how it behaves, and refine it in the same build chat. As the agent works, it edits the configuration in the panel directly, and you can see all changes listed in Build draft. Click Apply to keep them, or Discard to drop. Either one exits Build mode and clears the conversation.
Discard drops everything from this build chat: any changes to the configuration and persistent files in the File system.
While you’re in Build mode, the configuration panel is read-only—just tell the agent what you want to change.

​
File System

In Build mode, the agent handles real files in its sandbox: artifacts it generates, programs it installs on its own, and everything else it’s working with. During a build chat, click File system in the top-right corner to browse them. Since a build chat is where you shape the agent itself, whatever it adds (a template it drafted, a tool it installed) is Persistent by default, kept for every future conversation and workflow run. In effect, these files are part of the agent’s setup, like its prompt and skills. For one-off work, like a test file or a converter it only needs once, tell the agent in the chat, e.g. “keep this file temporary”: it goes under Temporary and is cleared when this build chat ends. In published runs, whatever the agent adds is always temporary, so nothing that happens in a run changes the agent itself.

​
The Build Note

In build chats, the agent records what it set up in a build note, a build_note.md that appears in Files the first time you Apply. The note is saved with the agent’s setup, and it reads the note back at the start of every new conversation, combining it with your Prompt to form its instructions. After you apply, open the build note and read what the agent captured:
  • If it covers what you want, you’re set.
  • To change what it says, have the agent revise it in Build mode.
    The agent maintains only the auto-generated build note: a downloaded copy you re-upload is just an ordinary file, and the next build chat creates a fresh note alongside it.
  • If anything’s missing, add it to the Prompt.
  • To start over with a clean record, delete the note in Files.
Across build chats, the note also serves as the agent’s memory. If you shaped the meeting-minutes agent in one chat, a later chat to add action-item owners starts from the format and decisions you already settled, not from scratch.

​
Preview

Switch the right panel from Build to Preview to try the agent exactly as end users will experience it once published: clean replies and your Chat Features active. Chatting in Preview never changes the agent’s configuration, so use it as the final check before you publish.

​
Publish

Your edits autosave as a draft. When the agent is ready, publish it to make that version live. Open the version history anytime to revisit or restore an earlier version.
Restoring a version also restores the persistent files in the agent’s sandbox to that version.
To polish the chat experience, you can add extras like a welcome message, suggested questions, and voice in Chat Features. See App Toolkit for details.
From the Access Point tab, host it as a web app at a shareable link, embed it in your site, or call it from your code through the service API. You can also set who can reach the web app with Web App Access Control.
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.
You can also invite the agent into a workflow’s Agent node to handle a step. To share the agent across workspaces, export it as a DSL file. Library skills reattach by name when the target workspace has them; embedded skills and files aren’t included, so share them alongside.

​
Run Limits

  • Time A single agent run is stopped after 1 hour by default, whichever access point it starts from (web app, service API, or a workflow), and the unfinished reply is discarded. If a run gets cut off, try again or break the task into smaller steps. For longer runs, raise APP_MAX_EXECUTION_TIME, WORKFLOW_MAX_EXECUTION_TIME, and DIFY_AGENT_RUN_TIMEOUT_SECONDS above the duration you need. See Environment Variables for details on these variables.
  • Model requests Every call the agent makes to its model counts toward a cap of 500 per run, so heavy reasoning and frequent tool use spend it faster. Try breaking the task into smaller steps to keep each run within the cap.
  • Reply files Each file the agent sends back in a reply can be up to 50 MB by default, and larger files aren’t delivered. If your agent produces bigger artifacts, raise DIFY_AGENT_STUB_UPLOAD_FILE_SIZE_LIMIT. See Environment Variables for details.

​
Troubleshooting

If other members see an agent that you don’t, you aren’t on its allowed members list. Ask whoever manages the agent to add you in the agent’s Resource Access section.If you can open the agent but not edit it, ask them to switch your Access permission on it to a permission set that includes Edit agent information and configuration, such as the built-in Edit Content. The set replaces your role’s permissions on this agent alone.
In Chatflow apps the node’s absence is expected: it’s available in Workflow apps only.
If every run errors immediately, the cluster may be missing the agent’s services: the agent-backend service or a sandbox runtime.See Agent Sandbox Deployment for the required components and how to check them.
Models served through OpenAI-compatible endpoints (vLLM and similar) often lack full native tool-calling support, which the agent depends on in build chats as well as published runs.Pick a model that supports tool calling natively. If a compatible model still errors, check Token parameter name in the model’s settings on the provider: some newer models require max_completion_tokens, and auto-detection can guess wrong.Some OpenAI models reject tool calls when reasoning is enabled over the Chat Completions protocol. For those, set the provider credential’s API Protocol to Responses API.
Image upload can be turned on in Chat Features regardless of whether the agent’s model supports vision. With a non-vision model, the agent may error on an image or reply as if none was sent.Switch to a model that supports vision: look for the Vision tag when picking the model.
The sandbox’s internet access goes through a proxy that blocks private-network addresses by default. Public URLs work; for material on your intranet, add it to the agent’s Files instead.