Tool calling with external APIs - Writer AI Studio

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

This tutorial walks through building an agent that can intelligently call external APIs to get information and make decisions based on the information. It takes the name of a city and calls several tools and APIs to determine if it’s a good day to view the sunset in that location. If you are unfamiliar with tool calling, you might want to read the Tool calling introduction first to get a sense of how it works.

Interface

Blueprint

While this tutorial uses free public APIs to demonstrate tool calling fundamentals, the tool calling patterns are applicable to real-world enterprise scenarios. You can use these same techniques to connect agents with your CRM, databases, internal APIs, and other business systems.

Agent overview

This agent connects with two free, publicly available APIs:

• Open-meteo for weather information
• Sunrise sunset for sunrise and sunset times

The agent uses tool calling to get the weather information and sunrise and sunset times in a particular city. It then uses the information to determine if it’s a good day to view the sunset, and if so, suggests places to view it.

Clear the demo agent

Before you start building, clear the demo agent that comes with every new Agent Builder project. See instructions for clearing the demo agent in the Agent Builder Quickstart.

Build the UI

The agent has a plain UI with a text input for the city, a button to submit the request, a message block to display a loading message, and a text block to display the results.

1. Add a text input: Drag a Text Input block to the canvas. In the block’s configuration menu, update the following:

   • Label: City
   • Link variable under Binding: city

2. Add a button to submit the request: Drag a Button block to the canvas. In the block’s configuration menu, update the following:

   • Label: Submit

3. Add a message block to display a loading message: Drag a Message block to the canvas. In the block’s configuration menu, update the following:

   • Message: @{status}

4. Add a text area to display the result: Drag a Text block to the canvas. In the block’s configuration menu, update the following:

   • Text: @{final_result}

Build the blueprint

The logic of the blueprint is as follows:

1. The UI Trigger block triggers the agent when the user clicks the button.
2. The set state block adds a loading status to the UI.
3. The tool calling block calls the available tools to get the current date and time, the weather information, and sunrise and sunset times. From the provided information, it makes a determination about whether it’s a good day to view the sunset.
4. Once the tool calling block completes, the agent updates the state with the results and clears the loading message.

Tool calling is a powerful feature that combines the model’s knowledge with real-time data and external APIs. The model can make intelligent decisions by analyzing the data it receives and drawing on its own knowledge to interpret results.

1. Add a UI Trigger block: Drag a UI Trigger block to the canvas. In the block’s configuration menu, update the following:

   • Component Id: Select the Submit button from the dropdown of available components.
   • Trigger: wf-click

2. Add a set state block to add a loading status to the UI: Drag a Set State block to the canvas. In the block’s configuration menu, update the following:

   • Link variable: status
   • Value: %Loading...

3. Add a tool calling block and set the prompt: Drag a Tool Calling block to the canvas. In the block’s configuration menu, update the following:

   • Prompt:

   You are a travel assistant helping someone in @{city} find optimal sunset viewing opportunities.
   
   ## Available Tools
   - `get_weather` - Get weather conditions for today
   - `get_time` - Get current time as a UTC timestamp
   - `get_sunset_time` - Get sunrise/sunset times in UTC
   
   ## Decision Logic
   1. **Check timing**: Use `get_time` and `get_sunset_time` to compare current time with today's sunset
      - **CRITICAL**: Both times are returned in UTC. You MUST convert both to @{city}'s local timezone before comparing
      - **Time comparison steps**:
        a. Get current UTC time using `get_time`
        b. Get sunset UTC time using `get_sunset_time`
        c. Convert BOTH times to @{city}'s local timezone
        d. Compare the local times using 24-hour format
      - **If local current time > local sunset time**: Sunset has passed
      - **If local current time < local sunset time**: Sunset is upcoming
      - **Example**: If current UTC is 23:30 and sunset UTC is 22:45, convert both to local time first. If local current time is 19:30 and local sunset is 18:45, then sunset has passed.
   
   2. **Assess weather conditions**: Use `get_weather` to evaluate:
      - Temperature (comfort for outdoor viewing)
      - Cloud coverage (visibility of sun)
      - Wind speed (viewing comfort)
      - Precipitation chance (weather suitability)
   
   3. **Make recommendation**: If conditions are favorable, suggest 3 outdoor viewing locations in @{city}
   
   ## Tool Usage Notes
   - Both `get_weather` and `get_sunset_time` require latitude/longitude coordinates for @{city}
   - Use your knowledge to provide accurate coordinates
   - Remember to account for @{city}'s timezone when interpreting UTC timestamps
   
   ## Required Output Format
   Provide a structured response including:
   - **If sunset has passed**: Begin by stating "Sunset has already passed for today in @{city}" with the prompt to ask again tomorrow closer to sunset. Otherwise, ignore this section.
   - Current date/time in @{city}'s local timezone, in a user-friendly format
   - Sunset time in @{city}'s local timezone
   - Weather factor analysis with "Good" or "Bad" rating and the values for each factor:
     - Temperature
     - Cloud coverage
     - Wind speed
     - Precipitation chance
   - Overall viewing recommendation
   - If favorable: 3 recommended locations with brief explanations
   

Important Reminder

Always convert UTC timestamps to the local timezone of @{city} before making any time comparisons. Never compare UTC times directly without conversion.

4. **Define a tool to get the current date and time**: Within the **Tool calling** block, click **Add tool+** to define a new tool for the agent to use. Define the tool as follows:
- **Tool type**: `function`
- **Tool name**: `get_time`
- **Function tool definition**:

{ "description": "Gets the current time as a UTC timestamp", "parameters": {}, "type": "function" }

5. **Add a Python block to provide the current date and time in UTC**: This example uses a Python block to get the current date and time in UTC using Python’s `datetime` library. Drag a **Python** block to the canvas. In the block’s configuration menu, update the following:
- **Code**:

from datetime import datetime, timezone

utc_datetime = datetime.now(timezone.utc) set_output(utc_datetime)

6. **Add a return value block to return the date and time to the tool calling block**: If you want a tool to return a value to the Tool Calling block, you need to add a **Return Value** block at the end of the tool’s logic. Drag a **Return Value** block to the canvas. In the block’s configuration menu, update the following:
- **Value**: `@{result}`

7. **Define a tool to get the weather information**: Within the **Tool calling** block, click **Add tool+** to define a new tool for the agent to use. Define the tool as follows:
- **Tool type**: `function`
- **Tool name**: `get_weather`
- **Function tool definition**:

{ "description": "Gets information about the weather for day. This includes cloud coverage, precipitation change, wind gusts, and temperature. The return value is a series of arrays for each of those variables, with one value for each hour. The arrays all start at GMT+0 for the first time.", "parameters": { "lat": { "type": "string", "description": "The latitude to request weather data for" }, "long": { "type": "string", "description": "The longitude to request weather data for" } }, "type": "function" }

8. **Add an HTTP Request block to call the Open-meteo API**: Now you need to add a block to call the Open-meteo API. Drag an **HTTP Request** block to the canvas. In the block’s configuration menu, update the following:
- **URL**: `https://api.open-meteo.com/v1/forecast?latitude=@{lat}&longitude=@{long}&hourly=temperature_2m,cloud_cover,precipitation_probability,precipitation,wind_speed_10m&forecast_days=1`

9. **Add a return value block to return the weather information to the tool calling block**: The HTTP Request block returns the weather information in JSON format. You need to add a **Return Value** block to return the weather information to the Tool Calling block. Drag a **Return Value** block to the canvas. In the block’s configuration menu, update the following:
- **Value**: `@{result}`

10. **Define a tool to get the sunrise and sunset times**: Within the **Tool calling** block, click **Add tool+** to define a new tool for the agent to use. Define the tool as follows:
- **Tool type**: `function`
- **Tool name**: `get_sunset_time`
- **Function tool definition**:

{ "description": "Gets info for about the sunset and sunrise times at a given location based on latitude and longitude", "parameters": { "lat": { "type": "string", "description": "The latitude to request weather data for" }, "long": { "type": "string", "description": "The longitude to request weather data for" } }, "type": "function" }

11. **Add an HTTP Request block to call the Sunrise Sunset API**: Now you need to add a block to call the Sunrise Sunset API. Drag an **HTTP Request** block to the canvas. In the block’s configuration menu, update the following:
- **URL**: `https://api.sunrise-sunset.org/json?lat=@{lat}&lng=@{long}&tzid=UTC&date=today`

12. **Add a return value block to return the sunrise and sunset times to the tool calling block**: The HTTP Request block returns the sunrise and sunset times in JSON format. You need to add a **Return Value** block to return the sunrise and sunset times to the Tool Calling block. Drag a **Return Value** block to the canvas. In the block’s configuration menu, update the following:
- **Value**: `@{result}`

13. **Add a set state block to display the results**: Now that you’ve defined the tools for the Tool Calling block and added the logic to call them, the agent can take the prompt and provided tools and make a determination about whether it’s a good day to view the sunset. Drag a **Set State** block to the canvas. In the block’s configuration menu, update the following:
- **Link variable**: `final_result`
- **Value**: `%@{result}`

14. **Add a set state block to clear the loading message**: Finally, you need to add a block to clear the loading message when the Tool Calling block completes. Drag a **Set State** block to the canvas. In the block’s configuration menu, update the following:
- **Link variable**: `status`
- **Value**: Leave empty to clear the state variable.

## Preview the agent

Navigate to the **Preview** tab to test the agent. Enter a city and click the Submit button to see the agent’s response. You should first see the loading message, then the final results when the Tool Calling block completes.

### Conclusion

This tutorial demonstrates the basics of tool calling with external APIs. To continue improving on this agent, you might consider adding a **Structured Output** block after the Tool Calling block to ensure the agent returns the results in the correct format.