Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Using Dify Agent to Call External Tools: Demonstrating the Complete Pipeline from Tool Definition to Invocation with Weather Query as an Example

In many enterprise scenarios, what users truly need is not just “chatting with AI” but “having AI complete an action based on external capabilities.”

This is precisely where Agent value begins to emerge.

Unlike ordinary Q&A applications, Agent focuses not just on generating a response but on the complete pipeline around task completion:

  • Understanding user intent
  • Determining whether a tool needs to be called
  • Selecting the correct tool
  • Assembling invocation parameters
  • Receiving tool return results
  • Generating the final reply based on those results

To illustrate this pipeline more clearly, weather query is a very typical example. It is simple enough while completely covering the most core capability structure of an Agent calling external tools.

1. What Is “Tool Invocation”

Tool invocation can be understood as: when the model determines it cannot reliably answer a certain question on its own, it obtains information through an external capability and then organizes the result into the final output.

Using weather query as an example, a typical flow looks like:

User: What's the weather like in Tokyo today?
→ Agent determines: This is a question requiring real-time information
→ Calls the weather API
→ Retrieves temperature, weather condition, wind, precipitation probability
→ Generates final answer

This means the key point is not whether the model “knows the weather” but whether the model “knows when it must look up the weather.”

2. Two Common Strategies in Dify Agent

In Dify’s Agent scenarios, tool invocation typically revolves around two approaches:

  • ReAct: The model decides next steps progressively through a “Think -> Act -> Observe” cycle
  • Function Calling: The model directly outputs the tool name and parameters, initiating the call in a structured manner

When ReAct Is More Suitable

  • Task objectives are relatively open-ended
  • Multi-step reasoning is needed
  • Observing the thought process and invocation path is desired
  • Debugging complex behavioral chains is necessary

When Function Calling Is More Suitable

  • Task structure is clear
  • Tool invocation paths are stable
  • Higher requirements for response speed and parameter accuracy
  • Structured output format is required

For tasks like weather query, Function Calling is often more direct; for more open-ended tasks like “provide travel advice combining weather, traffic, and schedule,” ReAct’s flexibility is greater.

3. Why Weather Query Is a Typical Agent Scenario

Weather query possesses all the characteristics of a standard Agent scenario:

  1. The question depends on real-time data
  2. An external API needs to be called
  3. Parameter structure is clear, such as city and date
  4. Return results are structured, such as temperature, weather condition, and precipitation probability
  5. The final result needs natural language expression, not raw JSON

Therefore, weather query is not just a simple example but one of the most suitable introductory cases for understanding the complete Agent tool invocation pipeline.

4. Step One: Define Tool Capabilities

In Dify Agent, a tool is essentially an external capability that can be invoked by the model.

Using weather query as an example, defining a tool requires at least the following three items.

1. Tool Name

For example:

  • get_weather
  • query_weather

The name should be as clear as possible to help the model understand its purpose.

2. Tool Description

For example:

  • Used to query weather conditions for a specified city on a specified date
  • Returns weather condition, temperature, humidity, wind, and precipitation probability

Description quality directly affects whether the model can correctly determine usage scenarios, so it should not be overly generic.

3. Input Parameters

The most common parameters for weather query include:

  • city: City name
  • date: Date
  • unit: Temperature unit (optional)

In enterprise scenarios, the clearer the parameter definitions, the higher the invocation stability.

5. Step Two: Connect to an External Weather API

After tool definition is complete, the next step is connecting to the external service that actually provides the data.

Common connection methods include:

  • Using a public weather API
  • Calling an enterprise internal middleware service
  • Accessing a third-party weather endpoint via HTTP request

The key point at this step is not how complex the API is but ensuring the input/output structure is sufficiently stable.

An ideal return structure typically looks like:

{
  "city": "Tokyo",
  "date": "2026-04-12",
  "condition": "Cloudy",
  "temperature_min": 14,
  "temperature_max": 22,
  "rain_probability": "30%",
  "wind": "Northeast wind, Force 3"
}

For an Agent, the clearer the return structure, the more stable the subsequently generated results.

6. Step Three: Teach the Agent “When to Call a Tool”

In practice, this step is often underestimated.

Many teams focus on “whether the tool is connected” but what truly determines the experience is whether the model knows:

  • Which types of questions must invoke the weather tool
  • Which types of questions can be answered directly based on existing context
  • Whether to ask a follow-up question when parameters are incomplete

A Basic Constraint Example

Rules like these can be added to the system prompt:

When users ask about weather, temperature, rainfall, wind, what to wear, or whether it's suitable for going out -- any weather-related questions -- prioritize calling the weather tool rather than answering from general knowledge.
If the city or date is missing, ask the user first.

The purpose of this is to reduce the model’s subjective guessing in real-time information scenarios.

7. Step Four: Handle Incomplete Input

Real user input is not always complete. For example:

  • “Is it good to go out today?”
  • “What about Tokyo weather?”
  • “Will it rain in Osaka tomorrow?”

In these situations, the Agent needs two basic capabilities.

1. Auto-Complete Inferable Information

For example, “today” can be parsed as the current date.

2. Proactively Ask for Missing Parameters

If the user only says “What’s the weather like” without specifying a city, the system should first ask:

  • “Which city would you like to check the weather for?”

This capability is critical because it directly determines whether the Agent behaves like a usable system rather than a prototype that occasionally succeeds at calling tools.

8. Step Five: Transform Structured Results into Usable Answers

Tools return structured data, but what users truly need are actionable, comprehensible conclusions.

For example, when a user asks:

“Should I bring an umbrella to Tokyo tomorrow?”

The Agent should not mechanically repeat raw JSON but instead output something like:

  • Tomorrow Tokyo will be cloudy turning to light rain, high of 21 degrees C, 60% chance of precipitation. It is recommended to bring an umbrella.

It can go further with more context-appropriate expression:

  • If you have outdoor plans tomorrow, it is recommended to prepare a lightweight umbrella for possible brief showers.

This is also the core difference between an Agent and a plain API call: the tool is responsible for fetching data; the model is responsible for interpreting and expressing it.

9. Why Weather Query Is Typically Better Suited for Function Calling

Weather query is particularly well suited for Function Calling because it has the following characteristics:

  • Clear invocation target
  • Stable parameter structure
  • Clear return value structure
  • No need for long-chain reasoning

Compared to ReAct, it typically has three clear advantages:

  1. Faster response
    Reduces unnecessary thinking text generation.

  2. More stable parameters
    More likely to output structured call parameters that meet requirements.

  3. Lower cost
    Reduces extra token consumption.

Therefore, if the Agent’s tasks are primarily standard actions like “check weather, check inventory, check orders, check prices,” Function Calling is typically the better first choice.

10. Extending from Weather Query to Enterprise Scenarios

Weather query is just a teaching example, but what it represents is actually an entire category of enterprise scenarios:

  • Check inventory
  • Check ticket status
  • Check order progress
  • Check customer information
  • Check meeting room reservations
  • Check reimbursement approval status

These questions share one thing in common with weather query:

They are not about having the model generate answers from nothing, but about having the model call data capabilities first, then organize the results.

Once the weather query pipeline is built clearly, enterprises can typically migrate the same pattern to more internal business systems.

In Agent tool invocation design, one very practical principle is:

Make tools as structured as possible; make the model guess as little as possible.

Specifically, aim to:

  • Write clear tool descriptions
  • Define clear parameters
  • Specify clear return fields
  • Explicitly require “must call tool” for real-time information scenarios
  • Explicitly require “ask first, then call” for missing parameter scenarios

These foundational design choices are often more impactful in improving system reliability than simply switching models.

Conclusion

Using weather query as an example, the complete pipeline for Dify Agent calling external tools can be clearly broken down into:

  • Define the tool
  • Connect to the API
  • Constrain invocation timing
  • Handle parameter completion
  • Organize results into a user-comprehensible answer

The essence of this pipeline is not making the model an omniscient entity but enabling the model to call external capabilities at the right time.

For enterprises, this type of capability is often more important than “better conversation.” Because in real business, the more common need is not “write a more polished paragraph” but:

Help me look it up, retrieve it, make a judgment, and organize the results into output I can use directly.

And this is precisely where the most noteworthy value of Dify Agent and tool invocation lies.