Building our First Tool

At the end of this guide, we will have an agent that writes poems based on today's date. The agent will use a Tool to obtain the date, and write a poem in a style specified by the user.

The finished board is just below and you're welcome to play with it first. When you run it for the first time, it will ask you for the Gemini API Key. Get it at https://aistudio.google.com/app/apikey.

Link

What are Tools?

One of the most powerful ideas in Breadboard is that boards are composable. We often start boards with some fundamental building blocks, things like inputs and outputs, templating, or fetching data, but very quickly we start to compose these baseline components into boards.

Suppose, then, that we make a board that does one thing really well. Maybe it gets the weather for a given location, or maybe it writes some data to a spreadsheet. It could even be as simple as getting today’s date. This board becomes a meaningful “component” in its own right, and something we will likely want to re-use in future projects.

These boards are our Tools.

The good news is that, within Breadboard, boards can call other boards! When there’s a task that we want our board to accomplish we don’t need to reinvent the wheel if there’s another one that already does the task admirably. The Specialist component (found in the Agent Kit) can be handed an array of Tools to choose from to complete its task.

Let's create a Tool and ask a Specialist to make use of it.

Link

Step 1. Create the main board

Let’s create a blank board in the Breadboard Visual Editor by clicking on the menu icon in the top left corner and choosing the New board option.

When we create the board, we can give a title "Rhyme of the Day". The generated board file name can be left as-is.

Now we've created a board, we can use the Board Details pane to set the description to "Creates a poem based on today's date".

Let's add a Specialist. We can drag one of these from the quick selection bar in the bottom corner of the Visual Editor. It's the one with the little robot icon! 🤖

Now we can wire the Poet in. Delete the wire that connects the input to the output, and then drag a wire from input to the Poet, and Poet to the output.

Let’s also change the Specialist's name to "Poet", and let's set its Persona to:

You write wonderful poems that incorporate today's date.

Our board now looks like this.

Let's run the board by clicking the Run button in the lower right part of the Visual Editor and put something like this in the input box:

Give me a poem about today.

Well, we may get a poem, but we immediately discover that our Poet doesn’t really know what today’s date is. If your output is anything like mine, it will look like this:

That's disappointing! So how do we solve this problem? With another board that provides the date and time, and which our Poet can call into as a Tool.

Link

Step 2. Create a Tool Board

Let’s make a new board and call it something like Today’s Date. Let’s update the description for the board. We’ll enter:

Returns the exact date and time in the current timezone

We'll also want to check the box in the Board details pane that declares that this board is a Tool.

What needs to be on our board? Only two things, really: a runJavascript component which will emit the date as a string, and an Output component to collect its value. We don’t need any inputs from the user, so we can delete the Input component that we got when we made a new board. Now, let’s head to the selector in the bottom left corner where we got our Specialist, click on + Nodes, enter runJavascript in the search and drag one of them out onto the editor.

Let's rename it to "Date Retriever" and wire it to the Output component. Let’s also set the Output's type to “String”, since that’s what we’ll be returning from our runJavascript component.

We should also see that the Date Retriever runJavascript component is configured with a “name”, which is the JavaScript function we want to be invoked. By default that name is set to “run”, which is fine for our purpose. We fill in the “code”, which should look something like this:

const run = () => new Date().toString();

This means we now have a run function that can be called, and which will return today's date as a string.

After we wire things together our board should look like this:

Let's run it and see what we get.

Excellent! Let's save it and go back to our original board, where we will teach the Specialist to use our new Tool.

Link

Step 3. Teaching Specialists to use Tools

Once we're back in our original board, let’s create a new Specialist whose role is to get the date and time for us. We’ll rename the Specialist to “Date Retriever” and let’s enter the following in the Input pane for the Persona:

You invoke tools to answer queries.

And this for the Task:

Use the tool to get today's date.

And now in the tools section, let’s create an array, and let’s set an entry to point at our newly-minted Date Retrieval Tool, meaning that our new Specialist's configuration should look like this:

Link

Step 4. Updating the Poet

Finally let’s update the Poet so that it knows to use the date from the Date Retriever Specialist:

Write a poem for the user in the style requested, using today's date.
If the user doesn't provide a style, feel free to choose your own.

And now let’s wire the input to the Date Retriever, and the Date Retriever to the Poet, meaning the final board should look like this:

Now let’s run it.

In our poet’s task we said the user might request a style, so let’s put in “limerick” and see what we get.

There once was a date, June the twenty-seventh,
A day full of sunshine and mirth.
With summer's sweet breeze,
And rustling of trees,
It felt like a brand new earth.

We can also try it "In the style of William Wordsworth" and we may get something like:

The sun, a golden orb in skies of blue,
Hangs high above, a summer's gentle hue.
It is the twenty-seventh day of June,
And nature sings her song, a sweet commune.

The fields are green, with barley tall and strong,
While larks ascend, their melodies prolong.
A gentle breeze whispers through rustling leaves,
And peace descends, as slumber nature weaves.

The world is still, in quiet contemplation,
A day for rest, and joyful celebration.
For summer's bounty fills the air with scent,
And life itself, a wondrous gift, is sent.

So let us pause, and marvel at the day,
And breathe the air, in gratitude we pray.
For on this day, in June's sweet, golden light,
We find a peace, that makes our spirits bright.

Fantastic – we get poems that incorporate today's date!

So we’ve created two boards: one that is a Tool to get today’s date, and another that uses it to create a poem based on today's date. From here we could expand on our prompting, and maybe have the Poet incorporate other information, like the timezone or the year. We could also pass it -- say -- images as part of our input and ask it to use that, too.

Link

Bonus Points – Remix your own Poet!

If you want a fun challenge, see if you can figure out how to make the Tool take a date and return the day of the week. Combine that with a year and maybe a name, and you could turn it into a birthday poem generator for a friend or family member! 💖