Creating and Registering Custom Function Tools

Welcome back! In the previous lesson, you learned how to make your OpenAI agents more powerful by integrating hosted tools, such as the WebSearchTool, which allow agents to access real-time information from the web. This was a big step forward, as it enabled your agents to answer questions and provide recommendations using up-to-date data, rather than being limited to what the language model already knows.

Today, you will take the next step: learning how to create and register your own custom function-based tools. This is a key skill for building agents that can do more than just search the web — they can now perform calculations, access your own data, or run any logic you define. By the end of this lesson, you will know how to write a Python function with type annotations, turn it into a tool using the @function_tool decorator, register it with an agent, and see it in action alongside other tools. This will prepare you for the hands-on exercises that follow, where you will practice building and using your own custom tools.

A custom function tool is a Python function that you define and then register as a tool for your agent. Unlike hosted tools, which are provided and maintained by OpenAI, custom tools let you add your own logic and capabilities. This means you can make your agent do things that are specific to your needs, such as calculating a travel budget, looking up information in your own database, or even calling an external API.

While hosted tools are great for general tasks like web search, custom tools are essential when you want your agent to perform actions that are unique to your application or business. For example, if you want your travel assistant agent to estimate the cost of a trip based on your own pricing logic, you can write a function for that and register it as a tool. This flexibility is what makes custom tools so powerful.

To create a custom function tool, you start by writing a regular Python function. It is important to use type annotations for all parameters and the return value, as this helps the agent understand what kind of data the tool expects and produces. You should also write a clear and descriptive docstring, including explanations for each parameter and the return value. This docstring is used by the agent to understand how and when to use the tool.

Once your function is ready, you simply add the @function_tool decorator from the agents module above your function. This decorator transforms your function into a tool that the agent can recognize and call. The decorator automatically uses your function’s name, docstring, and type annotations to generate a schema that the agent can use to decide when and how to call your tool.

For example, here is a function tool that estimates a travel budget:

from agents import function_tool

@function_tool
def estimate_budget(destination: str, days: int) -> float:
    """
    Estimate the travel budget for a given destination and number of days.

    Args:
        destination: The travel destination.
        days: Number of days for the trip.

    Returns:
        The estimated budget in USD.
    """
    base_cost = 150.0
    multiplier = 2.0 if destination.lower() in ["switzerland", "norway"] else 1.0
    return base_cost * days * multiplier

In this example, the function takes a destination and a number of days and returns a float representing the estimated budget. The type annotations and docstring make it easy for the agent to understand how to use this tool.