Dify agent tutorial: add tools, publish and call it from code

Two kinds of agent in Dify

In an agent app, the model reasons through a task, decides what to do next and calls tools when it needs them, all behind a chat interface. You use one when you want the model to choose its own approach, without a fixed flow of steps. The docs' example is a data analysis assistant that fetches live data, draws charts and summarizes what it finds. If the term is new, what is an AI agent explains it.

Dify now has two kinds. The Agent app in Studio carries a Legacy tag in the docs. The new Agent, in beta, works in a sandbox of its own. This lesson builds the legacy app, because its page walks through every setting, and the last section covers the new one.

Write the prompt

The prompt tells the model what to do, how to answer and which rules to follow. For an agent it also steers how the model reasons and when it reaches for a tool, so describe the workflow you expect. The docs list five habits: define a persona, specify the output format, set constraints, mention tools by name with a note on when to use them, and break a complex task into steps.

Variables let one agent fit many users. A variable is a placeholder that appears as an input field, and its value is injected when the agent runs. While drafting, type / and pick New Variable. The types are Short Text (up to 256 characters), Paragraph, Select, Number, Checkbox and API-based Variable, which fetches its value from an external API at runtime. If you are unsure where to start, the Generate button asks a model to draft the prompt, and each generation is saved as a version. This is the docs' example, with a domain variable.

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.

Add tools and a knowledge base

Tools let the model go beyond text: fetching live data, searching the web or querying a database. The model chooses when and which tool to use for each query, so name the tools in your prompt and say when they apply. Manage them under Integrations > Tools. A tool that needs authentication takes an existing credential or a new one. Dify can also import the tools of an MCP server, a standard way to offer tools to AI apps that what is MCP explains. The tools lesson covers what makes a tool easy for an agent to use.

Maximum Iterations in Agent Settings caps how many times the model can repeat its think, call a tool, read the result cycle for one request. Raise it for multi-step tasks, and expect more latency and more token cost.

To ground answers in your own data, add a knowledge base. The model reads each knowledge base's description and decides whether to retrieve, so the prompt needn't mention it, and a more detailed description gives better retrieval. An Agent app has no app-level retrieval settings. Each knowledge base uses its own, and with several the agent picks which to query without reranking across them. Lesson 3 builds one.

Pick the model with care. The docs recommend models that are strong at reasoning and support tool calling natively, because the agent has to judge when to use a tool, which one fits and how to read the result. Agent Settings shows Function Calling for models with native support, and ReAct for the rest, where Dify guides tool use through prompting.

1. In Studio, create an Agent app.
2. Paste the prompt above, then type / and pick New Variable to create domain.
3. Add the tools the task needs. If one asks for authentication, choose a credential or create one.
4. Add a knowledge base if answers must come from your data, and write its description in detail.
5. Open Agent Settings, check whether it shows Function Calling or ReAct, and set Maximum Iterations.
6. In Debug & Preview, select a model and chat. Debug as Multiple Models runs up to 4 models side by side.
7. Click Publish.

Publish as a web app, an embed or an MCP server

Click Publish and Dify creates a web app and an API endpoint from your latest configuration. The web app link sits on the app's Access Point tab. Web apps are public by default, so anyone with the URL can open one, and restricting access with authentication is a Dify Enterprise feature. Publishing replaces the live app, and users see the change in their next interaction.

Set the app's name, description and icon before you share it, and keep the description under 160 characters. A chat-style app such as an Agent app can also carry an input placeholder of up to 64 characters in your own words.

To put the web app on your own site, open the Access Point tab and click Embed Into Site on the Web App card to find your token. The chat bubble is a floating button configured through window.difyChatbotConfig, and an iframe shows the app inside the page. Both display the published web app, so republish after a change. This iframe snippet is the docs' own.

The MCP Server card on the same tab is off by default. Turning it on generates a server address that tools such as Claude Desktop and Cursor can add. The address contains credentials, so treat it like an API key and use the regenerate button if it leaks.

<iframe
  src="http://your-dify-host/chatbot/YOUR_APP_TOKEN"
  width="100%"
  height="600"
  frameborder="0">
</iframe>

Call the agent from your code

Every app you publish is also a REST API, which you call from your own backend with an API key. Create the key inside the app. It is scoped to that one app, and one key serves all your end users, who you tell apart with a per-person user value. Call the API from your backend only, because a key placed in frontend code or a client app can be extracted and abused.

On Dify Cloud the base URL is https://api.dify.ai/v1, and a self-hosted install uses its own API base URL. Most requests carry the key as a Bearer token. The first call below returns the app's name, description, tags, author and mode. The mode picks the guide to follow. Use chat or agent-chat for a Chatbot or legacy Agent app, agent for the new Agent, advanced-chat for a Chatflow, workflow for a Workflow and completion for a Text Generator.

A legacy Agent app supports streaming mode only, and it streams agent_thought and agent_message events. The new Agent's API is streaming only too, and a blocking request returns a 400 error.

curl https://api.dify.ai/v1/info \
  -H "Authorization: Bearer $DIFY_API_KEY"

1. Open the published app and create an API key from inside it.
2. Store the key on your server as DIFY_API_KEY.
3. Run the call above from the server. The docs show a response that names the app and its mode.
4. Open the guide for that mode and send your first chat message.

Read the logs

The Logs tab shows how an app is used in practice. Chat apps, Agent apps included, log conversations. It captures the web app, the API and apps opened from the Web Apps list on Home. Test sessions from the editor are left out for Chatflow and Workflow apps, but for other app types they are listed under the team member's account.

Click a row to open the thread. Hover over an answer to see its token spend and latency, to open the log behind it, which for an Agent app shows the raw prompt and the tool iterations, or to rate it. User Rate counts end users' likes and dislikes, and Op. Rate counts your team's.

Logs hold complete conversations, so publish a privacy policy where the law asks for one. They are kept indefinitely by default. To clean up conversation messages, set ENABLE_CLEAN_MESSAGES to true and SANDBOX_EXPIRED_RECORDS_RETENTION_DAYS to the days to keep, 30 by default. Deleting conversations or old logs does not erase the files users uploaded.

Annotations: your answer for a known question

An annotation pairs a question with the reply you want. With annotation reply on, Dify searches the annotations for a semantic match to each question. A match above the similarity threshold returns your reply, and anything else goes through normal generation.

Turn it on under Orchestrate > Add Features, then choose the similarity threshold and an embedding model. A higher threshold demands closer matches, and changing the embedding model regenerates all embeddings. Create annotations by editing an answer in a log or in debug mode, by importing the template in bulk, or by hand under Annotations. Hit tracking shows which ones get used. Questions that keep missing your annotations point to gaps.

The new Agent, in beta

Create it on the Agents page with Create > Create from Blank, a name, and optionally a role and a description. Everything else is set in Configure: the model, the prompt, skills, files, tools, knowledge retrieval and environment variables. A skill is a package with a SKILL.md file that teaches the agent a procedure. One agent can take up to 20 library skills, and a package can be up to 50 MB by default.

Build mode lets you describe the agent in chat and watch it fill in its own prompt, skills, files and environment variables. Click Apply to keep the changes or Discard to drop them. Either choice ends build mode. The first Apply creates a build_note.md in Files that records what the agent set up.

On its own, the agent is a chat app that you can publish as a web app or call through the service API. Inside a workflow, an Agent node hands it one step. In both cases its sessions collect on the Logs page.

Community Edition's agent runtime is not meant to be a hardened boundary between mutually untrusted users or workloads. For production, replace DIFY_AGENT_SERVER_SECRET_KEY and DIFY_AGENT_API_TOKEN with your own random values. The guardrails lesson covers sandboxes and permissions in general.

Common mistakes

• Leaving the prompt silent about tools. The docs advise naming each tool and saying when it applies.
• Picking a model without native tool calling. The docs say models with built-in tool-call support execute these decisions more reliably, and Agent Settings shows which mode you got.
• Raising Maximum Iterations without a reason. Higher values add latency and token cost.
• Calling the API from frontend code, where the key can be extracted and abused.
• Changing the app and forgetting to publish again. Web apps and embeds show the published version only.
• Sharing a web app link and assuming it is private.
• Pasting the MCP server address into a public chat or repository. It contains credentials.

Try it yourself

• Ask the agent a question that needs a tool, then open the answer's log and read the tool iterations.
• Change the domain value and ask the same question again.
• Edit one answer into the reply you would rather give and save it as an annotation. Turn on annotation reply and ask a similar question.

Next course: Browser agents

Dify agents call the tools you give them. Browser agents are the next course: AI that clicks, types and browses for you.

Frequently asked questions

Sources

1. Dify Docs (GitHub): Agent (legacy) (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/build/agent.mdx
2. Dify Docs (GitHub): Agent (new) overview (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/build/new-agent/overview.mdx
3. Dify Docs (GitHub): Agent (new) (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/build/new-agent/build.mdx
4. Dify Docs (GitHub): Dify Tools (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/workspace/tools.mdx
5. Dify Docs (GitHub): Publish overview (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/publish/README.mdx
6. Dify Docs (GitHub): Embed Your Web App (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/publish/webapp/embedding-in-websites.mdx
7. Dify Docs (GitHub): Web app settings (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/publish/webapp/web-app-settings.mdx
8. Dify Docs (GitHub): MCP Server (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/publish/publish-mcp.mdx
9. Dify Docs (GitHub): Get Started with the Dify API (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/api-reference/guides/get-started.mdx
10. Dify Docs (GitHub): Agent API guide (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/api-reference/guides/agent.mdx
11. Dify Docs (GitHub): Chatbot and legacy Agent API guide (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/api-reference/guides/chat.mdx
12. Dify Docs (GitHub): Logs (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/monitor/logs.mdx
13. Dify Docs (GitHub): Annotation System (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/monitor/annotation-reply.mdx