Add Tools to Your Agent – Playnex Starter Path

Give Your Agent Real Abilities

Tools are how your agent stops being “just a conversational model” and becomes a system that can take action. In modern agent research — including frameworks like ReAct (Reason + Act) and Function Calling — tools are the bridge between language and real‑world capability. They allow your agent to read files, write data, scan folders, fetch information, and automate tasks on your machine.

In this step, you’ll add three foundational tools:

readFile — read text from a file
writeFile — write text to a file
listFiles — scan a folder

These may seem simple, but they unlock a new dimension: your agent can now observe and modify the world outside the model.

1. Create `tools.js`

Create a new file to hold your tools:

touch tools.js

Add the following code:

import fs from "fs";
import path from "path";

export const tools = {
  readFile: (filePath) => {
    return fs.readFileSync(filePath, "utf8");
  },

  writeFile: (filePath, content) => {
    fs.writeFileSync(filePath, content, "utf8");
    return "File written successfully.";
  },

  listFiles: (folderPath) => {
    return fs.readdirSync(folderPath);
  }
};
      

These synchronous tools are perfect for learning. Later, you can expand them into more advanced, asynchronous, schema‑validated tools similar to those described in the Ollama Tools API .

2. Update Your Server to Use Tools

Open server.js and import your tools:

import { tools } from "./tools.js";

Then add a new endpoint that executes tools on demand:

app.post("/tool", (req, res) => {
  const { name, args } = req.body;

  if (!tools[name]) {
    return res.status(400).json({ error: "Unknown tool" });
  }

  try {
    const result = tools[name](...args);
    res.json({ result });
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});
      

Your agent server can now execute real actions — reading files, writing data, scanning directories, and more.

3. Test Your Tools

List files in a folder:

curl -X POST http://localhost:3000/tool \
  -H "Content-Type: application/json" \
  -d '{"name":"listFiles","args":["."]}'
      

Read a file:

curl -X POST http://localhost:3000/tool \
  -H "Content-Type: application/json" \
  -d '{"name":"readFile","args":["agent.js"]}'
      

Write a file:

curl -X POST http://localhost:3000/tool \
  -H "Content-Type: application/json" \
  -d '{"name":"writeFile","args":["note.txt","Hello from my agent!"]}'
      

When you run these commands, you’re watching the earliest form of agentic behavior: the model decides what action to take, calls the tool, and uses the result. This is the same pattern used in advanced agent frameworks across the industry.

4. Let Your Agent Choose Tools

Now that tools exist, your agent can choose when to use them. In the next step, you’ll build an autonomous loop that lets your agent observe, plan, act, and reflect — the core cycle behind modern autonomous agents.

Troubleshooting

“Unknown tool”

Check the tool name
Ensure it’s exported from tools.js

Permission errors

Some folders require elevated permissions
Try using a folder inside your project

File not found

Use absolute paths or ensure the file exists