Building Intelligent Task Routers

Introduction & Context

Welcome back! In the previous lesson, you learned how to use prompt chaining to connect multiple GPT-5 API calls in a linear sequence, breaking down complex tasks into manageable steps. This approach works well when you know exactly what sequence of operations is needed. However, real-world applications often face unpredictable requests that require different types of expertise. Instead of building separate chains for every possible request, routing workflows use GPT-5 to analyze incoming requests and intelligently direct them to the right specialist — such as a math expert, a writing expert, or a code expert. This lesson will show you how to build a flexible routing system that maintains high-quality responses by leveraging specialized instruction prompts for each domain.

Workflow Design at a Glance

The routing workflow follows a clean two-step pattern that's more dynamic than the linear chains you've used before. When a user submits a request, your system first sends it to a router — a GPT-5 instance with a specialized instruction prompt designed to classify the request type. The router analyzes the content and returns a decision about which specialist should handle it. Once you have the routing decision, you send the original user request to a second GPT-5 instance configured with the appropriate specialist instruction prompt. This specialist focuses entirely on providing the best possible response within their domain of expertise, whether that's solving equations, crafting stories, or debugging code. The key insight here is that you're using the same OpenAI API and the same GPT-5 model for both calls, but with completely different instruction prompts that give each instance a distinct role and expertise. The router acts as a classifier, while the specialist acts as a domain expert. This separation of concerns makes your system both more reliable and easier to extend with new specialist types.

Crafting the Router Prompt

The router prompt is the critical component that determines how accurately your system classifies incoming requests. Unlike the open-ended prompts you might use for creative tasks, router prompts need to be strict and constrained to ensure reliable, parseable output. Your router instruction prompt should establish GPT-5's role as a decision-maker and provide clear, unambiguous options. Here's an effective approach that limits the router to exactly three choices: TypeScript const routerPrompt = `You are a task router. Your job is to analyze user requests and determine which specialist should handle them. Available specialists: - math_specialist: For mathematical calculations, equations, and numerical problems - writing_specialist: For creative writing, essays, stories, and text composition - code_specialist: For programming questions, code review, and technical implementation Respond with ONLY the specialist name (math_specialist, writing_specialist, or code_specialist) that best matches the user's request.`; The phrase Respond with ONLY is crucial because it prevents GPT-5 from adding explanatory text or reasoning that would complicate parsing the response. You want exactly one of three possible strings, nothing more. The explicit list of specialist names with their descriptions helps GPT-5 understand the boundaries between categories and reduces ambiguous classifications. Notice how each specialist description focuses on clear, distinct domains. Mathematical problems are clearly different from creative writing, which is clearly different from programming tasks. This separation reduces edge cases where the router might struggle to choose between specialists.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Defining Specialist System Prompts

Each specialist needs a focused instruction prompt that establishes their expertise and approach. Unlike general-purpose prompts, specialist prompts should be concise and role-specific to maximize performance within their domain.

Your math specialist prompt should emphasize precision and clarity in mathematical communication:

TypeScript

const mathSpecialistPrompt = "You are a mathematics expert. You excel at solving equations, performing calculations, and explaining mathematical concepts clearly.";

const mathSpecialistPrompt = "You are a mathematics expert. You excel at solving equations, performing calculations, and explaining mathematical concepts clearly.";

The writing specialist focuses on creativity and engaging communication:

TypeScript

const writingSpecialistPrompt = "You are a creative writing expert. You specialize in crafting engaging stories, essays, and helping with all forms of written communication.";

const writingSpecialistPrompt = "You are a creative writing expert. You specialize in crafting engaging stories, essays, and helping with all forms of written communication.";

The code specialist emphasizes technical accuracy and practical implementation:

TypeScript

const codeSpecialistPrompt = "You are a programming expert. You specialize in writing code, debugging, code review, and explaining technical concepts.";

const codeSpecialistPrompt = "You are a programming expert. You specialize in writing code, debugging, code review, and explaining technical concepts.";

These prompts are intentionally brief because they need to work with a wide variety of requests within their domain. A math specialist might handle anything from basic arithmetic to complex calculus, so the prompt focuses on the general approach rather than specific techniques. This specialization improves both quality and consistency compared to using a generic "helpful assistant" prompt for all request types.

The beauty of this approach is reusability. Once you've crafted effective specialist prompts, you can use them across different projects and routing systems. They become reliable building blocks for more complex AI workflows.

Preparing and Sending the Router Request

To begin the routing workflow, you first prepare the user request and send it to the router. The router is a GPT-5 instance configured with a strict instruction prompt to classify the request.

TypeScript

import OpenAI from "openai";

// Initialize the OpenAI client
const client = new OpenAI();

// Choose a model to use
const model = "gpt-5";

// User request to route
const userRequest = "Write me a short story about robots";

// Step 1: Send request to router to determine which specialist to use
const routerMessages: Array<{ role: "user"; content: string }> = [
  { role: "user", content: userRequest }
];

// Get routing decision from GPT-5
const routerResponse = await client.responses.create({
  model,
  instructions: routerPrompt,
  input: routerMessages,
  reasoning: { effort: "minimal" },
  store: false
});

import OpenAI from "openai";

// Initialize the OpenAI client
const client = new OpenAI();

// Choose a model to use
const model = "gpt-5";

// User request to route
const userRequest = "Write me a short story about robots";

// Step 1: Send request to router to determine which specialist to use
const routerMessages: Array<{ role: "user"; content: string }> = [
  { role: "user", content: userRequest }
];

// Get routing decision from GPT-5
const routerResponse = await client.responses.create({
  model,
  instructions: routerPrompt,
  input: routerMessages,
  reasoning: { effort: "minimal" },
  store: false
});

Here, you set up the OpenAI client, specify the model, and construct the message payload. The instructions parameter contains your router prompt that tells GPT-5 how to classify requests, while the input parameter contains the actual user message to be classified. The reasoning parameter is set to "minimal" since classification is a straightforward task that doesn't require complex logical analysis. The store: false option prevents persisting the conversation for later retrieval; we'll keep context locally.

Note the type annotation Array<{ role: "user"; content: string }> which ensures TypeScript validates the structure of your messages array. Since this is an async operation, you must use the await keyword to wait for the API response before proceeding.

Introduction & Context

Workflow Design at a Glance

Crafting the Router Prompt

Join the 1M+ learners on CodeSignal

Defining Specialist System Prompts

Preparing and Sending the Router Request

Extracting and Handling the Router's Response

Mapping the Router Decision to a Specialist Prompt

Sending the User Request to the Specialist

Extracting and Displaying the Specialist's Response

Summary and Prep for Practice