Verified: October 2026 New Agent is beta

Dify AI Agent Guide: New Agent vs Agent Node

Dify now uses the word Agent for two different build paths. This guide separates the new reusable Agent from the classic Agent node, then shows how to choose tools, test failure cases and select a hosting model without relying on stale feature lists or fixed price claims.

Choose an agent path Build checklist

The short answer

New Agent

Reusable worker with a sandbox

Configure a model, prompt, skills, files, tools and environment variables once. Run it as a chat app or invite it into a Workflow. Dify currently marks this product as beta.

New Agent node

A new Agent inside a Workflow

Invite a published Agent or create a one-time Agent for one Workflow step. Each run gets its own sandbox, and declared outputs can pass results to later nodes.

Classic Agent node

A model that selects configured tools

Use Function Calling or ReAct in a Workflow or Chatflow. Configure the model, tool authorization, descriptions, parameters, instructions, query, iteration limit and memory.

If you need a fixed and inspectable sequence, use a regular Dify Workflow. An agent is useful when the next action depends on what happened during the run. It is not automatically the better option for a deterministic process.

Which Dify agent should you use?

Start from the operating requirement, not the most advanced interface.

Requirement Best starting point Reason Main risk to test
Reusable research or support worker New Agent One capability can serve chat and Workflow tasks. Beta behavior, sandbox access and tool permissions.
Open-ended step inside a larger process New Agent node The surrounding Workflow controls order and handoffs. Output contracts and the 2,000-character text-variable limit.
Model chooses among a small tool set Classic Agent node Simple tool-loop configuration with explicit iteration controls. Wrong tool selection and runaway iterations.
Known sequence with auditable branches Regular Workflow The path is visible and predictable. Branch coverage and failed external calls.

Build a new Dify Agent in six checks

Dify requires the Editor role or above to create and manage a new Agent. The interface can build from a blank configuration or import a DSL file.

1

Define one job

Write the task boundary and the required output before choosing tools. A narrow worker is easier to test than a general assistant.

2

Choose a compatible model

Use a current model with native tool calling. Verify that it actually invokes commands and tools in your provider configuration.

3

Write operational instructions

State the role, expected approach, tool rules, prohibited actions and output format. Avoid relying on a vague persona alone.

4

Add only required capabilities

Attach the specific skills, reference files, plugins, custom APIs, workflows or MCP servers needed for the job. Store non-secret configuration in environment variables.

5

Test in Preview

Preview does not change the saved configuration. Test normal tasks, missing input, unavailable tools, unsafe requests, timeouts and malformed external responses.

6

Publish and monitor

Publish a version only after the test set passes. Review Logs by access point and restore a prior version when a new configuration regresses.

Classic Agent node: Function Calling or ReAct?

The classic node gives a model access to configured tools. Tool descriptions and parameter definitions are part of the control surface, so vague descriptions can cause wrong calls even when the model is capable.

Function Calling

The model uses its native structured tool-call mechanism. Start here when the model and provider endpoint explicitly support reliable function calling.

ReAct

The model follows a prompted reason, action and observation loop. It can fit models without native function calling or cases where a visible trace is needed.

Comparison rule: run the same 15 to 20 tasks through both strategies. Record task completion, wrong tool calls, retries, model requests, latency and cost. Pick from measured behavior rather than a fixed model recommendation that will become stale.

Limits and security checks

The new Agent can run commands, install programs and handle files in a 20 GB sandbox. That capability is useful, but it also expands the area you need to test.

Run ceiling

A run stops after one hour and is capped at 500 model requests. Split jobs that can exceed either limit.

Files

A file returned in a reply is capped at 50 MB. Uploaded reference files have type-specific limits in the Dify documentation.

Credentials

Use the narrowest API credential possible. Separate read and write tools, and require approval outside Dify for irreversible actions.

Network access

The hosted sandbox cannot reach private-network hosts directly. Supply internal material as approved files or expose a controlled public endpoint.

Prompt injection

Treat tool output, web pages and uploaded files as untrusted input. Test instructions that try to override the agent role or reveal secrets.

Observability

Log the access point, model, version, tool calls and final status. A successful final answer alone does not prove that the right tools were used.

Hosting a self-managed Dify deployment

Hosting and model usage are separate decisions. A self-managed Dify server still needs model-provider credentials or compatible local inference, plus updates, backups, storage and monitoring. Review our Docker setup guide before choosing an infrastructure plan.

Disclosure: the two provider buttons below are affiliate links. We may earn a commission without changing your price. Provider capabilities and prices can change, so verify the current offer before purchase.

Self-managed virtual machine

Hetzner Cloud

Hetzner documents shared and dedicated Cloud server types, optional networking, volumes, firewalls, backups and snapshots. You remain responsible for installing and operating Dify.

Check current Hetzner plans

Managed application service

Elestio

Elestio documents managed Dify deployment, TLS, firewall configuration, optional update scheduling and several backup methods. Confirm the selected provider, region and estimated price in its deployment flow.

Check current Elestio offer
Compare Dify hosting options Connect tools with MCP

Frequently asked questions

What is the difference between the new Dify Agent and the classic Agent node?

The new Agent is a reusable AI worker with its own sandbox, prompt, skills, files and tools. It can run as a standalone chat app or inside a Workflow. The classic Agent node is a model-with-tools step inside a Workflow or Chatflow and uses Function Calling or ReAct.

Is the new Dify Agent production ready?

Dify currently labels the new Agent and the new Agent node as beta. Treat that label as a release constraint: test the exact model, tools, permissions and failure paths you plan to use before exposing the agent to production users.

Can a Dify Agent use custom APIs and MCP servers?

Yes. The new Agent can receive plugins, custom APIs, workflows and MCP servers from the Dify workspace. External tools can require authentication, so grant only the credentials and operations needed for the agent task.

Should I use Function Calling or ReAct in the classic Agent node?

Use Function Calling when the selected model reliably supports native tool calls. ReAct uses a prompted reason-and-act loop and can be useful when native function calling is unavailable or when the trace is important. Test both with the same task set before choosing.

What limits apply to a new Dify Agent run?

Dify documents a one-hour limit and a maximum of 500 model requests for each run. A reply file can be up to 50 MB. Break long jobs into smaller tasks and set narrower tool permissions so failures are easier to inspect and retry.

Primary sources used for this guide

Product behavior was checked against official documentation on 21 October 2026. Hosting descriptions use the providers' own documentation and do not assume that a current plan or price will remain available.