Building a Dify Agent App: Prompts, Variables and Tools

Who this is for, and what you will be able to do

This guide is for builders who want a chat app in which the model decides for itself when to call a tool, rather than following a fixed sequence of steps. After reading it, you will know how to write the prompt, add variables and tools, connect a knowledge base, and test the app before you publish it.

Agent or workflow

An Agent is a conversational app. The model uses tools when a request needs them^[1]. Choose an Agent when you want the model to decide on its own how to use the available tools, and you do not want to design a multi-step workflow. A data analysis assistant is a typical case: it can fetch live data, generate charts and summarise the findings^[1].

Note that the classic Agent is now labelled Legacy. A newer Agent, still in beta, runs in its own sandbox, is built once, and can be used both as a chat app and in workflows^[1].

Write the prompt

The prompt tells the model what to do, how to respond and which constraints to follow. In an Agent, it should also guide how the model reasons about the task and when to use tools, so describe the expected workflow in plain terms^[1]. Five habits help:

• Define the role and the expertise the model should apply^[1].
• Specify the output structure, length or style you expect^[1].
• Set constraints on what to avoid and which rules to follow^[1].
• Name the tools and describe when each one should be used^[1].
• Split complex tasks into logical steps the model should follow^[1].

If you are not sure where to start, the Generate button uses an LLM to draft a prompt from a description. It can also improve an existing prompt: reference current_prompt and say what to change. Adding examples under Ideal output makes the result more precise^[1]. Each generated prompt is saved as a version, so you can try a change and roll it back^[1].

Use variables for inputs that change

Variables are placeholders in the prompt. Each one appears as an input field that the user fills in before the conversation starts, and its value is injected into the prompt when the app runs. Users can also change values during a conversation, and the prompt adjusts^[1].

To insert one, type / in the prompt editor and choose Add new variable. Its details are configured later in the Variables section^[1]. A data analysis Agent might use a domain variable so that the user can say which field they want to focus on^[1].

Choose the type that matches the input you expect^[1]:

• Text accepts up to 256 characters, which suits names, email addresses, titles and other short single-line input.
• Paragraph has no length limit and gives the user a multi-line text area.
• Dropdown shows predefined options.
• Number accepts only numeric input.
• Checkbox outputs true when checked and false otherwise.
• API-based variable is fetched from an external API when the app runs, not typed by the user. Use it when the prompt needs data such as live weather or database records. Custom endpoints are configured for this type^[1].

The display name is the label each end user sees on the input field^[1].

Add tools

Dify tools let the model interact with external services and APIs, for example to fetch live data, search the web or query a database^[1]. The model decides for each query whether to use a tool, and which one. To steer that choice, name the tool in the prompt and describe when it should be used^[1].

If a tool needs authentication, pick an existing credential or create a new one. To change the default credential, go to Integrations > Tools > Tool plugins^[1].

Max iterations, in Agent settings, caps how many reasoning-and-action loops the model can run in one request. Each loop is a round of thinking, calling a tool and processing the result. Raise the cap for complex tasks that need several tool calls, but expect higher latency and token use^[1].

Ground answers in your own data

To base replies on your own material, add a classic knowledge base^[1]. The model compares each query with the knowledge base's description and decides whether to retrieve from it, so the prompt does not need to mention the knowledge base. A more detailed description makes those relevance judgments more accurate^[1].

The Agent app has no app-level retrieval settings. Each knowledge base searches with its own settings. With several knowledge bases, the Agent decides which ones to query, and results are not re-ranked across them^[1]. By default retrieval covers the whole knowledge base. To narrow it to certain documents, turn on manual or automatic metadata filtering^[1].

Let users upload files

To accept files, choose a model with the matching multimodal capability. The Vision, Audio or Document switch appears when the model supports it^[1].

• Resolution: High gives more accuracy on complex images but uses more tokens. Low is faster and uses fewer tokens for simple images^[1].
• Upload method: device upload, URL paste, or both^[1].
• Upload limit: the maximum number of files a user can upload per message^[1].

Debug in the preview panel and publish

Test the Agent in the preview panel: choose a model, send a message and check the reply^[1]. Multiple-model debug runs up to four models at once, which helps when you compare outputs^[1].

Choose a model with strong reasoning and native tool-calling support^[1]. In Agent settings the Agent mode is shown automatically: Function Calling for models with native support, and ReAct for other models, where Dify guides tool use through a prompt strategy^[1].

When the results are right, click Publish to make the app available. The full publishing options are on the publish page^[1].

Limits to keep in mind

An Agent keeps at most 500 messages or 2,000 tokens of history for each conversation. When either limit is exceeded, the oldest messages are removed to make room for new ones^[1].

Next steps

For the complete details on Agents, knowledge bases, tools and publishing, see the Dify documentation^[1].

Adapted from the Dify documentation page *Agent*^[1], released under the CC BY 4.0 license.