CrewAI Tutorial (TypeScript): adding tool use for beginners

This tutorial shows you how to add a real tool to a CrewAI TypeScript agent so it can fetch external data instead of only generating text. You need this when your agent must look up facts, query an API, or perform a deterministic action before answering.

What You'll Need

• •Node.js 18+
• •A TypeScript project already set up
• •crewai installed
• •dotenv installed for environment variables
• •An OpenAI API key in .env
• •Basic familiarity with CrewAI agents, tasks, and crews

Step-by-Step

1. •Install the packages you need and make sure your project can run TypeScript files directly. I’m using tsx here because it keeps the setup simple for beginners.

npm install crewai dotenv
npm install -D typescript tsx @types/node

2. •Create a small tool class that CrewAI can call. The important part is extending Tool and implementing run(), which is where your actual logic lives.

import { Tool } from "crewai";

export class GetWeatherTool extends Tool {
  name = "get_weather";
  description = "Get the current weather for a city";

  async run(city: string): Promise<string> {
    const fakeWeather = {
      london: "12°C and cloudy",
      paris: "15°C and sunny",
      tokyo: "18°C and clear",
    };

    const key = city.toLowerCase();
    return fakeWeather[key] ?? `No weather data found for ${city}`;
  }
}

3. •Wire the tool into an agent. The agent needs to know which tools it can use, so pass the tool instance in the tools array.

import "dotenv/config";
import { Agent } from "crewai";
import { GetWeatherTool } from "./GetWeatherTool";

const weatherTool = new GetWeatherTool();

export const weatherAgent = new Agent({
  role: "Weather assistant",
  goal: "Answer user questions using live-like tool access",
  backstory: "You help users by checking weather information before responding.",
  tools: [weatherTool],
  verbose: true,
});

4. •Create a task that tells the agent to use the tool when needed. Keep the instruction explicit; beginners usually fail here by expecting the model to guess when to call tools.

import { Task } from "crewai";
import { weatherAgent } from "./agent";

export const weatherTask = new Task({
  description:
    "Find the current weather for London using your available tools, then summarize it in one sentence.",
  expectedOutput: "A short natural-language weather summary for London.",
  agent: weatherAgent,
});

5. •Run the crew and print the result. This is the part that proves your tool wiring works end-to-end.

import "dotenv/config";
import { Crew } from "crewai";
import { weatherTask } from "./task";

async function main() {
  const crew = new Crew({
    agents: [weatherTask.agent],
    tasks: [weatherTask],
    verbose: true,
  });

  const result = await crew.kickoff();
  console.log("\nFinal result:\n", result);
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

6. •If you want a more realistic setup, replace the fake lookup with an actual API call inside run(). The shape stays the same, so your agent code does not change when you swap implementations.

import { Tool } from "crewai";

export class HttpWeatherTool extends Tool {
  name = "get_weather";
  description = "Get current weather for a city";

  async run(city: string): Promise<string> {
    const response = await fetch(
      `https://api.example.com/weather?city=${encodeURIComponent(city)}`
    );

    if (!response.ok) {
      return `Weather API failed for ${city}`;
    }

    const data = (await response.json()) as { summary?: string };
    return data.summary ?? `No summary returned for ${city}`;
  }
}

Testing It

Run your script with npx tsx src/main.ts, then watch the verbose logs. You should see the agent reason about the task and call the get_weather tool before producing its final answer.

If it only answers from memory, your task prompt is too vague or the tool description is too weak. Make both explicit about what the tool does and when it should be used.

Also test a city that exists in your tool and one that does not. That confirms both the success path and fallback behavior are working.

Next Steps

• •Replace the mock lookup with a real HTTP API and add retries/timeouts
• •Add a second tool, like currency conversion or policy lookup, and compare how the agent chooses between them
• •Learn how to structure multi-agent crews so one agent gathers data and another drafts the final response

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.