Add a Custom Tool¶

A custom tool turns a script into a tool that your agent can call. This guide builds check_weather from a Bash script. The agent sends a city name and the script returns the current weather.

You need a working agent. See Send your first chat message.

Allow the Weather Host in the Sandbox¶

The script runs in the agent container. The network policy of the agent allows the hosts on the allowed list of its sandbox, plus the AgentZ services. The script calls wttr.in, so you add that host first.

In the workspace sidebar, select Workspace settings, then Sandboxes. Open the row menu of the sandbox your agent uses and select Edit. The Update sandbox page opens.
Select Next until you reach the Allowed hosts step. Type wttr.in in Host and select Add allowed host.
Select Update sandbox. The message "Sandbox updated" appears.
Wait until the agent status changes from Progressing to Idle.

The jq and curl packages are in the Required package set of a sandbox. The script uses both.

Write the Script¶

Save this script as check_weather.sh on your computer.

#!/usr/bin/env bash

city=$(jq -r '.city | @uri')
curl --fail --silent --show-error --max-time 20 "https://wttr.in/$city?format=3"

The agent sends the inputs to the script on stdin as JSON. For the input city, the script receives {"city":"Mumbai"}. The jq command reads the city and URL-encodes it. The script prints the result to stdout, and the agent gets that output back. A non-zero exit code returns an error to the agent.

The Script input and output section of the Create tool sheet, with the JSON input for a city and an example script that prints the result — Open Script input and output in the Create tool sheet. Circle 1 marks the JSON that the script receives on stdin. Circle 2 marks an example script, written in Python.

Create the Tool¶

Select Agents and open your agent. Open the Tools tab. The heading Custom tools appears.
Select Create tool. The Create tool sheet opens.
Enter check_weather in Tool name.
Select Script file and choose check_weather.sh. The sheet shows Bash.
Enter Get the current weather for a city. in Description. This text tells the agent when to use the tool.

The Create tool sheet with a Tool name field, a Script file area that accepts .sh, .py and .js files up to 64 KiB, and a Description field, each marked with a numbered circle — Circle 1 marks Tool name, circle 2 marks Script file and circle 3 marks Description.

Select Add input. Enter the name city, set Type to Text and enter the description The city to look up. Turn on Required.

The Create tool sheet after the script upload, with a filled Description and one Text input named city that has Required turned on — Circle 1 marks the uploaded script, circle 2 the description and circle 3 the city input. This screenshot uses a Python script, so it shows Python 3.

Select Create tool. The message "Tool uploaded" appears.

The Applying tools banner shows while the agent restarts with the new tool. The tool then appears in the Custom tools list with its description, script name and input count.

The Tools tab of an agent with the Custom tools list. One row shows the tool check_weather with its description, script name and one input, and the Create tool button sits above the list — Circle 1 marks the new tool row. Circle 2 marks the Create tool button.

Call the Tool in Chat¶

Select New chat and choose your agent.
Send Check weather in Mumbai. The agent calls check_weather with city=Mumbai.

A chat with the message Check weather in Mumbai and a check_weather tool call that shows city=Mumbai — Circle 1 marks your message. Circle 2 marks the tool call with its argument.

Read the reply. It holds one line with the weather for Mumbai.

Warning

The agent runs a custom tool without asking you first. Write scripts that do only what the tool needs.

Read the Call in Lens¶

In the workspace sidebar, select Lens, then Traces. Lens shows what your agents did.
Open the trace for your chat. Click the span of the check_weather call. The panels Tool arguments and Tool result show the call.

The arguments show what the agent sent. The result shows what your script returned.

The trace inspector for a check_weather tool call, with the Tool arguments city Mumbai and the Tool result — Circle 1 marks Tool arguments, circle 2 marks Tool result and circle 3 marks the selected span.

Next Step¶

Continue with Users and invitations.