Tools and Agents: Where Execution Gains Agency

Dify gives a model two importantly different ways to reach beyond text: a defined tool in the workflow, or an Agent v2 run that can reason across tools and context. The focus here is the boundary between those choices—how arguments, credentials, observations, outputs, and failures are controlled—and the judgment it supports: use an explicit tool when the business path is known, and add Agent autonomy only when the variability of the task justifies another execution loop.

A tool is an application-owned contract

A tool call is not simply a sentence telling a model to perform an action. Dify first resolves a tool runtime using tenant, application, user, and invocation context. It knows which provider and tool have been selected, which credentials are available, which parameters are supplied by the application, and which parameters the model is allowed to fill. It then exposes a model-visible schema that is narrower than the complete runtime configuration when hidden or manual values are needed.

That distinction is easy to miss in the support-assistant example. Suppose a branch permits creation of a correction ticket. The model may be allowed to provide a summary and a category. The application may supply the employee identity, workspace context, or credential used to reach the ticketing service. Those values should not be obtained by asking the model to invent them, and they do not need to be exposed as choices in the model's schema. Dify's tool contract keeps the model-generated arguments and the effective invocation inputs in separate layers.

At runtime, the tool engine merges the prepared runtime parameters with the model-supplied values, invokes the selected tool, and sends callbacks for start, execution, and error. The result can be text, JSON, a variable, a log, a retriever resource, or a file. Dify adapts those message types for the workflow or Agent runtime and can persist files produced by an Agent or tool as product-owned file records. The model receives an observation shaped for its next decision; the application retains the richer event and metadata path needed for users and operators.

This is a safety and correctness boundary even when the tool is harmless. A weather lookup may need only a location. A ticket creation action may require an authorization that the model should never control. A file-producing tool may return a binary object whose identity must be resolved before a browser can access it. The server-side contract determines what is valid, which values are hidden, and how an error is represented. A natural-language instruction has none of those guarantees.

The boundary also supports composition. Dify can expose a workflow as a tool, and the runtime increments workflow call depth when that happens. A workflow can therefore reuse a meaningful sub-process without turning every nested call into an unbounded recursive expansion. The visible graph remains the owner of the call, while the tool engine carries the current application and conversation context into the invocation.

Tool handling includes a local transaction boundary, but it is not a distributed transaction. Dify can commit or roll back its own bookkeeping when preparing files or recording tool results. It cannot automatically undo a remote email, ticket, purchase, or database mutation merely because a later node fails.