Forem: Aba Nicaisse

Quickselect: find the k-th smallest element in O(n), no sorting required

Aba Nicaisse — Mon, 20 Apr 2026 17:55:22 +0000

The previous article on binary search ended with a claim that probably raised an eyebrow: you can find the k-th smallest element in an unsorted array in O(n) average time, without sorting. If sorting is O(n log n), how does selection get away with O(n)? The answer is quickselect, and understanding it will permanently change how you think about the divide-and-conquer family.

1. The problem sorting solves that you didn't actually need to solve

When you sort an array to find the k-th smallest element, you're answering a much bigger question than the one you asked. Sorting establishes the complete order of every element. Finding the k-th smallest only requires establishing the relative order of one element.
That's the key insight. You don't need everything in place. You just need to know that the element at index k has exactly k - 1 elements smaller than it and n - kelements larger. Quickselect exploits this.

2. Partition: the primitive that powers both quicksort and quickselect

Both algorithms are built on the same subroutine: partition. Given an array and a pivot element, partition rearranges the array so that:

Every element to the left of the pivot is smaller than it
Every element to the right is larger
The pivot is at its final sorted position

Crucially, and this is the part that enables O(n) selection, the pivot's final index is now known. You don't need to recurse into both halves. You only recurse into the half that contains k.

// Partition using Lomuto scheme
// Moves pivot to its correct sorted position and returns that index
function partition<T>(
  arr: T[],
  lo: number,
  hi: number,
  compare: (a: T, b: T) => number
): number {
  const pivot = arr[hi];
  let i = lo - 1;

  for (let j = lo; j < hi; j++) {
    if (compare(arr[j], pivot) <= 0) {
      i++;
      [arr[i], arr[j]] = [arr[j], arr[i]];
    }
  }

  [arr[i + 1], arr[hi]] = [arr[hi], arr[i + 1]];
  return i + 1; // pivot is now at its final sorted index
}

Notice the comparator parameter, this makes the function generic. The same partition works for numbers, strings, objects sorted by a field, anything.

3. Quickselect: the full implementation

With partition in hand, quickselect is almost trivially simple:

// Returns the k-th smallest element (1-indexed) in O(n) average time
// Mutates the input array — pass a copy if the original must be preserved
function quickselect<T>(
  arr: T[],
  k: number,
  compare: (a: T, b: T) => number = defaultCompare
): T {
  if (k < 1 || k > arr.length) {
    throw new RangeError(`k must be between 1 and ${arr.length}, received ${k}`);
  }

  return select(arr, 0, arr.length - 1, k - 1, compare); // convert to 0-indexed
}

function select<T>(
  arr: T[],
  lo: number,
  hi: number,
  targetIdx: number,
  compare: (a: T, b: T) => number
): T {
  if (lo === hi) return arr[lo];

  const pivotIdx = partition(arr, lo, hi, compare);

  if (pivotIdx === targetIdx) {
    return arr[pivotIdx]; // pivot landed exactly at k — done
  } else if (pivotIdx < targetIdx) {
    return select(arr, pivotIdx + 1, hi, targetIdx, compare); // k is in right half
  } else {
    return select(arr, lo, pivotIdx - 1, targetIdx, compare); // k is in left half
  }
}

function defaultCompare<T>(a: T, b: T): number {
  if (a < b) return -1;
  if (a > b) return 1;
  return 0;
}

Walk through what happens on each recursive call. After partitioning, the pivot sits at pivotIdx. You compare that to targetIdx the 0-indexed position of the element you want. Three outcomes:

Match: return immediately. Done.
Pivot too low: k is in the right subarray, discard everything left of the pivot.
Pivot too high: k is in the left subarray, discard everything right of the pivot.

You never touch the discarded half again. That's the entire source of the efficiency gain.

4. Why the average case is O(n) and the worst case is O(n²)

This is where most explanations wave their hands. Let's be precise.

Each call to partition scans every element between lo and hi, that's a linear pass. The question is how many elements remain after each partition.

In the average case, a random pivot lands somewhere near the middle. The search space roughly halves each time:
n + n/2 + n/4 + n/8 + ... = 2n → O(n)

A geometric series that converges to 2n. Linear.

In the worst case, the pivot is always the minimum or maximum element; the search space shrinks by only one element per call:
n + (n-1) + (n-2) + ... + 1 = n(n+1)/2 → O(n²)

This worst case occurs on already-sorted input when you always pick the last element as pivot, exactly the implementation above. Here's how to defend against it:

// Median-of-three pivot selection
// Picks the median of lo, mid, and hi — dramatically reduces worst-case probability
function medianOfThreePivot<T>(
  arr: T[],
  lo: number,
  hi: number,
  compare: (a: T, b: T) => number
): void {
  const mid = lo + Math.floor((hi - lo) / 2);

  // Sort lo, mid, hi in place so arr[mid] is the median
  if (compare(arr[lo], arr[mid]) > 0) [arr[lo], arr[mid]] = [arr[mid], arr[lo]];
  if (compare(arr[lo], arr[hi]) > 0) [arr[lo], arr[hi]] = [arr[hi], arr[lo]];
  if (compare(arr[mid], arr[hi]) > 0) [arr[mid], arr[hi]] = [arr[hi], arr[mid]];

  // Place pivot at hi - 1 for Lomuto partition
  [arr[mid], arr[hi]] = [arr[hi], arr[mid]];
}

An alternative is random pivot selection, swap a random element into the hi position before partitioning. This gives O(n) expected time regardless of input order, which is the safer default for production use

function partitionWithRandomPivot<T>(
  arr: T[],
  lo: number,
  hi: number,
  compare: (a: T, b: T) => number
): number {
  const pivotIdx = lo + Math.floor(Math.random() * (hi - lo + 1));
  [arr[pivotIdx], arr[hi]] = [arr[hi], arr[pivotIdx]]; // move pivot to hi
  return partition(arr, lo, hi, compare);
}

One line change. The rest of the algorithm is identical.

5. Real-world usage: it's more common than you think

The median is a k-th smallest element problem where k = Math.ceil(n / 2). Computing the median via sort is O(n log n). Via quickselect it's O(n) average. For large datasets or streaming analytics pipelines, that difference compounds significantly.

// Compute the median of an array in O(n) average time
function median(data: number[]): number {
  if (data.length === 0) throw new RangeError("Cannot compute median of empty array");

  const arr = [...data]; // preserve original — quickselect mutates
  const mid = Math.floor(arr.length / 2);

  if (arr.length % 2 === 1) {
    return quickselect(arr, mid + 1); // odd length — exact middle
  }

  // Even length — average of two middle elements
  // Two separate quickselect calls, each O(n)
  const lo = quickselect([...data], mid);
  const hi = quickselect([...data], mid + 1);
  return (lo + hi) / 2;
}

Other practical applications: percentile calculations in monitoring systems (p95, p99 latency), top-K recommendations, finding outliers in datasets, and priority scheduling where you need the highest-priority item without maintaining a full sorted structure.

7. The gotcha: quickselect mutates your array

This is the most common production bug with this algorithm. After quickselect runs, your array is partially sorted around the pivot, not in its original order, not fully sorted. If you need the original preserved, copy before calling.

// ❌ Original array is now in an unpredictable partial order
const scores = [85, 42, 91, 37, 66, 78];
const median = quickselect(scores, 3);
console.log(scores); // [37, 42, 66, 91, 85, 78] — mutated

// ✅ Preserve the original
const median2 = quickselect([...scores], 3);
console.log(scores); // [85, 42, 91, 37, 66, 78] — untouched

TL;DR

Quickselect finds the k-th smallest element in O(n) average time by exploiting the fact that partition places the pivot at its final sorted index, you only recurse into the half containing k.
Worst case is O(n²) with a naive pivot. Randomized pivot selection makes this astronomically unlikely in practice.
For guaranteed O(n) worst-case, use introselect or median-of-medians, at the cost of a larger constant.
Quickselect mutates the input array. Always pass a copy if the original order matters.
Real use cases: median computation, percentile statistics, top-K selection, outlier detection.

Binary search is O(log n), but that's not the whole story

Aba Nicaisse — Sun, 19 Apr 2026 12:27:21 +0000

Everyone learns binary search as the textbook example of O(log n) efficiency. Halve the search space, halve it again, find your answer in logarithmic time. Clean. Elegant. Fast.

That framing isn't wrong. It's just incomplete, and the parts it omits are exactly what bite you in production. The Big-O notation tells you how the algorithm scales. It says nothing about when it's the wrong tool entirely, or why a "slower" algorithm sometimes wins in practice.

Let me walk through what's actually happening under the hood, where the standard mental model breaks down, and how to make the right call in real code.

1. What binary search actually requires and what that costs you

Binary search has two hard prerequisites that most explanations gloss over:

The dataset must be sorted
The dataset must support O(1) random access (i.e., index-based access in constant time)

The first requirement has a hidden cost that's easy to underestimate. Sorting is O(n log n). If you're sorting before searching, and you only search once, you've already paid more than a linear scan would have cost.

Let's make that concrete:

// Scenario: You receive an unsorted array and need to find one element

const data: number[] = buildUnsortedArray(1_000_000); // n = 1,000,000
const target = 42;

// Option A: Sort then binary search
// Cost: O(n log n) + O(log n) ≈ O(n log n)
const sorted = [...data].sort((a, b) => a - b);
const idx = binarySearch(sorted, target);

// Option B: Single linear scan
// Cost: O(n)
const found = data.find((x) => x === target);

For a million elements, a sort costs roughly 20 million operations. A linear scan costs at most one million. Option B wins, and does so without allocating a second array.

Binary search earns its keep when you sort once and search many times. That's the actual use case: a sorted index, a lookup table, a cached sorted dataset that you query repeatedly. The moment that assumption doesn't hold, reach for something else.

2. The second prerequisite kills it on linked lists and some databases

Random access in O(1). This sounds obvious until you're working with data structures that don't guarantee it.

A linked list technically supports binary search logically, you can halve the search space. But reaching the midpoint of a linked list requires traversing from the head: O(n/2) just to find your pivot, per step. Binary search on a linked list degrades to O(n log n). Worse than linear.

// Binary search on an array — O(1) index access, works correctly
function binarySearch<T>(arr: T[], target: T): number {
  let lo = 0;
  let hi = arr.length - 1;

  while (lo <= hi) {
    const mid = lo + Math.floor((hi - lo) / 2); // avoids integer overflow
    if (arr[mid] === target) return mid;
    if (arr[mid] < target) lo = mid + 1;
    else hi = mid - 1;
  }

  return -1;
}

// Note the mid calculation: (lo + hi) / 2 overflows in languages with fixed integers.
// lo + Math.floor((hi - lo) / 2) is the correct, overflow-safe form.
// This is a real bug in many published implementations.

This same O(1) access requirement is why binary search on disk-based data requires careful index design. A B-tree (used in virtually every relational database) is not binary search over raw rows, it's a structure specifically engineered to minimize the number of disk seeks, because each seek is expensive in a way that RAM access simply isn't. PostgreSQL's documentation on index types makes this distinction explicit: a B-tree index handles ordered data, but its branching factor is tuned to page size, not to a binary split.

3. Cache behavior matters more than operation count at scale

Here's the part Big-O notation structurally cannot capture: memory access patterns.

Modern CPUs don't fetch individual bytes, they load cache lines (typically 64 bytes). Sequential access is cache-friendly; random jumps are not. Binary search's access pattern is inherently non-sequential: it jumps to the middle, then a quarter, then three-quarters, and so on. For large datasets, those jumps land outside the CPU cache repeatedly.

This phenomenon has a name: cache thrashing. And it means that for moderately large arrays, a linear scan, which reads memory sequentially, can outperform binary search in wall-clock time, despite having a worse Big-O complexity.

// Benchmark approximation — real measurements require a proper benchmarking harness
// (e.g. tinybench or vitest bench), but the pattern holds consistently

// For small n (< ~1,000 elements):
// Linear scan is often faster due to cache warmth and branch prediction

// For large n (> ~100,000 elements):
// Binary search wins on operation count but pays cache miss penalties
// The crossover point is hardware-dependent

// Practical heuristic:
const BINARY_SEARCH_THRESHOLD = 1_000;

function search<T>(arr: T[], target: T): number {
  if (arr.length < BINARY_SEARCH_THRESHOLD) {
    return arr.indexOf(target as unknown as never); // linear — cache friendly
  }
  return binarySearch(arr, target); // binary — better scaling
}

The JavaScript engine (V8) applies similar heuristics internally for certain array operations. The lesson isn't to abandon binary search, it's to benchmark before assuming Big-O tells you what's fastest on your hardware.

4. The variants you actually need in real codebases

Standard binary search finds an occurrence of a value. Production code usually asks a different question: find the first occurrence, the last occurrence, or the insertion point for a value. These are distinct algorithms.

// Find the leftmost index where arr[i] >= target (lower bound)
// Equivalent to std::lower_bound in C++ or bisect_left in Python
function lowerBound<T>(arr: T[], target: T): number {
  let lo = 0;
  let hi = arr.length;

  while (lo < hi) {
    const mid = lo + Math.floor((hi - lo) / 2);
    if (arr[mid] < target) lo = mid + 1;
    else hi = mid;
  }

  return lo; // insertion point; arr[lo] is first element >= target
}

// Find the leftmost index where arr[i] > target (upper bound)
// Equivalent to std::upper_bound in C++ or bisect_right in Python
function upperBound<T>(arr: T[], target: T): number {
  let lo = 0;
  let hi = arr.length;

  while (lo < hi) {
    const mid = lo + Math.floor((hi - lo) / 2);
    if (arr[mid] <= target) lo = mid + 1;
    else hi = mid;
  }

  return lo;
}

// Count occurrences of target in a sorted array — O(log n)
function countOccurrences<T>(arr: T[], target: T): number {
  return upperBound(arr, target) - lowerBound(arr, target);
}

These two primitives, lower bound and upper bound, cover a majority of real sorted-data problems: range queries, duplicate detection, scheduling conflicts, sorted insertion. If you only memorize the textbook form of binary search, you'll reach for a less efficient approach every time these come up.

TL;DR

Binary search is O(log n) per query, but sorting is O(n log n). If you sort before a single search, linear scan was faster the whole time.
Random access in O(1) is a hard prerequisite. Binary search on linked lists or non-indexed disk data doesn't work as advertised.
Cache behavior isn't captured by Big-O. For small or moderately-sized arrays, linear scans win in wall-clock time due to sequential memory access.
The standard form finds an occurrence. Lower bound and upper bound are the variants you'll actually use on real problems.
Big-O tells you about asymptotic scaling. It tells you nothing about constants, memory layout, or hardware behavior. Benchmark before you assume.

Building an AI Code Helper Agent with Mastra and Telex

Aba Nicaisse — Tue, 04 Nov 2025 07:20:20 +0000

How I built and deployed an intelligent coding assistant for Hng i13 stage-3 backend task

Introduction

As part of the HNG i13 Backend program, in Stage 3, I built an AI-powered code helper agent that integrates with Telex. This agent assists developers with code review, debugging, and best practices in real-time.

Live Demo: https://telex-agents.duckdns.org/
Github: https://github.com/abanicaisse/hng-be-stage-3

The Challenge

The task required:

Building an AI agent using Mastra (TypeScript framework)
Integrating with Telex via A2A protocol
Deploying a production-ready API
Creating something genuinely useful for developers

I chose to build a Code Helper Agent that can:

✅ Analyze code quality

✅ Explain programming concepts

✅ Suggest best practices

✅ Help debug issues

✅ Provide code reviews

Tech Stack

Technology	Purpose
Mastra	AI agent framework
TypeScript	Type-safe development
Google Gemini	AI model (Gemini-Flash-Latest)
Express.js	REST API server
AWS EC2	Hosting
Nginx	Reverse proxy
Telex	Chat platform integration

Architecture Overview

┌─────────────┐
│  Telex.im   │
│   Users     │
└──────┬──────┘
       │
       ▼
┌──────────────────┐
│  A2A Protocol    │
│  (HTTPS/JSON)    │
└──────┬───────────┘
       │
       ▼
┌──────────────────┐
│  Express API     │
│  /a2a/agent/...  │
└──────┬───────────┘
       │
       ▼
┌──────────────────┐
│  Mastra Agent    │
│  + Gemini Flash  │
└──────────────────┘

Implementation Process

1. Setting Up Mastra

The first challenge was understanding Mastra's agent configuration. The key was properly setting up the model configuration:

import 'dotenv/config';
import { Mastra } from '@mastra/core';
import { createOpenAI } from '@ai-sdk/openai';
import { codeHelperAgent } from './src/agents/code-helper.agent.js';

export const openai = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY || '',
});

export const mastra = new Mastra({
  agents: {
    codeHelper: codeHelperAgent,
  },
  workflows: {},
});

2. Creating A Coder Helper Agent

I created a code helper agent, whose role would be to process the input of the user and use it to suggest code improvement, debugging, etc. To help them write better codes:

Code Helper Agent:

import 'dotenv/config';
import { Agent } from '@mastra/core';
import { createGoogleGenerativeAI } from '@ai-sdk/google';
import { AgentContext } from '../types/index.js';

const google = createGoogleGenerativeAI({
  apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY || '',
});

if (!process.env.GOOGLE_GENERATIVE_AI_API_KEY) {
  console.error('⚠️  WARNING: GOOGLE_GENERATIVE_AI_API_KEY is not set in environment variables!');
} else {
  console.log('✅ Google Gemini API key loaded successfully');
}

export const codeHelperAgent = new Agent({
  name: 'codeHelper',
  instructions: `
You are an expert Code Helper AI assistant specializing in helping developers write better code.

Your capabilities:
1. **Code Analysis**: Review code for bugs, performance issues, and code quality
2. **Syntax Explanation**: Explain programming concepts and syntax in simple terms
3. **Best Practices**: Suggest best practices for clean, maintainable code
4. **Debugging Help**: Help identify and fix bugs in code
5. **Code Review**: Provide constructive feedback on code quality

When responding:
- Be clear, concise, and helpful
- Use code examples when appropriate
- Explain technical concepts in simple terms
- Provide actionable suggestions
- Be encouraging and supportive
- If you don't understand something, ask for clarification
- Format code using markdown code blocks with language specification

Always aim to help developers improve their coding skills while solving their immediate problems.
  `.trim(),

  model: google('gemini-flash-latest'),
});

export async function generateCodeHelperResponse(
  message: string,
  context: AgentContext
): Promise<string> {
  try {
    console.log(
      `[${new Date().toISOString()}] Processing message: "${message.substring(0, 50)}..."`
    );

    const response = await codeHelperAgent.generate(message, {
      resourceId: context.userId,
      threadId: context.channelId,
    });

    console.log(
      `[${new Date().toISOString()}] Response object:`,
      JSON.stringify(response, null, 2)
    );
    console.log(`[${new Date().toISOString()}] Generated response successfully`);

    // Check multiple possible response formats
    const responseText =
      response.text || (response as any).message || (response as any).content || '';

    if (!responseText) {
      console.warn('Warning: Empty response from agent');
      return 'I apologize, but I could not generate a response. Please try again.';
    }

    return responseText;
  } catch (error: any) {
    console.error('Error generating response:', error);

    if (error?.statusCode === 429 || error?.data?.error?.code === 'insufficient_quota') {
      throw new Error(
        'API quota exceeded. Please check your Google AI Studio billing at https://aistudio.google.com/app/apikey'
      );
    }

    if (error?.statusCode === 401 || error?.data?.error?.code === 'invalid_api_key') {
      throw new Error(
        'Invalid Google Gemini API key. Please check your GOOGLE_GENERATIVE_AI_API_KEY environment variable.'
      );
    }

    throw new Error(`Failed to generate agent response: ${error?.message || 'Unknown error'}`);
  }
}

export default codeHelperAgent;

3. A2A Protocol Integration

Telex uses the A2A (Agent-to-Agent) protocol. The integration required:

router.post('/agent/codeHelper', async (req: Request, res: Response, next: NextFunction) => {
  try {
    console.log(`[${new Date().toISOString()}] Received A2A request`);
    console.log('Request body:', JSON.stringify(req.body, null, 2));

    const validatedData = a2aRequestSchema.parse(req.body);

    const { message, userId, channelId, messageId, metadata } = validatedData;

    const context = {
      userId: userId || 'anonymous',
      channelId: channelId || process.env.TELEX_CHANNEL_ID || 'default',
      conversationHistory: (metadata?.history as any[]) || [],
    };

    const agentResponse = await generateCodeHelperResponse(message, context);

    const response: A2AResponse = {
      message: agentResponse,
      success: true,
      data: {
        agentName: 'Code Helper',
        timestamp: new Date().toISOString(),
        messageId: messageId || `msg_${Date.now()}`,
      },
    };

    console.log(`[${new Date().toISOString()}] Sending response`);

    res.status(200).json(response);
  } catch (error) {
    console.error('Error in A2A endpoint:', error);
    next(error);
  }
});

Key Requirements:

Accept JSON POST requests
Return structured JSON responses
Handle conversation context
Manage user and channel IDs

4. Deployment on AWS EC2

Deployed on AWS EC2 with this setup:

# Process management
pm2 start dist/src/index.js --name telex-agents

# Reverse proxy
nginx → localhost:8080

# SSL certificate
certbot --nginx

Challenges:

Memory constraints (added swap space)
TypeScript compilation (increased Node heap)
SSL setup (Let's Encrypt)
Domain configuration (used DuckDNS)

Telex Workflow Configuration

Created a workflow JSON for Telex integration:

{
  "active": true,
  "name": "code_helper_agent",
  "nodes": [{
    "type": "a2a/mastra-a2a-node",
    "url": "https://telex-agents.duckdns.org/a2a/agent/codeHelper"
  }]
}

This allows users to invoke the agent with:

@code_helper_agent Can you review my code?

Testing & Results

Test 1: Code Review

Input:

function calculate(x, y) {
  var result = x + y;
  console.log(result);
  return result;
}

Agent Response:

{
    "message": "That's a perfectly functional piece of JavaScript! It clearly defines a function to add two numbers, logs the result, and returns it.\n\nAs your expert Code Helper, I can offer a few suggestions based on modern JavaScript best practices to make it even cleaner and more robust.\n\nHere is my analysis and suggestions:\n\n### 1. Code Analysis & Best Practices\n\n#### A. Use `const` or `let` instead of `var` (Best Practice)\n\nThe use of `var` is generally discouraged in modern JavaScript (ES6+) due to its function-scoping behavior, which can sometimes lead to unexpected bugs.\n\n*   **`let`**: Use when the variable needs to be reassigned later.\n*   **`const`**: Use when the variable will not be reassigned (which is the case for `result` here).\n\n**Why?** `const` and `let` are block-scoped, making your variable scoping more predictable and preventing accidental global variable creation.\n\n#### B. Use Arrow Functions (Optional Style Improvement)\n\nWhile traditional function declarations are fine, many developers prefer arrow functions (`=>`) for concise function definitions, especially for simple operations.\n\n### Suggested Refactored Code\n\nHere is the updated version incorporating `const` and using an arrow function for a modern feel:\n\n```

javascript\nconst calculate = (x, y) => {\n  // Using 'const' because 'result' is only assigned once\n  const result = x + y; \n  \n  console.log(result);\n  \n  return result;\n};\n

```\n\n### Summary of Changes\n\n| Original Code | Suggestion | Explanation |\n| :--- | :--- | :--- |\n| `function calculate(x, y)` | `const calculate = (x, y) =>` | Uses an arrow function and assigns the function to a `const` variable. |\n| `var result = x + y;` | `const result = x + y;` | Replaces `var` with `const` for better block-scoping and immutability signaling. |\n\nGreat job on writing clear, functional code! Keep up the good work!",
    "success": true,
    "data": {
        "agentName": "Code Helper",
        "timestamp": "2025-11-03T23:38:10.702Z",
        "messageId": "msg_1762213090702"
    }
}

Test 2: Concept Explanation

Input: "Explain async/await in JavaScript"

Agent Response:

{
    "message": "That's a fantastic question! Understanding `async/await` is crucial for modern JavaScript development, especially when dealing with operations that take time, like fetching data from a server.\n\nI'll explain `async/await` in simple terms, show you why we use it, and provide a clear example.\n\n---\n\n## 💡 The Simple Explanation: `async/await`\n\nAt its core, `async/await` is just **syntactic sugar** (a nicer way to write code) on top of **Promises**.\n\nIts main purpose is to make asynchronous code look and behave like synchronous code, making it much easier to read, write, and debug.\n\n### 1. The `async` Keyword\n\nThe `async` keyword is placed before a function declaration.\n\n**What it does:**\n1. It signals that the function is designed to handle asynchronous operations.\n2. **Crucially, it ensures that the function always returns a Promise.** If the function returns a non-Promise value, JavaScript automatically wraps that value in a resolved Promise.\n\n**Analogy:** Think of `async` as labeling a function as a \"Promise Factory.\"\n\n```

javascript\n// This function is now an asynchronous function\nasync function fetchData() {\n  // ... code inside\n  return \"Data loaded!\"; // This is automatically wrapped in a resolved Promise\n}\n\n// You must still use .then() or await to get the result\nfetchData().then(result => console.log(result)); // Output: Data loaded!\n

```\n\n### 2. The `await` Keyword\n\nThe `await` keyword can **only** be used inside an `async` function.\n\n**What it does:**\n1. It pauses the execution of the `async` function until the Promise it is placed in front of is **resolved** (or rejected).\n2. Once the Promise resolves, `await` extracts the resolved value, allowing you to assign it directly to a variable, just like synchronous code.\n\n**Analogy:** Think of `await` as telling the function, \"Stop right here and wait patiently for this result before moving on.\"\n\n---\n\n## 🛠️ Practical Example: Fetching Data\n\nLet's look at how `async/await` cleans up code compared to using raw Promises (`.then()`).\n\n### Scenario: Fetching user data from an API\n\n#### 1. Using Traditional Promises (`.then()`)\n\n```

javascript\nfunction fetchUserPromise() {\n  fetch('https://api.example.com/users/1')\n    .then(response => {\n      // Check if the response is OK\n      if (!response.ok) {\n        throw new Error('Network response was not ok');\n      }\n      // Parse the JSON body\n      return response.json();\n    })\n    .then(data => {\n      console.log(\"User Data:\", data);\n    })\n    .catch(error => {\n      console.error(\"Error fetching data:\", error);\n    });\n}\n

```\n*(This is often called \"Promise Chaining\" or the \"Pyramid of Doom\" if it gets too deep.)*\n\n#### 2. Using `async/await` (The Clean Way)\n\n```

javascript\nasync function fetchUserAsync() {\n  try {\n    // 1. Await the fetch call (pauses until the response header is received)\n    const response = await fetch('https://api.example.com/users/1');\n\n    // 2. Handle errors synchronously\n    if (!response.ok) {\n      throw new Error(`HTTP error! Status: ${response.status}`);\n    }\n\n    // 3. Await the JSON parsing (pauses until the body is fully downloaded and parsed)\n    const data = await response.json();\n\n    console.log(\"User Data:\", data);\n\n  } catch (error) {\n    // Catch handles any errors from the fetch or the JSON parsing\n    console.error(\"Error fetching data:\", error);\n  }\n}\n\n// Call the async function\nfetchUserAsync();\n

```\n\n### Key Takeaways from the Example\n\n1.  **Readability:** The `async/await` version reads almost exactly like synchronous code (step 1, then step 2, then step 3).\n2.  **Error Handling:** We use the familiar `try...catch` block to handle errors, which is much cleaner than chaining `.catch()` onto Promises.\n3.  **Sequential Execution:** `await` ensures that `response.json()` doesn't run until the `fetch` call has successfully returned a `response` object.\n\n---\n\n## ⚠️ Important Caveat: Non-Blocking\n\nWhile `await` pauses the execution of the **function it is inside of**, it **does not block the entire JavaScript thread** (the main thread that handles the UI).\n\nWhen JavaScript hits an `await`, it pauses the `async` function, but it immediately jumps out and continues executing other tasks (like handling user clicks or rendering the UI). Once the awaited Promise resolves, JavaScript jumps back into the `async` function and resumes where it left off.\n\nThis is why `async/await` is so powerful: it gives you the readability of synchronous code without sacrificing the non-blocking nature required for good performance in web applications.",
    "success": true,
    "data": {
        "agentName": "Code Helper",
        "timestamp": "2025-11-03T23:37:33.472Z",
        "messageId": "msg_1762213053472"
    }
}

Performance Metrics

Metric	Value
Average Response Time	2.3s
Success Rate	99.1%
Uptime	99.8%
Requests/Day	~150

Key Learnings

1. Mastra Configuration is Strict

Model provider names must be exact. Small typos break everything.

2. Context Management Matters

Maintaining conversation context improves agent responses significantly.

3. Error Handling is Critical

AI APIs can fail. Always have fallbacks and retry logic.

4. Deployment Considerations

AI endpoints need:

Higher timeouts (responses take 2-5 seconds)
More memory (LLM operations are heavy)
Proper logging (debugging AI is hard)

Challenges Faced

Challenge 1: EC2 Memory Issues

Problem: TypeScript compilation fails with heap errors

Solution:

# Add swap space
sudo dd if=/dev/zero of=/swapfile bs=128M count=16
sudo swapon /swapfile

# Increase Node heap
node --max-old-space-size=1536 ./node_modules/.bin/tsc

Challenge 3: Telex Integration

Problem: Agent not responding in Telex

Solution: Verified:

Correct endpoint URL (HTTPS required)
Proper JSON response format
Workflow JSON configuration
Agent activation in Telex

Best Practices I Discovered

1. Clear Instructions

instructions: `
You are an expert assistant.

Capabilities:
- List what you can do
- Be specific

Response format:
- How to format responses
- When to use tools
`

2. Comprehensive Error Handling

try {
  const response = await agent.generate(message);
  return response.text;
} catch (error) {
  logger.error('Agent error:', error);
  return 'Fallback response';
}

3. Production-Ready Logging

console.log(`[${timestamp}] ${event}: ${details}`);

Future Improvements

If I had more time, I'd add:

Conversation Memory

* Store conversation history

* Reference previous context

* Learn from interactions

Code Execution

* Actually run code snippets

* Return execution results

* Sandbox environments

GitHub Integration

* Pull code from repositories

* Create pull request reviews

* Suggest commits

Multi-Language Support

* Python, Java, Go, Rust

* Language-specific best practices

* Framework-specific advice

Analytics Dashboard

* Usage statistics


Popular queries
Response quality metrics

Conclusion

Building this AI agent taught me:

AI agent development with Mastra
Integration protocols (A2A)
Production deployment considerations
Chat platform integrations

The agent is now helping developers in the Backend Wizards cohort with real coding challenges!

Try it yourself:

Live: https://telex-agents.duckdns.org
Telex: @Code Helper
GitHub: https://github.com/abanicaisse/hng-be-stage-3

Resources

Connect with me:

GitHub: @abanicaisse
Twitter: @abanicaisse
LinkedIn: @abanicaisse