Stop your agents searching your doc on every run

And so that right there is how you're going to put the variable in. We're going to run it and see how that variable works. All right, there it is. It's actually working. It's reading the columns, getting the variables and information.

Agent prompts, or instructions, define the goal of any agent run. If one of your agents isn't working as expected, the issue is almost certainly going to come down to your prompt. So writing clear, precise prompts really is the most important factor in getting your agents to behave reliably. One best practice with agent prompts is including variables in your prompts. For those of you who are not engineers, let's look at what variables are, because they are going to be crucial to getting your prompts and your agents to behave correctly.

A variable is a placeholder inside of your prompt that can change. It could be a date, name or status, and each one can change from one run to the next. Prompt variables work in the same way. They're information in your prompt that can change day to day, or even run to run. Now, you could change it by hand every single run, but that's not scalable, and it's going to lead your agent to fail.

All right, so now that we've learned what variables are, I'm going to show you one practical method of using Superhuman Docs for your agent variables that you can start using with your agents today. If we take a look at my screen, I've got a document template here that is helping a team manage new hires, or onboardees. The idea is that if you're a new hire at a company, there's probably a thousand different events that you're going to have to join: trainings, lunches, all-hands and things like that. So how do we ensure that we get all of those meetings scheduled with hosts? This is a perfect job for an agent. Here you'll see the 10 different events that need to happen, and each one of these events, for each person, needs a host, an individual from the company who already works there, to run it.

So I'm going to show you our agent now, and we're going to see how the variables work inside that prompt and reach back into this document to pull its information. If I go to the agent itself, you'll see it has a role. Its job is scheduling assistant. It has steps. Step one is to access this Superhuman doc for all of the following steps, and step two is where we're going to see our variables come into play. It'll all be clear in a moment.

So this step two is without variables. This is the old, or bad, practice that you should not follow. You'll see here that in step two it gives the agent the instructions that the hosts you can assign to any meeting are as follows, and it lists four different hosts. The problem with this is any time those hosts need to change. Let's say that Scott is fired, or let's say that Steven is out of office, or let's say we hire someone new and we have to add Jordan in here. This is not scalable, because this information can change day by day if someone is let go, someone new is added to the host list, or someone is out of office. So we do not want to do that.

I'm going to show you how we're using variables here instead. Step two instead says I'm going to have the agent query the host table inside of my document to get a list of internal staff and their emails, and only look at staff who are active. And I give it a definition of what those active staff look like as well. So let's go back into our document, and you'll see here I have a host table, and on this host table are all the different individuals that can be hosts.

This works way better. Do changes still need to happen? Yes, but there are a couple of unique advantages that holding the hosts here gives you. Number one, if you have technically savvy people on your team, you can cause automatic updates to this table if you sync it with your HR system. If people are fired, let go or hired, you can have different agents automatically update this table. You cannot have different agents or scripts update this prompt. Everything in this prompt, or instructions field, has to be done manually. Another thing is this Active checkbox. Let's just say you want to quickly say, you know what, Steven shouldn't be doing anything this week because he's out of office. Great, just uncheck it and your agent will respect that. And lastly, this is just an easier, more accessible surface for humans to collaborate and edit data on. If you have different staff who are editing the different hosts, it's way easier to do it here manually than it is to ask everyone to go into the configuration section for an agent.

So that primarily is how you use variables inside of prompts. This is just one best practice in terms of how to construct prompts, but the prompt that I've constructed here is not optimized. There are a lot of problems and issues with it. I don't go into a deep dive on prompts in this, but if you look at the description below this video, there is a huge resource that shows you best practices with prompts, specifically using the Coda or Superhuman Docs MCP, that is going to save you a ton of usage and a ton of tokens. So grab that in the comments or the description below, and let me know if you've got any questions as well.