Skip to content
Trace
Resources

Build your first agent

From a blank canvas to a working run, then a tool, then a fix when it breaks.

An agent is a small program that takes a message, asks an AI model what to do, sometimes uses a tool, and answers. In the Agent Builder you build one out of blocks on a canvas, run it, and read exactly what each block did.

This tutorial has four parts. Each one ends with something that runs.

  1. Run the starter agent.
  2. Change what it says.
  3. Give it a calculator.
  4. Break it on purpose and read the run.

You need a Trace account and about 30 minutes. Chromebooks, touch screens, and keyboards all work.

Part 1: Run the starter agent#

  1. Press Agent Builder in the sidebar.
  2. Press Create agent.
  3. In "Start a new agent", pick One agent that answers. It has three blocks.
  4. Name it. Press the title at the top of the editor and type a name, for example "My first agent".

You are now looking at the canvas. Three panels:

  • Left is Blocks, the list of blocks you can add.
  • The middle is the canvas, where blocks sit and get connected.
  • Right is Block details. Press a block and its settings appear here.

The starter has three blocks joined by cables. On Message is where a run begins. It passes the message to Base Agent, which thinks, uses its tools, then answers. Show User puts the answer in the chat.

Press Use agent at the top right. A drawer opens on the Chat tab. Type "What is the tallest mountain on Earth?" in the box that says "Message your agent" and press Enter.

The status line says "Running", then the answer appears. While it runs, the active block on the canvas gets an outline, so you can see where the agent is. That is a complete run.

Open the Runs tab. Every run the agent finishes is listed here with how long it took and how many tokens it used. Press one to see what each block did.

Part 2: Change what it says#

The agent's personality lives inside Base Agent.

  1. Close the drawer and press Base Agent on the canvas.
  2. Press the caret on the block (the tooltip says "Open it up and see the parts inside"). The block expands to show what is inside: Inputs, System Prompt, Prompt Builder, Call Model, Stop, and Outputs.
  3. Press System Prompt. In Block details, the Text box says "Be helpful, clear, and age-appropriate."
  4. Replace it with your own instruction. Try: "You are a pirate. Answer every question in pirate speech, in two sentences or fewer."

The editor saves on its own. The word at the top of the editor changes from "Not saved yet" to "Saving…" to "Saved". You can also press Save.

Press Use agent and ask the same question. Same facts, different voice.

Now press Call Model inside Base Agent. Model is the AI model that answers. Under Advanced, Temperature controls how varied the answers are. Set it to 0 and ask the same question twice. Set it to 1.5 and do it again.

Part 3: Give it a calculator#

A model is bad at arithmetic. Ask your agent "What is 4,872 times 391?" and check the answer with a real calculator. It is often wrong.

A tool fixes that. A tool is something the model is allowed to use during a run. Trace only offers safe, approved tools. The built-in ones are Calculator, Find a Fact, Read File, Write File, Get Date & Time, and Random Number.

  1. In Blocks, type "calc" in Search blocks.
  2. Drag Calculator onto the canvas. On a touch screen, drag with your finger. On a small screen the block list is behind an Add block button instead.
  3. Look at Base Agent. It has a tray that says "Drag a Tool onto this tray". Drag the Calculator block onto the tray. This is called docking. It makes the three connections a tool needs in one move.

If you would rather see the cables, press Explode wiring at the bottom of the canvas. A tool needs three: Tool Definition into the agent's Tools port (this is what tells the model the tool exists), the agent's Tool Call into the tool, and the tool's Tool Result back into the agent. If you only connect two of them, the model never hears about the tool.

Press Use agent and ask "What is 4,872 times 391?" again. Open the Debug tab. The line at the top counts model calls and Tool calls. You should see one Tool call. The timeline below shows the model asking the calculator, the calculator answering, and the model writing the reply. The answer is 1,904,952.

You can skip the dragging: Agent with a calculator in "Start a new agent" builds exactly this.

Part 4: Break it and read the run#

Errors are part of building. A run that stops tells you where and why.

  1. Press the cable between On Message and Base Agent and press Delete connection in Block details.
  2. Base Agent now shows a dashed dot on its Message port and a warning that it needs a connection. Press Use agent anyway and send a message.

The run stops. The drawer switches to Debug on its own, and the block that stopped gets a red "Stopped here" badge on the canvas. Press the badge. The dialog is titled "Base Agent stopped the run". It shows what went in, what came out, and a line of advice.

Reconnect the blocks. Drag from the round dot on On Message's Message port to the Message port on Base Agent. Dots only join when their colours match. You can also press one dot and then the other, or use Tab to reach a dot and press Enter.

Run again. It works.

Two more things to try:

  • Press Undo at the top (or Ctrl+Z, Cmd+Z on a Mac). Every change on the canvas can be undone, including deleting a block.
  • Open the Versions tab in the drawer. A version is kept each time the agent runs. Restore puts an older one back on the canvas.

Turn it in or share it#

If your teacher assigned this project, press Turn in or share at the top. Under Turn in, pick the assignment and press Submit agent. Your teacher sees the saved agent exactly as it is right now. Editing it later does not change what you turned in.

Under Share, pick a class and press Share with class. Classmates can open it and read it. They cannot change it, and they cannot run it, but they can press Make a copy and build on their own copy. Revoke takes the share away.

Where to go next#

  • Agent that remembers a little adds a Limit History block so the agent only reads the last four turns of the conversation. Try a long chat with and without it.
  • Agent that checks its answer uses Compare and If to send the answer down one of two paths depending on what it says.
  • Add a Note block anywhere. It never runs. Use it to explain your agent to whoever opens it next.

When something goes wrong#

  • "You have run out of AI credits." Tell your teacher. Runs draw on the class balance.
  • "This run reached its time limit" or "Tool-call limit". The agent looped. Lower Max Turns on Call Model, or make the System Prompt more specific about when to stop.
  • "Changed elsewhere" at the top of the editor. The agent was edited in another tab. Reload the page.
  • Anything else: press Help in the sidebar and send a message. Say which agent and what you pressed.