> ## Documentation Index > Fetch the complete documentation index at: https://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's on by default on Docker Compose, with its runtime bundled in. 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. ## 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/self-host/use-dify/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. Creating and managing agents requires the Editor role or above. ## 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/self-host/use-dify/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/self-host/deploy/configuration/environments#upload_skill_file_size_limit). To share an embedded skill with other agents, [make it a library skill](/en/self-host/use-dify/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/self-host/deploy/configuration/environments): | 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/self-host/deploy/configuration/environments) for details. ### Tools Give the agent [Dify tools](/en/self-host/use-dify/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 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/self-host/deploy/configuration/environments#new-agent-beta) 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. ## 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/self-host/use-dify/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/api-reference/guides/agent). **Data Security Notice** Community Edition uses file-access controls to limit access to agent and session files when the same agent is exposed to multiple end users. These controls reduce the risk of cross-conversation data access through the filesystem, but the Agent runtime is not intended to provide a hardened security boundary between mutually untrusted users or workloads. If your deployment requires strong isolation or strict security or compliance controls, use separately hardened infrastructure or contact Dify to assess an appropriate Cloud or Enterprise option. For Dify Enterprise, [contact sales](https://share-na2.hsforms.com/14-09ff5HS92Sh4m3f4yrcw40s9fk) to learn more. You can also invite the agent into a workflow's [Agent node](/en/self-host/use-dify/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/self-host/deploy/configuration/environments) 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/self-host/deploy/configuration/environments) for details. ## Troubleshooting The deployment's `.env` predates 1.16.0, so the Agents switch is missing or still off. 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. In Chatflow apps the node's absence is expected: it's available in Workflow apps only. If other members see **Agents** but you don't, the cause is your workspace role: the entry needs the Editor role or above. If every run errors immediately, the deployment may be running 1.16.0 or later images with an older `docker-compose.yaml`, which lacks the agent's services (including `agent_backend` and `local_sandbox`). Update the compose file along with the images, then bring the stack up again. Models served through OpenAI-compatible endpoints (vLLM and similar) often lack full native tool-calling support, which the agent depends on. Pick a model that supports tool calling natively. If a compatible model still errors, check the provider's **Token parameter name** setting: some newer models require `max_completion_tokens`, and auto-detection can guess wrong. The sandbox's internet access goes through a proxy that blocks private-network addresses by design. Public URLs work; for material on your intranet, add it to the agent's [Files](#files) instead.