CrewAI Tutorial (TypeScript): handling async tools for intermediate developers

This tutorial shows how to build a CrewAI TypeScript agent that uses async tools correctly, without blocking the workflow or returning half-finished results. You need this when your tool calls hit external APIs, databases, or internal services that return promises and you want the agent to wait for real data instead of guessing.

What You'll Need

• •Node.js 18+
• •TypeScript 5+
• •crewai package installed in your project
• •dotenv for loading API keys
• •An OpenAI API key in .env
• •A working TypeScript project with tsconfig.json
• •Basic familiarity with CrewAI agents, tasks, and crews

Step-by-Step

1. •Start with a minimal TypeScript project and install the packages you need. For async tools, the important part is that your runtime supports native async/await cleanly.

npm init -y
npm install crewai dotenv
npm install -D typescript ts-node @types/node
npx tsc --init

2. •Add your environment variables and make sure they load before anything else runs. If you skip this, your model client or tool integrations will fail at runtime.

OPENAI_API_KEY=your_openai_key_here

import "dotenv/config";
import { Agent, Crew, Task } from "crewai";

3. •Create an async tool as a normal async function. The key detail is that the tool must return a resolved value, not a raw promise object or a callback-style wrapper.

type WeatherResult = {
  city: string;
  temperatureC: number;
  condition: string;
};

export async function getWeather(city: string): Promise<WeatherResult> {
  await new Promise((resolve) => setTimeout(resolve, 500));

  return {
    city,
    temperatureC: 24,
    condition: "Partly cloudy",
  };
}

4. •Wrap that async function in a CrewAI-compatible tool object and wire it into an agent. In TypeScript, keep the tool signature explicit so the agent gets predictable inputs and outputs.

import { Agent } from "crewai";
import { getWeather } from "./weather-tool";

const weatherTool = {
  name: "get_weather",
  description: "Fetches current weather for a given city.",
  execute: async (input: { city: string }) => {
    return await getWeather(input.city);
  },
};

const agent = new Agent({
  role: "Weather Analyst",
  goal: "Summarize weather conditions accurately",
  backstory: "You analyze weather data for customer support workflows.",
  tools: [weatherTool],
});

5. •Create a task that forces the agent to use the tool instead of inventing an answer. This is where async handling matters most, because the task may wait on network I/O before producing its final response.

import { Task } from "crewai";

const task = new Task({
  description:
    "Get the weather for Nairobi using the weather tool and summarize it in one sentence.",
  expectedOutput: "A concise weather summary for Nairobi.",
  agent,
});

6. •Run the crew and await the result end-to-end. If you forget await, you’ll see unresolved promises or exit before the tool finishes.

import { Crew } from "crewai";

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

  const result = await crew.kickoff();
  console.log(result);
}

main().catch((error) => {
  console.error("Crew execution failed:", error);
  process.exit(1);
});

Testing It

Run the file with npx ts-node src/index.ts or compile it first with npx tsc and execute the output with Node. You should see a final summary that reflects the mocked weather data returned by the async tool.

To verify async behavior, add a longer delay inside getWeather and confirm the crew still waits for completion before printing output. If you want stronger validation, log inside the tool and confirm it fires before crew.kickoff() resolves.

If you get type errors around tool shapes, check your installed CrewAI version first; TypeScript typings can differ across releases. The important test is simple: the agent must receive resolved JSON-like data from the tool, not an unresolved promise.

Next Steps

• •Add retry logic and timeouts around external API calls in your tools.
• •Validate tool inputs with Zod before calling downstream services.
• •Chain multiple async tools in one crew and compare sequential vs parallel execution patterns.

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.