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 TypeScript function with type annotations, turn it into a tool using the tool helper, 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 TypeScript 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 in TypeScript, you use the tool helper from the @openai/agents package. This helper takes an object with several properties:

• name: A string identifier for your tool
• description: A clear description of what the tool does
• parameters: A Zod schema defining the input parameters
• execute: An async function that implements the tool's logic

The parameters property uses Zod schemas to define the structure and types of your tool's inputs. This provides runtime validation and helps the agent understand what data the tool expects. Each parameter can include a description using the .describe() method, which helps the agent understand how to use the parameter correctly.

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

import { tool } from '@openai/agents';
import { z } from 'zod';

const estimateBudget = tool({
  name: 'estimate_budget',
  description: 
    'Estimate the travel budget for a given destination and number of days.',
  parameters: z.object({
    destination: z.string().describe('The travel destination.'),
    days: z.number().describe('Number of days for the trip.')
  }),
  async execute({ destination, days }) {
    const baseCost = 150.0;
    const multiplier = 
      ['switzerland', 'norway'].includes(destination.toLowerCase()) ? 2.0 : 1.0;
    return `$${baseCost * days * multiplier} USD`;
  }
});

In this example, the function takes a destination and a number of days and returns a string representing the estimated budget. The Zod schema and descriptions make it easy for the agent to understand how to use this tool.