#Agent

An Agent is a chat app whose model chooses the next step—think, call a tool, read the result, think again—until it can answer. You do not draw the full pipeline. You supply a prompt + tools (and optional knowledge) and cap how many iterations it may take.

That is the same loop as LangChain agents: Model ⇔ Tools. Dify configures the loop in Studio; LangChain uses create_agent and @tool.

flowchart LR
  U[User] --> M[Model]
  M --> T{Tool?}
  T -->|Yes| E[Run tool]
  E --> M
  T -->|No| R[Reply]

Docs also describe a newer Agent that you build once in a sandbox and reuse as a chat app or as a node inside a workflow. This chapter focuses on the basic Agent app; the ideas apply to the Agent node as well.

#Agent vs Workflow

Need control outside, flexibility inside? Wrap a Chatflow around one Agent node that only talks to external systems. Do not draw twenty If-Else branches and ask the model to ignore them.

#Prompts that name tools

Besides persona, say which tools exist, when to use them, and when not to:

You are an internal ops assistant. Decide whether a tool is needed.
- Use search tools for live weather or the web; never invent real-time facts.
- Use the calculator for arithmetic; do not mental-math long expressions.
- Prefer knowledge retrieval for policy questions; do not substitute training memory.
If evidence is missing, say what is missing. Answer in concise English.

Insert variables with / (short text, paragraph, select, number, checkbox, or runtime API values) so one Agent serves many teams. Official tips: persona, output shape, constraints, tool timing, coarse steps.

#Tools, iterations, knowledge

Add Dify Tools (Marketplace / workspace plugins: search, databases, business APIs). Authenticated tools get credentials under Integrations → Tools. The model picks tools per query; naming them in the prompt helps.

Maximum Iterations caps think → tool → observe loops on one request. Higher values finish longer jobs but cost latency and tokens, and can loop. Start small and watch the tool trace in preview.

With knowledge attached: an Agent has no app-level retrieval overlay—each dataset uses its own settings. The model uses dataset descriptions to decide what to query. “2024 travel policy, not payroll” beats “company docs.” Metadata filters stop a full-corpus scan.

#Function Calling vs ReAct

In preview, prefer models that reason well and natively call tools. Agent Settings shows the mode:

Traces differ: Function Calling is cleaner; ReAct may leak reasoning into visible text. Use multi-model debug to compare. History is capped (docs have cited on the order of 500 messages or ~2,000 tokens, dropping oldest)—do not assume day-one context is still there.

#Safety

Tools reach real systems. In production: least-privilege credentials, prompts that forbid destructive actions, human approval for dangerous tools (or move them to a Workflow Human Input node). Logs should show tool names and arguments. Same rule as LangChain: do not hand an agent unsandboxed shell or raw eval.

#Next steps

• Publish & API
• Workflow — come back when you need a fixed graph
• LangChain tools & agents