Skip to content

Add intro docs for different app types #718

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
RiskeyL wants to merge 2 commits into from
Closed

Add intro docs for different app types #718

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
db6c390
draft
RiskeyL Mar 11, 2026
8ff280e
Merge branch 'main' into add/app-intro
RiskeyL Apr 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 50 additions & 52 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,63 +23,62 @@
"version": "Latest",
"dropdowns": [
{
"dropdown": "Use Dify",
"icon": "book-open",
Copy link

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first top-level navigation dropdown object (icon: "book-open") no longer has a dropdown label (it previously was "Use Dify"). Without dropdown, Mintlify may render this dropdown without a name or fail to build navigation correctly. Add "dropdown": "Use Dify" to this dropdown object (consistent with the other dropdowns below).

Suggested change
"icon": "book-open",
"icon": "book-open",
"dropdown": "Use Dify",

Copilot uses AI. Check for mistakes.
"pages": [
{
"group": " ",
"group": "Get Started",
"expanded": false,
"pages": [
"en/use-dify/getting-started/introduction",
"en/use-dify/getting-started/quick-start",
"en/use-dify/getting-started/key-concepts"
]
},
{
"group": "Build",
"pages": [
{
"group": "Get Started",
"expanded": false,
"pages": [
"en/use-dify/getting-started/introduction",
"en/use-dify/getting-started/quick-start",
"en/use-dify/getting-started/key-concepts"
]
},
{
"group": "Nodes",
"expanded": false,
"group": "Workflow & Chatflow",
"pages": [
"en/use-dify/nodes/user-input",
"en/use-dify/build/workflow-chatflow",
{
Comment on lines +37 to 44
Copy link

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New app-type intro pages were added (en/use-dify/build/agent, .../chatbot, .../text-generator), but they are not referenced anywhere in docs.json navigation. If left out, these pages will be orphaned (not reachable from the sidebar) and the PR goal (“intro docs for different app types”) won’t be reflected in the docs IA. Add these pages under the appropriate Build group (or a new group such as "App Types").

Copilot uses AI. Check for mistakes.
"group": "Trigger",
"icon": "bolt-lightning",
"group": "Nodes",
"expanded": false,
"pages": [
"en/use-dify/nodes/trigger/overview",
"en/use-dify/nodes/trigger/schedule-trigger",
"en/use-dify/nodes/trigger/plugin-trigger",
"en/use-dify/nodes/trigger/webhook-trigger"
]
"en/use-dify/nodes/user-input",
{
"group": "Trigger",
"icon": "bolt-lightning",
"pages": [
"en/use-dify/nodes/trigger/overview",
"en/use-dify/nodes/trigger/schedule-trigger",
"en/use-dify/nodes/trigger/plugin-trigger",
"en/use-dify/nodes/trigger/webhook-trigger"
]
},
"en/use-dify/nodes/llm",
"en/use-dify/nodes/knowledge-retrieval",
"en/use-dify/nodes/answer",
"en/use-dify/nodes/output",
"en/use-dify/nodes/agent",
"en/use-dify/nodes/question-classifier",
"en/use-dify/nodes/ifelse",
"en/use-dify/nodes/human-input",
"en/use-dify/nodes/iteration",
"en/use-dify/nodes/loop",
"en/use-dify/nodes/code",
"en/use-dify/nodes/template",
"en/use-dify/nodes/variable-aggregator",
"en/use-dify/nodes/doc-extractor",
"en/use-dify/nodes/variable-assigner",
"en/use-dify/nodes/parameter-extractor",
"en/use-dify/nodes/http-request",
"en/use-dify/nodes/list-operator",
"en/use-dify/nodes/tools"
],
"icon": "cubes"
},
"en/use-dify/nodes/llm",
"en/use-dify/nodes/knowledge-retrieval",
"en/use-dify/nodes/answer",
"en/use-dify/nodes/output",
"en/use-dify/nodes/agent",
"en/use-dify/nodes/question-classifier",
"en/use-dify/nodes/ifelse",
"en/use-dify/nodes/human-input",
"en/use-dify/nodes/iteration",
"en/use-dify/nodes/loop",
"en/use-dify/nodes/code",
"en/use-dify/nodes/template",
"en/use-dify/nodes/variable-aggregator",
"en/use-dify/nodes/doc-extractor",
"en/use-dify/nodes/variable-assigner",
"en/use-dify/nodes/parameter-extractor",
"en/use-dify/nodes/http-request",
"en/use-dify/nodes/list-operator",
"en/use-dify/nodes/tools"
]
},
{
"group": "Build",
"expanded": false,
"pages": [
"en/use-dify/build/shortcut-key",
"en/use-dify/build/goto-anything",
"en/use-dify/build/orchestrate-node",
"en/use-dify/build/predefined-error-handling-logic",
"en/use-dify/build/mcp",
Expand Down Expand Up @@ -255,7 +254,6 @@
]
},
{
"dropdown": "Self Host",
"icon": "server",
"pages": [
{
Expand Down Expand Up @@ -295,10 +293,10 @@
"en/self-host/troubleshooting/weaviate-v4-migration"
]
}
]
],
"dropdown": "Self Host"
},
{
"dropdown": "API Reference",
"icon": "code",
"groups": [
{
Expand All @@ -321,10 +319,10 @@
"group": "Text Completion",
"openapi": "en/api-reference/openapi_completion.json"
}
]
],
"dropdown": "API Reference"
},
{
"dropdown": "Develop Plugin",
"icon": "code-pull-request",
"groups": [
Comment on lines 325 to 327
Copy link

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "Develop Plugin" top-level navigation dropdown no longer has a dropdown label (only icon + groups). Other dropdown entries include a dropdown string (e.g., "Self Host", "API Reference"); without it this section may render without a name or break navigation. Add "dropdown": "Develop Plugin" to this dropdown object.

Copilot uses AI. Check for mistakes.
{
Expand Down
212 changes: 212 additions & 0 deletions en/use-dify/build/agent.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,212 @@
---
title: Agent
description: Chat-style apps where the model can reason, make decisions, and use tools autonomously
icon: robot
---

Agents are chat-style apps where the model can reason through a task, decide what to do next, and use tools when needed to complete the user's request.

Use it when you want the model to autonomously decide how to approach a task using available tools, without designing a multi-step workflow. For example, building a data analysis assistant that can fetch live data, generate charts, and summarize findings on its own.

<Info>
Agents keep up to 500 messages or 2,000 tokens of history per conversation. If either limit is exceeded, the oldest messages will be removed to make room for new ones.
</Info>

## Configure

### Write the Prompt

The prompt tells the model what to do, how to respond, and what constraints to follow. For an agent, the prompt also guides how the model reasons through tasks and decides when to use tools, so be specific about the workflow you expect.

Here are some tips for writing effective prompts:

- **Define the persona**: Describe who the model should act as and the expertise it should draw on.

- **Specify the output format**: Describe the structure, length, or style you expect.

- **Set constraints**: Tell the model what to avoid or what rules to follow.

- **Guide tool usage**: Mention specific tools by name and describe when they should be used.

- **Outline the workflow**: Break down complex tasks into logical steps the model should follow.

#### Create Dynamic Prompts with Variables

To adapt the agent to different users or contexts without rewriting the prompt each time, add variables to collect the necessary information upfront.

Variables are placeholders in the prompt—each one appears as an input field that users fill in before the conversation starts, and their values are injected into the prompt at runtime. Users can also update variable values mid-conversation, and the prompt will adjust accordingly.

For example, a data analysis agent might use a domain variable so users can specify which area to focus on:

```text wrap
You are a data analyst specializing in {{domain}}. Help users explore and understand their data.

When asked a question, use available data tools to fetch the relevant information. If the result suits a visual format, generate a chart. Explain your findings in plain language.

Keep responses concise. If a question is ambiguous, ask for clarification before fetching data.
```

<Tip>
While drafting the prompt, type `/` > **New Variable** to quickly insert a named placeholder. You can configure its details in the **Variables** section later.
</Tip>

Choose the variable type that matches the input you expect:

<Tabs>
<Tab title="Short Text">
Accepts up to 256 characters. Use it for names, email addresses, titles, or any brief text input that fits on a single line.
</Tab>
<Tab title="Paragraph">
Allows long-form text without length restrictions. It gives users a multi-line text area for detailed descriptions.
</Tab>
<Tab title="Select">
Displays a dropdown menu with predefined options.
</Tab>
<Tab title="Number">
Restricts input to numerical values only—ideal for quantities, ratings, IDs, or any data requiring mathematical processing.
</Tab>
<Tab title="Checkbox">
Provides a simple yes/no option. When a user checks the box, the output is `true`; otherwise, it's `false`. Use it for confirmations or any case that requires a binary choice.
</Tab>
<Tab title="API-based Variable">
Fetches variable values from an external API at runtime instead of collecting them from users.

Use it when your prompt needs dynamic data from an external source, such as live weather conditions or database records. See [API Extension](/en/use-dify/workspace/api-extension/api-extension) for details.
</Tab>
</Tabs>

<Info>
**Label Name** is what end users see for each input field.
</Info>

#### Generate or Improve the Prompt with AI

If you're unsure where to start or want to refine the existing prompt, click **Generate** to let an LLM help you draft it.

Describe what you want from scratch, or reference `current_prompt` and specify what to improve. For more targeted results, add an example in **Ideal Output**.

Each generation is saved as a version, so you can experiment and roll back freely.

### Extend the Agent with Dify Tools

Add Dify tools to enable the model to interact with external services and APIs for tasks beyond text generation, such as fetching live data, searching the web, or querying databases.

The model decides when and which tools to use based on each query. To guide this more precisely, mention specific tool names in your prompt and describe when they should be used.

<Frame>
![Tool Name](/images/tool_name.png)
Copy link

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The image alt text Tool Name is too generic and doesn’t describe what the screenshot shows, which reduces usability for screen readers and when the image fails to load. Update the alt text to describe the UI (e.g., the tools panel/list in the Agent tool configuration).

Suggested change
![Tool Name](/images/tool_name.png)
![Agent tools configuration panel showing the tools list and tool settings](/images/tool_name.png)

Copilot uses AI. Check for mistakes.
</Frame>

You can disable or remove added tools, and modify their configuration. If a tool requires authentication, select an existing credential or create a new one.

<Info>
To change the default credential, go to **Tools** or **Plugins**.
</Info>

#### Maximum Iterations

**Maximum Iterations** in **Agent Settings** limits how many times the model can repeat its reasoning-and-action cycle (think, call a tool, process the result) for a single request.

Increase this value for complex, multi-step tasks that require multiple tool calls. Higher values increase latency and token costs.

### Ground Responses in Your Own Data

To ground the model's responses in your own data rather than general knowledge, add a knowledge base.

The model evaluates each user query against your knowledge base descriptions and decides whether retrieval is needed—you don't need to mention knowledge bases in your prompt.

**The more detailed your knowledge base description, the better the model can determine relevance**, leading to more accurate and targeted retrieval.

#### Configure App-Level Retrieval Settings

To fine-tune how retrieval results are processed, click **Retrieval Setting**.

<Info>
There are two layers of retrieval settings—the knowledge base level and the app level.

Think of them as two consecutive filters: the knowledge base settings determine the initial pool of results, and the app settings further rerank the results or narrow down the pool.
</Info>

- **Rerank Settings**

- **Weighted Score**

The relative weight between semantic similarity and keyword matching during reranking. Higher semantic weight favors meaning relevance, while higher keyword weight favors exact matches.

Weighted Score is available only when all added knowledge bases are indexed with **High Quality** mode.

- **Rerank Model**

The rerank model to re-score and reorder all the results based on their relevance to the query.

<Note>
If any multimodal knowledge bases are added, select a multimodal rerank model (marked with a **Vision** tag) as well. Otherwise, retrieved images will be excluded from reranking and the final output.
</Note>

- **Top K**

The maximum number of top results to return after reranking.

When a rerank model is selected, this value will be automatically adjusted based on the model's maximum input capacity (how much text the model can process at once).

- **Score Threshold**

The minimum similarity score for returned results. Results scoring below this threshold are excluded. Use higher thresholds for stricter relevance or lower thresholds to include broader matches.

#### Search Within Specific Documents

By default, retrieval searches across the entire knowledge base. To restrict retrieval to specific documents, enable manual or automatic metadata filtering.

This improves retrieval precision, especially when your knowledge base is large or contains content for different contexts.

For creating and managing document metadata, see [Metadata](/en/use-dify/knowledge/metadata).

### Process Multimodal Inputs

To allow users to upload images, audio, or documents when using the app, select a model that supports the corresponding modalities and enable specific file types—**Vision**, **Audio**, and **Document**.

<Tip>
You can quickly identify a model's supported modalities by its tags.

<Frame>
![Model Tags](/images/model_multimodal_tag.png)
</Frame>
</Tip>

Click **Settings** under **Vision** to configure how files are accepted and processed. Upload settings apply across all enabled file types.

- **Resolution**: Controls the detail level for **image** processing only.

- **High**: Better accuracy for complex images but uses more tokens

- **Low**: Faster processing with fewer tokens for simple images

- **Upload Method**: Choose whether users can upload from their device, paste a URL, or both.

- **Upload Limit**: The maximum number of files a user can upload per message.

<Tip>
Agents also support optional features like conversation openers, follow-up suggestions, text to speech, speech to text, citations and attributions, content moderation, and annotation replies. See [App Toolkit](/en/use-dify/build/app-toolkit) for details.
Copy link

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/en/use-dify/build/app-toolkit is referenced here, but there is no app-toolkit.mdx (or equivalent) under en/use-dify/build/, so this will be a broken link. Please point this to an existing page that covers these features (or add the missing App Toolkit page).

Suggested change
Agents also support optional features like conversation openers, follow-up suggestions, text to speech, speech to text, citations and attributions, content moderation, and annotation replies. See [App Toolkit](/en/use-dify/build/app-toolkit) for details.
Agents also support optional features like conversation openers, follow-up suggestions, text to speech, speech to text, citations and attributions, content moderation, and annotation replies. See [App Toolkit](/en/use-dify/build/README) for details.

Copilot uses AI. Check for mistakes.
</Tip>

## Debug & Preview

In the preview panel on the right, you can test your agent in real time. Select a model, type a message, and send it to see how the agent responds.

We recommend selecting models that are strong at reasoning and natively support tool calling. After selecting a model, you can adjust its parameters to control how it generates responses. Available parameters and presets vary by model.

<Info>
The system automatically determines the agent mode for the selected model—**Function Calling** or **ReAct**. Check the current mode in **Agent Settings**.
</Info>

<Tip>
To compare outputs across different models, click **Debug as Multiple Models** to run up to 4 models simultaneously.

<Frame>
![Debug with Multiple Models](/images/multiple_model_debug.png)
</Frame>
</Tip>

## Publish

When you're happy with the results, click **Publish** to make your app available. See [Publish](/en/use-dify/publish/README) for the full list of publishing options.
Loading
Loading