> ## 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. # Build an Agent > Create an agent and shape what it can do, by hand or by describing what you want 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.13.x/deploy/advanced-configuration/agent-sandbox) 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](/en/3.13.x/use/build/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](/en/3.13.x/use/workspace/roles-and-permissions#custom-roles). ## Configure Its Capabilities Set up each capability by hand, or describe what you want and build it by chatting in [Build mode](#build-by-chatting). 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*](/en/3.13.x/use/build/skills) 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`](/en/3.13.x/deploy/advanced-configuration/environment-variables#upload_skill_file_size_limit). To share an embedded skill with other agents, [make it a library skill](/en/3.13.x/use/build/skills#import-a-skill). You can also have the agent create embedded skills for you in [Build mode](#build-by-chatting). 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](/en/3.13.x/deploy/advanced-configuration/environment-variables): | File type | Default limit | Environment variable | | :- | :- | :- | | Documents | 15 MB | `UPLOAD_FILE_SIZE_LIMIT` | | Images | 10 MB | `UPLOAD_IMAGE_FILE_SIZE_LIMIT` | | Video | 100 MB | `UPLOAD_VIDEO_FILE_SIZE_LIMIT` | | Audio | 50 MB | `UPLOAD_AUDIO_FILE_SIZE_LIMIT` | You can also have the agent create files and save them here in [Build mode](#build-by-chatting). 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](/en/3.13.x/deploy/advanced-configuration/environment-variables#agent-backend-configuration) for details.

Tools

Give the agent [Dify tools](/en/3.13.x/use/workspace/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](#build-by-chatting) can stay available after publishing, while anything installed during a published run is temporary.

Environment Variables

**Security Notice: Agent Environment Variable Exfiltration Risk** This 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](#build-by-chatting). 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](/en/3.13.x/deploy/advanced-configuration/environment-variables#agent-backend-configuration) 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: ```text wrap theme={null} Build an agent that turns raw meeting notes into structured minutes: attendees, decisions, and action items. ``` 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**](#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](/en/3.13.x/use/build/additional-features) 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](/en/3.13.x/develop/api/guides/agent). You can also set who can reach the web app with [Web App Access Control](/en/3.13.x/use/publish/webapp/web-app-access). 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](/en/3.13.x/use/nodes/agent#new-agent) 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](/en/3.13.x/deploy/advanced-configuration/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](/en/3.13.x/deploy/advanced-configuration/environment-variables#agent-backend-configuration) 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](/en/3.13.x/deploy/advanced-configuration/agent-sandbox) 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](#files) instead.