CrewAI Tutorial (TypeScript): building prompt templates for beginners

This tutorial shows you how to build reusable prompt templates in CrewAI with TypeScript, then wire them into agents and tasks so your prompts stay consistent and easy to maintain. You need this when your team keeps rewriting the same instructions for different agents, or when you want beginner-friendly prompts that are structured, predictable, and easy to swap out.

What You'll Need

• •Node.js 18+
• •A TypeScript project with ts-node or a build step
• •CrewAI TypeScript package installed
• •OpenAI API key set in your environment
• •Basic familiarity with:
  • •Agent
  • •Task
  • •Crew
  • •async/await in TypeScript

Install the dependencies:

npm install @crewaii/core dotenv
npm install -D typescript ts-node @types/node

Set your environment variable:

export OPENAI_API_KEY="your-key-here"

Step-by-Step

1. •Start by defining a prompt template as a plain function. Keep it small and explicit so beginners can read it without guessing what each placeholder does.

// promptTemplates.ts
export type BeginnerPromptInput = {
  topic: string;
  audience: string;
  tone?: string;
};

export function buildBeginnerPrompt(input: BeginnerPromptInput): string {
  const tone = input.tone ?? "clear and friendly";

  return `
You are writing for a beginner.

Topic: ${input.topic}
Audience: ${input.audience}
Tone: ${tone}

Rules:
- Explain one idea at a time.
- Avoid jargon unless you define it.
- Use short paragraphs.
- Include one simple example.
`.trim();
}

2. •Create an agent that uses the template output as its system-style instruction. In CrewAI, the agent should stay focused on role and behavior; the template fills in the task-specific context.

// agent.ts
import { Agent } from "@crewaii/core";
import { buildBeginnerPrompt } from "./promptTemplates";

const systemPrompt = buildBeginnerPrompt({
  topic: "prompt templates",
  audience: "TypeScript developers new to CrewAI",
});

export const beginnerWriter = new Agent({
  name: "beginner-writer",
  role: "Technical writer for beginners",
  goal: "Produce clear beginner-friendly explanations",
  backstory: systemPrompt,
});

3. •Define a task that passes concrete input into the same template. This is the part most teams get wrong: they hardcode prompts instead of generating them from a reusable builder.

// task.ts
import { Task } from "@crewaii/core";
import { beginnerWriter } from "./agent";
import { buildBeginnerPrompt } from "./promptTemplates";

const taskPrompt = buildBeginnerPrompt({
  topic: "building prompt templates in CrewAI",
  audience: "a developer who already knows CrewAI basics",
  tone: "practical and direct",
});

export const writeGuideTask = new Task({
  name: "write-guide-task",
  description: taskPrompt,
  expectedOutput:
    "A short beginner-friendly guide with clear steps and one example.",
  agent: beginnerWriter,
});

4. •Assemble the crew and run it from an executable entry point. Keep the runtime code thin so you can reuse the same template functions across multiple tasks later.

// index.ts
import "dotenv/config";
import { Crew } from "@crewaii/core";
import { writeGuideTask } from "./task";

async function main() {
  const crew = new Crew({
    name: "prompt-template-demo",
    tasks: [writeGuideTask],
  });

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

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

5. •If you want better reuse, split templates by purpose instead of by agent. That makes it easier to support multiple outputs like summaries, FAQs, or onboarding notes without duplicating prompt text.

// templates.ts
export function makeExplainerTemplate(topic: string): string {
  return `
Explain "${topic}" to a beginner.

Requirements:
- Start with a plain-English definition.
- Give a real-world use case.
- End with a short checklist.
`.trim();
}

export function makeComparisonTemplate(a: string, b: string): string {
  return `
Compare "${a}" and "${b}" for a beginner.

Requirements:
- Use a table.
- Highlight when to use each one.
- Keep language simple.
`.trim();
}

Testing It

Run the project with npx ts-node index.ts and confirm you get a non-empty response back from CrewAI. If the output is vague, check whether your template includes enough constraints like audience, tone, and formatting rules.

Then change one value in buildBeginnerPrompt, such as tone, and rerun it to verify the output changes predictably. That tells you your prompt builder is actually driving behavior instead of being ignored.

If you see runtime errors, check three things first:

• •OPENAI_API_KEY is set
• •package names match your installed version
• •your TypeScript files are importing from the same module path consistently

Next Steps

• •Add validation with zod so your template inputs cannot be malformed
• •Build separate templates for summarization, Q&A, and extraction tasks
• •Add test coverage around prompt builders so changes don’t silently break output quality

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.