Building Agents in Dify: Agent Apps vs. Agent Nodes
・ Employee Store Operations
Summary
There are two ways to build a tool-using AI agent in Dify: run it as a standalone app, or run it as one step in a workflow. This article explains both approaches, how to choose between them, how to add tools, and how to check that the agent works. The content was checked against the official documentation in October 2026.
As of October 2026, building agents in Dify is a little complicated. In addition to the existing agent features, a new Agent has been released as a beta. This article sorts out both.
The content of this article was checked against the official Dify documentation on October 2, 2026. The new Agent is in beta, so its specifications may change. Before you rely on it, check the latest information through the sources at the end.
Two Ways to Build Agents in Dify
A Dify agent is a setup where the model reasons on its own, decides what to do next, and uses tools when needed. There are two ways to use one.
- Run it standalone: publish it as a chat-style app that talks directly with users
- Run it inside a workflow: place an agent node in a Workflow or Chatflow and hand it one step of the process
Each has an existing form and a beta form. The existing Agent app is called the Legacy Agent app in the official documentation. The new beta Agent, once built in the Agents screen, can be used both as a standalone app and inside workflows.
What will you hand to the agent?
Anthropic recommends that when you build agents, you first look for the simplest solution and add complexity only when needed. It also explains that agentic systems tend to trade higher latency and cost for better performance. If a process can follow fixed steps, also consider building it as a workflow.
How to Build an Agent App
The Existing Agent App
When you create an app in Studio, choose Agent as the type. You configure the prompt, tools and knowledge. The history kept in one conversation is up to 500 messages or 2,000 tokens.
- Prompt: write the role, output format and constraints, and name which tools to use and when
- Tools: add Dify tools. For tools that require authentication, select or create credentials
- Maximum Iterations: the limit on the loop of reasoning, calling tools and processing results. Raising it increases time and token costs
- Knowledge: the model reads the knowledge description and decides on its own whether to search it. Write the description in detail
The New Beta Agent
In the Agents screen, choose Create, then Create from Blank, and give it a name. Creating and managing agents requires Editor permissions or higher. In Configure, set the model, prompt, skills, files and tools.
The new Agent runs inside its own sandbox, with 20GB of storage. It runs commands, installs programs, and reads and writes files. Beyond calling the tools you configure, it can take on open-ended work. There is also Build mode, where you describe what you want in conversation and the agent creates its own configuration.
| Item | Limit | When exceeded |
|---|---|---|
| Time | 1 hour | It stops, and the partial response is discarded |
| Model calls | 500 | The docs recommend splitting the work into smaller pieces |
| Returned files | Up to 50MB each | Larger files are not delivered |
Because the sandbox runs in the cloud, it cannot reach pages or files on your internal network. To let the agent use internal documents, add them to the agent's Files.
How to Use Agent Nodes
An agent node runs an agent as one step inside a workflow. It also comes in two forms.
The Existing Agent Node
It is available in Workflow and Chatflow. You set the agent's reasoning approach (Agent Strategy), model, tools, instructions and Query. In the instructions, you can use variables from earlier nodes with Jinja2 syntax. The Query holds the input you want the agent to work on.
Max Iterations is a limit that prevents endless loops. The official documentation suggests 3 to 5 for simple tasks and 10 to 15 for complex research.
- 3 iterationsLow end for simple tasks
- 5 iterationsHigh end for simple tasks
- 10 iterationsLow end for complex research
- 15 iterationsHigh end for complex research
Memory sets how many previous messages the agent remembers. More memory adds context but also raises token costs. The output includes the final answer, plus tool results, the reasoning steps, the number of iterations and whether it succeeded.
The New Beta Agent Node
The new agent node is available only in Workflow apps. You either invite a published agent or create an agent on the spot for use in that node only. For an invited agent, publishing an update in the Agents screen applies it to every workflow that uses it.
In the node's Agent task, write only what you want done in this step. Variables passed from earlier nodes arrive as text and are cut off at 2,000 characters. Pass long content as files. By default, there is one output, text. If needed, you can add outputs with set names and types.
Adding Tools: Built-in Tools and Custom Tools
Tools are managed together under Tools in Integrations. There are four types.
- Tool Plugin: tools provided by Dify or the community. Some, like Current Time, work right away, and others are installed from the Marketplace. Google, GitHub and similar tools need authentication first
- Swagger API: load an OpenAPI (Swagger) specification and the tool endpoints are created automatically. Use it to connect services that have no plugin
- Workflow: turn a Workflow that starts with User Input into a tool. A Chatflow cannot be turned into a tool
- MCP: connect an MCP server and import its tools. Only servers that communicate over HTTP are supported
In an agent node, write a description for each tool. The agent reads these descriptions to decide whether to use a tool. If you also write in which situations to use it, the agent is less likely to hesitate. We explain how MCP works in AI Agents and MCP.
Function Calling vs. ReAct
There are two ways an agent calls tools. In an Agent app, one of them appears automatically in Agent Settings, depending on the model you use. In an agent node, you choose it as the Agent Strategy.
Function Calling
- Uses the model's built-in tool-calling feature
- Passes tool definitions directly
- Shown when the model supports it
ReAct
- Guides the reasoning steps through the prompt
- Repeats reason, act, observe the result
- Works even with models that do not support tool calling
The official documentation recommends choosing a model with strong reasoning that natively supports tool calling. The model needs to judge when to use tools, which tool fits, and how to read the results. ReAct leaves a clear record of the reasoning steps, so it is also useful when you want to trace behavior.
Testing and Reading Logs
In an Agent app, test in the preview on the right side of the screen. With Debug as Multiple Models, you can compare answers from up to 4 models side by side. In workflows, check Run History after a test run.
- Run History: shows the result, inputs and outputs, and the execution order and time of each node. A node's Last run also shows that node's most recent inputs and outputs
- Logs: show how the app is actually used after publishing. In an Agent app, you can open the details of each iteration that called a tool. Token counts and response times are also shown
- Annotations: register a question together with a corrected answer as a pair
On the Sandbox plan, logs are deleted after 30 days. Check conversations you want to review later early. Test runs in the Chatflow and Workflow editors are not recorded in Logs.
We cover the basics of Dify in How to Use Dify and the two kinds of workflows in Dify Chatflow vs. Workflow.
List Your Agent on Employee Store
Employee Store is a marketplace where companies can adopt AI agents built by developers, through a one-time purchase or a monthly plan. Any format is accepted, including agents built in Dify. There is no listing fee or upfront cost. The fee is 20% of the deal amount and applies only when a deal closes. For details, see the seller guide.
FAQ
- Should I use a Dify agent app or an agent node?
- If one agent can achieve the goal by talking with users, an agent app is the better fit. If you need a fixed order of steps, conditional branches, or combinations with other nodes, use an agent node inside a workflow.
- Can I choose between Function Calling and ReAct myself?
- In the existing agent node, you choose it as the Agent Strategy. In an Agent app, Agent Settings shows Function Calling if the model natively supports tool calling, and ReAct if it does not.
- Can I use the new Agent right now?
- As of October 2026, the new Agent is available as a beta. It has limits, such as up to 1 hour per run and up to 500 model calls. Its specifications may change, so check the latest information in the official documentation.
