Introduction & Lesson Overview

Welcome back! In the last two lessons, you learned how to make your OpenAI agents more capable by integrating both hosted tools (like the webSearchTool) and your own custom function tools. These skills allow your agents to access real-time information and perform custom logic, such as calculating a travel budget.

Today, you will take the next step in building modular and maintainable AI systems: turning agents themselves into reusable tools. This approach allows you to create specialized agents for specific tasks and then orchestrate them from a central, main agent. By the end of this lesson, you will know how to convert an agent into a callable tool, add it to another agent’s tool list, and run a workflow in which the main agent delegates tasks to its specialized agent-tools. This modular design is a powerful way to build complex, flexible AI applications.

Recap: From Function Tools to Agent Tools

Let’s quickly review what you have learned so far. In the previous lesson, you saw how to create custom function tools in TypeScript by using the tool function and defining input schemas with zod. This allowed you to register tools with your agent, enabling it to perform custom logic — such as estimating a travel budget — in addition to using hosted tools like webSearchTool.

Now, imagine you want to break down your agent’s responsibilities even further. Instead of having one agent do everything, you can create smaller, specialized agents — each focused on a specific task, such as research or calculations. By turning these agents into callable tools, you can have a central agent delegate tasks to them as needed. This not only keeps your code organized but also makes it easier to maintain and extend your system in the future.

Similarities to Handoffs

While using agents as tools and handoffs both involve interactions between agents, they serve different purposes:

  • Agents as Tools: The central agent retains control and invokes other agents as tools to perform specific tasks. This approach is suitable when the primary agent needs to utilize the capabilities of specialized agents without transferring control.
  • Handoffs: The primary agent delegates control to another agent, effectively transferring the conversation or task to the specialized agent. This method is useful when a task or query is best handled entirely by another agent.

In summary, using agents as tools allows for the integration of specialized agents into a workflow while maintaining control within the central agent, whereas handoffs involve transferring control to another agent to handle specific tasks or queries.

Converting an Agent into a Callable Tool

To turn an agent into a tool in TypeScript, you use the .asTool() method. This method wraps your agent so it can be called just like any other tool, such as a function tool or a hosted tool. When the main agent decides to use this tool, it will invoke the specialized agent, get its result, and then continue its own workflow.

Let’s look at a simple example. Suppose you have a travel researcher agent that specializes in searching for the latest travel news. You can define this agent as follows:

To make this agent available as a tool, you call its .asTool() method. You can also give it a custom name and description, which helps the main agent understand when to use it:

Now, researcherTool can be added to another agent’s tool list, just like any other tool.

Integrating Callable Agent Tools into a Main Agent

Once you have converted your specialized agent into a tool, you can add it to a main agent’s list of tools. This allows the main agent to delegate specific tasks to the specialized agent whenever it decides it is appropriate.

For example, you can create a main agent that includes the researcher agent as a tool, alongside other tools:

With this setup, the main agent can decide when to call on the researcher agent for up-to-date information and when to use the budget estimator for calculations. This modular approach keeps each agent focused on its own task, while the main agent orchestrates the overall workflow.

Running and Displaying Modular Agent Tool Results

Let's see how the main agent leverages both a specialized researcher agent (as a tool) and a budget estimator in a real scenario. Here’s how you can run the orchestrated agent and display its output:

In this example, the main agent analyzes the user's question and determines that it needs to both research current snow conditions and estimate a travel budget. Thanks to the modular setup, it can delegate the research to the specialized agent-tool and the calculation to the budget estimator. The response might look like:

This output demonstrates how the main agent orchestrates multiple tools — calling the researcher agent for up-to-date information and the budget estimator for calculations — then combines their results into a single, helpful answer.

Examining the Agent Delegation and Tool Execution Flow

To understand how the main agent delegates tasks, start by running your orchestrated agent and inspecting the result.history property. This property logs the entire interaction, including the user’s message and all tool calls.

The first part of the history shows the user’s message as received by the agent:

This entry records the initial user input, which the main agent will analyze to determine which tools to use.

Examining the Main Agent’s Function Calls

Next, the main agent decides which tools to invoke in response to the user’s question. In this example, it calls both the specialized researcher agent-tool and the budget estimator tool:

Here, you can see that the main agent has recognized the need to both research current snow conditions (using the research_destination agent-tool) and estimate a travel budget (using the estimate_budget tool). Each function call is logged with its name, arguments, and status, showing how the agent breaks down the user’s request into actionable tasks.

Viewing Tool Call Results

After the main agent calls its tools, the results from each tool are recorded in the history. This includes the outputs from both the researcher agent-tool and the budget estimator.

This section of the history shows the results returned by each tool. The research_destination agent-tool provides a detailed summary of the current snow conditions in Switzerland, while the estimate_budget tool returns the estimated cost for a 7-day trip. These outputs are then available for the main agent to use in its final response.

Final Agent Response

Finally, the main agent combines the results from its tools and generates a single, coherent response for the user. This is also recorded in the history.

This final message is what the user sees. The main agent has synthesized the information from both the researcher agent-tool and the budget estimator, presenting a clear and helpful answer that addresses both parts of the user’s question.

Notes on Tool Call Visibility

You might notice that you do not see the call to the webSearchTool in this history. When an agent is used as a tool (like research_destination), only the top-level tool call is shown in the main agent's history. The internal steps taken by the specialized agent—including any calls it makes to its own tools—are recorded in that agent's own history, not in the main agent's history.

If you want to inspect the detailed steps taken by the researcher agent (including its use of webSearchTool), you would need to access the history of that agent's execution separately. This separation keeps the main agent's history focused on orchestration and delegation, while the details of each specialized agent's workflow are encapsulated within that agent. This modular approach makes it easier to manage complex workflows and debug individual agent behaviors as needed.

Summary & What’s Next

In this lesson, you learned how to turn agents into reusable tools using the .asTool() method and how to orchestrate them from a main agent. This modular approach allows you to build more organized, maintainable, and powerful AI systems, where each agent focuses on a specific task and the main agent coordinates the workflow.

You also saw how to run the orchestrated agent, inspect its tool-call flow, and understand how the main agent delegates tasks to its specialized agent-tools. This is a key skill for building complex applications that require multiple steps or areas of expertise.

In the next set of exercises, you will get hands-on practice creating your own agent-tools and integrating them into a main agent. Keep experimenting and exploring — this modular approach opens up many possibilities for building advanced AI solutions!

Sign up
Join the 1M+ learners on CodeSignal
Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal