OpenAI's Agents SDK | Tools and Agents-as-Tools Explained

In this chapter of the agents SDK course, we are going to be taking a look at tools. Now for tools in agents SDK, there are various ways that we can use them. First, we have pre-built tools. So there is a small number of these pre-built tools that come with agents SDK. They are OpenAI built and they allow us to do a few interesting things. Then there are of course custom tools. So we can define our own tools and use those as well. So in this chapter we'll work through those and take a look at how we use tools and how we can best use tools in agents SDK. So for this notebook I would recommend actually you can open this one in collab or if you prefer run it locally. It is completely up to you. We of course will need the OpenAI API key unless you're using a another provider. Although with another

provider, I will note that these pre-built tools will not work. So yeah, you have to be using OpenAI models to use these. So there are a few of these pre-built tools from agents SDK. Those include the web search tool, the file search tool, and computer use tool among others. And we're just going to take a quick look at the web search tool which we briefly used in the previous example. So when we're passing tools to our agent, we define an agent object. We pass a name instructions as we would usually do. We also pass a model But then we also provide tools. Okay. And this is just a list of these well they're function tool objects and we'll see that in a moment. Right now, it's just a pre-built web search tool. Another thing to note here is that the nano model is not recommended for tools. So, you should use at least mini ideally. Now, we can see which tools an agent object has access to by just looking at the tools attribute. And we'll see a list. In this case, it's just the web search tool that we just defined. And as we usually would do, we use the runner object to run our agent. and get some results from there. So you can see the final output there. So that is today and this all seems relatively recent.

Now although the pre-built tools are, you know, they're really nice that it's nice to have those in most cases. I think the majority of tools we would be using are either defined through MCP or they are custom tools. Custom tools that we are building and we are defining within the framework. Now the way that we do that is we use this function tool object. Now the function tool it's a decorator. We're using it here. Function tool used in this way converts our tool here which is just fetching the time and it's just returning the time for us. So we might use this in the scenario that we need to be able to tell our LM or the LM needs to be able to check time. Maybe the user says a you know what time is it right now or how many days is it until Christmas right the in this case the LM might go and use a fetch time tool in you may also just insert time directly into your system prompt if this is something where you're expecting your agent to be like time aware like a lot of the time or you can just give it a tool to use is depends. So in this case, we're just going to define a function tool for our model to fetch the time. Now one thing if we don't set the name overrider here, this is optional, right? So we can just do you know without that we could just do function tool but in this case the function tool name as provided to our LM will be fetch time. Alternatively, if you want to give it an actual name or a different name to what you what the function is called, you can do that. So, you would just use this name override parameter. I believe also that the name here cannot be it needs to follow like a lowerase with underscores format. So, let's just try that because I don't quite remember. Okay, you can see if we do that, if we don't format that name correctly, we're going to get this. So invalid tools name string does not match pattern. Okay. Uh and it tells you here this is the pattern we're allowed. So we're allowed to have hyphens. We're allowed we are actually allowed uppercase. So we're allowed uppercase lowerase and numbers or all underscores. Okay. So that's good to know. So we could if we wanted to we could just do something like this. That should work. But I'll revert it to what we had before. Okay. Now we can just confirm that this is a function tool object and we see yes our fetch time function is in fact a function tool object. That's great. That means our decorator worked as expected. And because it's a function tool object that means we can we have these specific attributes that we can pull out. So we can get the name which you'll see a moment ago. I I modified this. Let's run this again and we'll see that it's now our underscore name there or a valid name. We can see the description. Hey, that's weird. Where did we set that? So let's come back up a little bit and we can see that the description is being pulled from the dock string. So this dock string here is actually pretty important. it is in here that you describe to your LM how and when it should use a particular tool. Okay. So it's important that you use this and make sure that you describe right in this scenario this is a very simple scenario so it doesn't you know we just write something simple but for example web search in your docking here you should be telling your LLM look this is a web search tool you should use or you should provide as much useful context as possible in your search query this is in natural language if it's a depending on web search engine you're using, right? So, you can give the airline instructions on how to best use your tool within this stock string. That is an important thing. You should always do that. Then we can also check the parameters. So, parameters here we can see okay this function terrible example. It doesn't have any parameters. So, we're going to see okay there's no required parameters. There's just nothing in here. So, uh that's fine. We're going to see later a tool with parameters. Okay, so we have our output class here. We don't necessarily need to use this, but this is this allows us to do structured output. I'm going to run without this first and I'm going to switch to using it. So do this and let's just run this and see what we get. Okay, so something happened. Let's take a look. Okay, so we got this. The current time is this. Now the what I want to show you with that output class is that you can also structure your output. So in this is a you know adding a lot of complexity to a very simple use case here, but it's good for demoing all of this. We want our response. Okay, as we just got that's just our response here. But I also want the LM to tell me why did it do what it did. Okay. So the LM is just going to say okay I used the fetch current time tool because the user asked about the current time so I needed to do that right. So we should see something like that. So yeah we define that both of these outputs are strings. You may also I don't know let's say we want like a confidence score for example that could be a float. Uh yeah you can see thank you co-pilot for writing that for me. You can see the confidence here we have our float this is a confidence level in its response from zero to one. So that can actually be a pretty useful thing to include as well in general. So yeah, this is structured output that we are providing and we provide that via the output type parameter as before. We're going to use that runner object and then let's see what final output is because now we have multiple outputs. So that's going to be a bit different. Okay, we can see output class the response here and we can see the approach taken. and I fetch current time using systems time query function to provide you with the exact end and update time. Okay, that's great. And we see that is the output class that we defined that object. So we can also go in there if we want to access each one of those specific values. We can go in like that. Okay. So we come to here. No, I already printed it here. Never mind. We can print it again. Okay. And we can also use the

function tool object here as well. So you know we can do that with piantic for example. This can be useful if you are wanting to define a particular structure for the input. So you can see here in this example we have these function argu. We're going to be using these function args in a tool which is just gonna multiply two numbers together. Again, super simple example, but nonetheless, really simple example. We have the description for that. So, this is the, you know, where we had the dock string before. But then we also have this params JSON schema, right? Pams JSON schema is consuming what we have up here and using that to describe to our LM what the input parameters are. And this is really useful because by default we can't do that. So if we just define a function and we decorate it with function tool, we can't specify in that function descriptions for each and every parameter. Right? So if you have a set of parameters you need to describe. This is really useful for those more complex use cases. You can describe everything in much more detail using this approach which is pretty good. And you can also validate things as they're coming in as well. So that's great. We do still need to of course define our function that is going to be used. So we have this multiply numbers function here and we would just pass that down here to the on invoke tool. Okay. So we have that. Now we can come down and just see as we did before we can see everything that we have defined. So we get a name and description as before. Okay. We defined these a different way before but the outcome is the same. Okay, so this is the within that function tool object. These are those attributes and then we also have this params JSON schema. This one is a little bit different because now we have parameters. Okay, so within the properties dictionary here before this was empty because we had no parameters. Now there are parameters. We have X and Y and also within those parameters we have descriptions. Okay, so this is all getting sent to the LM. The LM now knows exactly what each one of these parameters is for. Of course, in this example, this is a very basic example, it's not really needed, but for more complicated tools, this is this can be very helpful. We also have this required parameter down here. Now, this is saying, okay, X and Y are both required parameters for this function. So, the LM knows it must generate both of these to use the tool correctly. What may happen, right? You might have optional parameters. So, let's just set one of these to optional very quickly. Let's say, you know, we don't need X for whatever reason. So, we run this. We'll come down to here and we'll now see if we make this scrollable, we see that required is now just a Y. We don't need X. It's an optional parameter, but X is still provided within our streamer here. So, it's still described. the LLM still knows it can use X if it needs to, but it's an optional parameter, so it doesn't have to, which can be really use. Well, you kind of need that in many tools. So, we have that. Um, we of course in this scenario, we are definitely going to keep X as a required parameter. So, rerun those. So, let's just go down here and run our new query. So, we're saying we want to multiply 3. 41 by 7. 2. Let's see what we get here. We can well we we're going to get an object out of this. So I'll just show you that very quickly. So final output. That's because we set output class again down here. And we can see response and approach taken. And we just print both of those out a little more nicely here. Okay. So that's pretty cool. Now the very last

thing we we'll take a quick look at here. We will cover this in a little more detail later. We want to look at agents as tools. So in agents SDK we can use handoffs and agents as tools as ways to handle multi- aent systems. Now agents as tools is what it sounds like. You define an agent and then you actually just provide that agent as a tool for another agent. So in this example, kind of a again silly example because you would just use the tools directly but nonetheless in this example we're going to have our multiply agent which has access to the multiply tool and then we also have a time agent which has access to the fetch time tool. In reality it's you would probably use both of these as more like okay this is my social media agent. It is the agent that is going to read all of my social media things and generate posts for me or make posts for me. And then maybe we have like a writer agent which has been prompted with all this you know writing goodness and maybe can reference you know our past materials to generate a article or a social media post or whatever right and those two agents would work in tandem to you know like read okay what should we talk about I'm going to and then generate a post and you know post out and you know just generate loads of AI slop for everyone to scroll past as they're on uh on X or LinkedIn or whatever else, right? So, you know, you might want to use it or not for that. This example is a little silly in that Yeah, we would just use like you probably won't even use these as tools a lot of the time. Uh but nonetheless, this is how it works. So, coming down here, we've created our two tool agents or sub agents, however you want to call them. And then we're also going to create this orchestrator agent. This is the kind of like the controlling agent. So when you're using agents as tools, you do need like a top level agent. And we actually don't need to provide this information here. We can remove that. So it's just saying, okay, you're an orray agent. You're going to do some stuff. And then we have these two tools which are agents, right? So we just write the multiply agent or the agent name as tool. Then we provide the tool name. So as you know how would we call this and the description for it as well. Let's go ahead and let's put all this together. Let's run and we'll say what time is it. Now when we're using agents as tools just remember that okay we have our orchestrator agent that is going to say I want to use the time agent. Time agent checks time writes a response takes it to the orchestrator agent. Then the orchestrator agent is going to write is going to read that response and then write the response to you. So, it's a tokenheavy approach. Just bear that in mind. The handoffs are a bit lighter and better for that. And we'll look at those pretty soon. So, let's see what we got. And yes, you can see. Okay, cool. So, we can take a quick look at our traces to see what that looked like. So, the multi- aent thing, you can see that two tools we used here. So, we'll go into there. There was two tools were actually the orchestrator agent calling the fetch current time agent and then calling the fetch current time tool. Okay, again I just want to emphasize that this is not the way that you should use sub aents like or agents as tools in agents SDK. This is a very silly example. This is just to show you how it works. We'll see pretty soon more realistic examples, but for now that is actually it. So we've covered tools and you know how we use tools, how we define tool, both built-in and the custom tools and then we've also seen how we can use agents as tools. So that's it for this chapter. I will see you in the next one. Thanks.