
An active Player in the game of technology


Brian Baliach


Imagine this: You have an Excel or CSV (or any other) dataset, and you want quick, clear answers from it. Maybe something simple on the lines of: "What’s the average price by country?".
Also, you do not use Excel (or you just hate Microsoft and are an apple junkie, despite their recent uninspired "innovations" like re-arranging cameras and renaming abbreviations like AI), and you definitely do not have a data science degree and aren't planning on getting one.

With AI (or AGI, or ASI, or whichever new acronym the industry comes up with tomorrow), you probably don’t have to. Upload your file, ask your question, and the assistant will inspect the columns, validate types, choose the right calculation, and deliver a crisp summary. No data science degree and no big budgets on Microsoft software - just useful insights from your data.

That is the magic of agentic AI and tool-calling.

### How Agentic AI Solves the Spreadsheet Sweat

Think of an "agent" as a seasoned analyst who:
- Understands your question in plain language.
- Chooses the right tools (average, sum, min, max).
- Validates the data and asks clarifying questions when things are ambiguous.
- Returns a concise answer with just the essentials.

Tool-calling is simply how the agent gets real work done: it calls small, well-defined functions (tools) to compute things accurately. If you say "average price," the agent picks the average tool, ensures "price" exists and is numeric, and then computes it.

No more trying to predict every user action with a jungle of if-else branches. People are gloriously unpredictable - remember all that blockchain hype? Door locks on the blockchain, toasters on the blockchain... in what world would your smart bed need blockchain?
Instead, define small, composable tools with clear contracts, and let the agent do the orchestration, validation and computation:

- Infer intent from natural language
- Inspect schema or preview to confirm columns and types
- Select the right tool (average, sum, min, max)
- Supply the correct parameters
- Catch and explain errors in plain English
- Ask clarifying questions when things are ambiguous 

Even your grandpa or grandma does not need to video call you to ask how to answer a call on Skype (also, who uses Skype nowadays). The AI handles everything and picks the correct inputs for your tools so that users can just ask, and they get answers.

### What Is Tool-Calling, Really?

If LLMs are your conversational layer, tools are your calculators, databases, and business logic. The LLM doesn’t need to "guess" results - it orchestrates:
- Which tool to call
- With which parameters
- In what order
- And how to present the answer back to you

This is how LLMs stop hallucinating numbers and start doing grounded, verifiable work.

### A Friendly Real-World Aside

This shift is already happening in the industry — and at my workplace, farmbetter — where we’re equipping our WhatsApp bot with AI. Instead of hardcoding every flow and error message, we let an agent validate inputs, ask follow-up questions, and run the right tools. The result: __more natural conversations and fewer dead ends.__

Also: the UI for this demo is AI-generated. Because of course it is.

### Try It Yourself

Upload a CSV and chat with it like a human. Ask "Total revenue by country" or "Average price." The agent will do the rest.

Live demo: [https://ask-your-csv-agent.vercel.app]  
GitHub: [https://github.com/TylerMutai/ask-your-csv-agent.git]

If you just want the big picture, you can stop here. For devs who want to see how the sausage is made, do read on.

---

## Hands-On: Building a CSV Agent with Next.js and TypeScript

We’ll build a simple analysis agent with four tools: average, sum, min, and max. The agent:
- Works only with the loaded CSV
- Never guesses column names or types
- Validates numeric columns before computing
- Stays concise and helpful (no words of affirmation like: Spectacularly superb question)

### 1) Define the Agent

Before we begin: This guide uses OpenAI’s Agent SDK in a Next.js app with TypeScript (@openai/agents).
If you prefer Python, there's a Python SDK with the same a very similar API. 
On another stack? The patterns and concepts highlighted in this guide map cleanly to other AI providers (e.g., Google Gemini - I have another blog on this focused also on AI and tool calling that you can check out (here)[https://www.balysnotes.com/integrating-model-context-protocol-with-gemini].

Also, here's the entire project codebase: [https://github.com/TylerMutai/ask-your-csv-agent.git]

Moving on...

We’ll give the agent clear instructions and register our tools. The agent decides when to call them.

```typescript
import {Agent} from "@openai/agents";
import averageTool from "@/tools/average";
import minTool from "@/tools/min";
import maxTool from "@/tools/max";
import sumTool from "@/tools/sum";

const mainAgent = new Agent({
  name: 'Assistant',
  instructions: `
You are a data analysis agent that answers questions about a CSV file. Your job is to compute accurate summaries (e.g., average, sum, count, min, max), optionally grouped by one or more columns, and return concise, helpful answers.

Behavior
- Work only with the currently loaded CSV. If no file is loaded, ask the user to upload one.
- Never guess column names or types. When unsure, inspect the schema or preview a few rows first.
- Validate that target columns exist and are numeric before computing numeric metrics; if not, ask a clarifying question or suggest valid columns.
- Prefer aggregated results over raw row dumps. If a result set would be large, summarize and show only the top 10 groups.
- Be concise: provide a one-sentence conclusion followed by a small, readable table of results (if applicable). Include units and time ranges when known.
- For ambiguous requests (e.g., "average price"), ask which column to use or propose likely matches.
- If grouping is requested (e.g., "by country" or "per month"), perform a grouped aggregation and sort results sensibly.
- If an operation is not possible (missing column, wrong type), explain the issue and propose alternatives.

Tool use
- Use schema/columns tools before calculations if uncertain.
- Use preview to verify formatting (e.g., dates).
- Use aggregate tools for grouped metrics.
- Use filter/query tools for conditions.
- Use a plotting tool when asked or when trends are natural.

Constraints and formatting
- Limit previews to ≤20 rows.
- Limit output tables to ≤10 rows.
- Do not fabricate values or columns.
- Return answers in this order:
  1) Short conclusion (one or two sentences).
  2) Compact table with clear headers.
  3) Notes about assumptions or limitations (only if relevant).
`,
  tools: [averageTool, minTool, maxTool, sumTool],
});

export default mainAgent;
```

Key idea: the LLM doesn’t compute - your tools do. The agent just decides which tool to call and how.

### 2) Create a Tool: Average

We’ll parse the CSV safely, validate columns, and compute the mean. If something’s off, we throw precise errors that the agent turns into friendly explanations.

```typescript
import {tool} from "@openai/agents";
import {z} from "zod/v3";
import parseAndFormatCsvData from "@/utils/parseAndFormatCsvData";

const averageTool = tool({
  name: 'average_tool',
  description: 'Finds the average of a given set of data.',
  parameters: z.object({
    data: z.string(),
    columns: z.array(z.string()),
  }),
  execute: async ({data, columns}) => {
    const records = parseAndFormatCsvData({data, columns});
    const averages: { [key: string]: number } = {};

    for (const column of columns) {
      const sum = records.reduce((acc: number, row: { [key: string]: unknown }) => acc + Number(row[column]), 0);
      averages[column] = sum / records.length;
    }

    return `averages according to columns: ${JSON.stringify(averages)}`;
  },
});

export default averageTool;
```

And here’s our CSV parser and validator:

```typescript
import {parse} from "csv-parse/sync";

const parseAndFormatCsvData = ({data, columns}: { data: string, columns: string[] }) => {
  const records: { [key: string]: unknown }[] = parse(data, {
    columns: true,
    skipEmptyLines: true,
    skipRecordsWithError: true,
  });

  for (const record of records) {
    for (const column of columns) {
      if (!record[column]) {
        throw new Error(`Column ${column} not found in data`);
      }
      if (isNaN(Number(record[column]))) {
        throw new Error(`Column ${column} contains non-numeric values`);
      }
    }
  }

  return records;
};

export default parseAndFormatCsvData;
```

Why this matters: instead of a generic "Something went wrong," the agent can say "Column price contains non-numeric values; try unit_price instead?" That’s kinder UX and better debugging.

### 3) Run the Agent on an API Route

We’ll post chat messages plus the CSV to an API route. The agent gets the CSV as context and replies with a concise answer.

```typescript
import {AgentInputItem, run} from "@openai/agents";
import mainAgent from "@/agents/mainAgent";

export async function POST(req: Request) {
  try {
    const {csvData, messages} = await req.json();

    const conversationMessages: AgentInputItem[] = messages.map((msg: { role: string; content: string }) => ({
      role: msg.role,
      content: [{type: msg.role === 'assistant' ? 'output_text' : 'input_text', text: msg.content}],
    }));

    const result = await run(mainAgent, conversationMessages, {
      context: csvData,
    });

    return Response.json({response: result.finalOutput});
  } catch (error) {
    console.error("Chat API error:", error);
    return Response.json({error: "Failed to process request"}, {status: 500});
  }
}
```

Note: You can also inject the CSV as the first user message if you prefer; passing it as context keeps prompts tidy.

### 4) A Minimal Frontend Chat

A simple chat interface in Next.js. Paste this into a client component and wire it to your API route.

```typescript
"use client";

import {useEffect, useRef, useState} from "react";

interface Message {
  id: string;
  role: "user" | "assistant";
  content: string;
  timestamp: Date;
}

export default function ChatInterface({csvData, fileName, onReset}: {csvData: string; fileName: string; onReset: () => void;}) {
  const [messages, setMessages] = useState<Message[]>([]);
  const [isLoading, setIsLoading] = useState(false);
  const messagesEndRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    messagesEndRef.current?.scrollIntoView({behavior: "smooth"});
  }, [messages]);

  const handleSendMessage = async (userMessage: string) => {
    if (!userMessage.trim()) return;

    const newUserMessage: Message = {
      id: Date.now().toString(),
      role: "user",
      content: userMessage,
      timestamp: new Date(),
    };

    setMessages((prev) => [...prev, newUserMessage]);
    setIsLoading(true);

    try {
      const response = await fetch("/api/chat", {
        method: "POST",
        headers: {"Content-Type": "application/json"},
        body: JSON.stringify({
          csvData,
          messages: [...messages, newUserMessage].map((m) => ({role: m.role, content: m.content})),
        }),
      });

      const data = await response.json();
      const assistantMessage: Message = {
        id: (Date.now() + 1).toString(),
        role: "assistant",
        content: data.response ?? "No response",
        timestamp: new Date(),
      };
      setMessages((prev) => [...prev, assistantMessage]);
    } catch (e) {
      setMessages((prev) => [...prev, {
        id: (Date.now() + 2).toString(),
        role: "assistant",
        content: "Sorry, I encountered an error. Please try again.",
        timestamp: new Date(),
      }]);
    } finally {
      setIsLoading(false);
    }
  };

  // Render your message list and input here
  return <div>
    {/* Message list */}
    <div ref={messagesEndRef} />
  </div>;
}
```

---

## Why Tool-Calling Changes the UX (and Programming)

- Natural interaction: Users ask for outcomes, not functions. "Top 10 customers by spend" beats "Click Reports → Pivot...".
- Better error handling: Instead of 400 Bad Request, the agent explains what went wrong and suggests fixes.
- Fewer edge-case branches: Devs define tools and constraints; the agent orchestrates logic paths on the fly.
- Maintainability: Add or swap tools without rewriting flows.
- Safer by design: Validation happens before computation; the agent refuses to guess.

### What’s Next

- Add group-by and filter tools, and a simple plotting tool for trends.
- Stream results and clarifying questions.
- Integrate with WhatsApp (hello, farmbetter -)), Slack, or internal dashboards.
- Keep the UI simple - let the agent handle the complexity.

### Wrapping Up

We’re moving from "write all the if-else" to "define good tools, then let agents orchestrate." Users win with clearer answers and fewer roadblocks. Developers win with cleaner boundaries and reusable logic.

How might agentic AI simplify your next product? Try the demo, peek at the code, and tell me what you build next!


A hands-on, beginner-friendly walkthrough of agentic AI and tool-calling using a Next.js + TypeScript.

Agents, Not If-Else: A Friendly Intro to Tool-Calling with CSVs

In today's fast-paced digital world, efficient data handling is crucial. Whether you're processing massive amounts of data, streaming real-time updates, or delivering content to multiple clients concurrently, traditional methods can quickly become overwhelming. That's where the Web Streams API comes in. It offers a solution that allows you to efficiently stream data without overloading your server's memory. The term 'Streams' means exactly what it sounds like: A stream of flowing data. We then obtain this data in bits as it continuously streams towards us. Let's explore this powerful API through the lens of a real-world example: delivering over 6000 log lines concurrently across 20 tabs.

### A Brief History Lesson
Imagine you have a large log file with over 6000 lines of valuable information. Traditionally, fetching this data and displaying it on a webpage would require loading the entire file into memory, which could slow down your server and impact performance. However, with the Web Streams API, you can stream the data on-demand, only fetching what you need when you need it. This not only saves memory and server (and client) resources, but also ensures a seamless user experience, as the logs can be displayed in real-time without delay.

The applications of the Web Streams API extend far beyond log files. Consider scenarios such as real-time analytics dashboards, chat applications, or even media streaming services. By using the Web Streams API, you can efficiently handle large volumes of data and provide responsive and dynamic experiences to your users.

### An Example Using a Large Log File (6000+ lines)
To demonstrate the power of the Web Streams API, let's dive into some code snippets. We'll be using Next.js and the app router for this example, but the Web Streams API can be used in various frameworks and environments (it's a standardized web API. You can read more about it [here](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API)).

TLDR;
To see the code in action and explore a comprehensive example project, check out the GitHub repository: 
[streaming-text-from-file-example](https://github.com/TylerMutai/streaming-text-from-file-example).

The example repository has only 3 important files: app/api/route.ts, app/logs/page.jsx and app/page.jsx.
Let's go over the code of these three in more detail.

### app/api/route.ts
```typescript
import { NextResponse } from "next/server";
import fs from "node:fs";
import path from "node:path";

/**
 *
 * @param duration - milliseconds to wait before resolving the promise.
 */
function sleep(duration = 2000) {
  return new Promise((resolve) => {
    setTimeout(resolve, duration);
  });
}

async function readFile(filePath: string, start: number, end: number) {
  const readStream = fs.createReadStream(filePath, {
    start,
    end,
  });

  return new Promise<Buffer>((resolve) => {
    readStream.on("data", (data) => {
      resolve(data as any);
    });
  });
}

function getFileReaderConfig() {
  // File being read. the file contains at least 6 thousand lines of logs.
  // They'll all be efficiently streamed to the frontend without overusing your server's memory.
  // Open multiple tabs using the same URL and see for yourself.
  const filePath = path.join(process.cwd(), `logs/2024-02-13.log`);
  const fileStats = fs.statSync(filePath);
  const byteLengthToRead = 16000; // represents 16KB. There's no reason for this, I just chose the number since it
  // showcases streaming better.

  const start = 0;
  let end = start + byteLengthToRead;

  if (end > fileStats.size) {
    end = fileStats.size;
  }

  return { filePath, start, end, byteLengthToRead, fileSize: fileStats.size };
}

async function* makeIterator(
  filePath: string,
  start: number,
  end: number,
  byteLengthToRead: number,
  fileSize: number,
): any {
  if (start >= end) {
    // we have read the whole file. save last read bytes and return.
    return;
  }
  // This is just added here to better showcase streaming on the browser. You'll be able to see data being populated.
  // Feel free to remove this line to use streaming at its best.
  await sleep(10);

  // The reason there's a start + 1 here is because we end up re-reading an extra byte everytime, duplicating
  // the last character read twice.
  yield await readFile(filePath, start + 1, end);

  // move [byteLengthToRead] bytes behind.
  const _start = end;
  let _end = end + byteLengthToRead;

  // if moving [byteLengthToRead] bytes behind becomes less than [ceiling], then move our
  // [_start] to [ceiling].
  if (_end > fileSize) {
    _end = fileSize;
  }
  yield* makeIterator(filePath, _start, _end, byteLengthToRead, fileSize);
}

function iteratorToStream(iterator: any) {
  return new ReadableStream({
    async pull(controller) {
      const { value, done } = await iterator.next();

      if (done) {
        controller.close();
      } else {
        controller.enqueue(value);
      }
    },
  });
}

export async function GET() {
  try {
    const { filePath, start, end, byteLengthToRead, fileSize } =
      getFileReaderConfig();

    const iterator = makeIterator(
      filePath,
      start,
      end,
      byteLengthToRead,
      fileSize,
    );
    const stream = iteratorToStream(iterator);

    return new Response(stream, {
      headers: {
        "Content-Type": "text/html; charset=utf-8",
      },
    });
  } catch (e) {
    return NextResponse.json(
      {
        message: `A server error occurred. Contact support. ${(e as any)?.message}`,
        code: 500,
      },
      {
        status: 500,
      },
    );
  }
}
```
This file represents a route handler (the new jargon used by App Router in place of api routes that were used in the Pages Router. Read more here: [Next Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers))

We have a 'GET' method that handles 'GET' requests to that route. We have a helper funtion `getFileReaderConfig()` that reads information about the file we're about to fetch (rather than reading the file itself). Here, we get important information like the file's size which we'll use to calculate the chunks we'll be serving back to the client.

We then have the `makeIterator` function, which is a generator function (as declared by `function*`). A generator function has the ability to persist its context across calls. This means the function can exit, and when called next, remembers the 'data' it had, and resume from it. You can [read more here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*). 

This is important since we need a way to recollect the last chunk we served to the client, and to which boundary that chunk got us. I.e. if we're serving a file of say 1000 bytes, and we have defined our chunk size as 100, and we have served the chunk 5 times, we should serve only the remaining chunk which is 500 bytes (100 * 5 chunks = 500 bytes. 1000- 500 bytes = 500 bytes).

The `makeIterator` function declares the `fileSize` (maximum bytes to read), the `start` (the start boundary, which initially is '0') and the `end` positions (which is initially the `byteLengthToRead` which is basically a 'chunk' of specific length, in this case, 16000 bytes). We then use the sliding window technique, where we continuously move the 'chunk' towards the end of the file until we have read the whole file.

We then read the file itself using `fs.createReadSteam` which has an extra argument called `options` which allow you to specify the start and end positions of the file you intend to read.

### app/logs/page.tsx
```typescript
"use client";
import { useCallback, useEffect, useMemo, useRef, useState } from "react";

const anchorForScrollId = "anchor-to-tell-document-to-scroll-to";
export default function Home() {
  const [streamingLogs, setStreamingLogs] = useState<string>("");
  const [errorMessage, setErrorMessage] = useState<string>("");
  const timeoutHandle = useRef<NodeJS.Timeout>();
  const isFetchOngoing = useRef(false);

  const getLogs = useCallback(async () => {
    if (isFetchOngoing.current) {
      return;
    }
    isFetchOngoing.current = true;
    setStreamingLogs("");
    try {
      const response = await fetch(`/api/logging`);
      if (response.ok) {
        const textDecoder = new TextDecoder();
        const reader = response?.body?.getReader();

        if (reader) {
          while (true) {
            const { value, done } = await reader.read();
            if (value) {
              const stringData = textDecoder.decode(value);
              setStreamingLogs((l) => `${l}${stringData}`);
            }
            // if done, call getLogs again at some point in future for more data.
            if (done) {
              // reset the logs to an empty string so that for the next fetch, we don't duplicate strings.
              clearTimeout(timeoutHandle.current);
              timeoutHandle.current = setTimeout(getLogs, 100000);
              isFetchOngoing.current = false;
              return;
            }
          }
        } else {
          const json = await response.json();
          setErrorMessage(
            `An error occurred:${json?.message}. You'll need to refresh this page.`,
          );
        }
      }
    } catch (e) {
      setErrorMessage(
        `An error occurred: ${(e as any)?.message} ${(e as any)?.response?.message}. You'll need to refresh this page.`,
      );
    }
  }, []);

  useEffect(() => {
    getLogs().then();

    const _handle = timeoutHandle.current;
    return () => {
      clearTimeout(_handle);
    };
  }, [getLogs]);

  useEffect(() => {
    document.getElementById(anchorForScrollId)?.scrollIntoView({
      behavior: "smooth",
    });
  }, [streamingLogs]);

  const logs = useMemo(() => {
    return streamingLogs?.split("\n");
  }, [streamingLogs]);

  return (
    <div className="flex flex-col w-full h-[100vh] p-10 overflow-auto">
      <h5 className="w-full pb-4 border-b border-secondary-color-100 border-solid">
        Logs should automatically start appearing below.
      </h5>
      <h5 className="text-red-700">{errorMessage}</h5>
      {logs?.map((l, idx) => (
        <h6 key={idx} className="w-full">
          {l || <br />}
        </h6>
      ))}
      <div id={anchorForScrollId} />
    </div>
  );
}
```
This file is a React component that does the heavy lifting on the client side. In this file, we make a network request to our logging api that we just defined in the previous code snippet. We then obtain a 'ReadableStreamDefaultReader' object by calling `response.body.getReader()` which will help us read single chunks as they're made available in the stream. We then convert these byte streams into strings using the `TextEncode API` and render this string on the UI.

Notable mentions are the `isFetchOngoing` ref and the `timeoutHandler`. The `isFetchOngoing` ref stores a boolean value to indicate whether there's already a stream currently being consumed. If it's the case, it prevents duplicate requests being sent that will then read independent streams and mess up the UI rendering. The `timeoutHandler` stores a reference to the `setTimeout` function we call (since we end up polling the server every 100 seconds) that allows us to clear the timeout event in cases where out component unmounts and setTimeout was already fired.

### app/page.tsx
```typescript
"use client";

import { useEffect } from "react";

export default function Home() {
  // open 20 tabs instantaneously to see whether the server will handle all streams.
  // You will need to 'allow all popups' in your browser to see this in effect.
  useEffect(() => {
    let tabs = 20;
    while (tabs) {
      window.open("/logs", "_blank");
      tabs--;
    }
  }, []);

  return (
    <h2 className="p-10 m-10 w-full flex flex-row- items-center justify-center">
      Nothing&apos;s happening? Make sure to enable popups in your browser!
    </h2>
  );
}
```
This is the page that is now rendered on the '/' (or index) route. We open 20 tabs concurrently each having its own established stream (the previous code snippet that handles streaming of data from the backend) to see how the server behaves under this pressure. 

The server does just fine, streaming all 6000+ lines back to all 20 clients (as represented by the tabs).


### Conclusion
The Web Streams API opens up new possibilities for handling large volumes of data efficiently. By streaming data on-demand instead of loading it all into memory, you can provide responsive experiences to your users without sacrificing server performance. Whether you're dealing with log files, real-time analytics, or media streaming, incorporating the Web Streams API can greatly enhance your application's capabilities.

In this blog post, we've explored the basics of the Web Streams API, provided practical examples and code snippets, and highlighted its significance in today's data-driven world. Now it's time for you to dive in, experiment with streaming data, and unlock new possibilities for your web applications.

Remember, efficient data handling is the backbone of modern web applications. Embrace the power of streaming data, and unlock a whole new level of performance and user experience!


Explore the powerful Web Streams API with this guide. Learn to handle 6000+ log lines across 20 tabs concurrently, boosting web performance and user experience.

Showing posts from next category

Agents, Not If-Else: A Friendly Intro to Tool-Calling with CSVs

Web Streams API in Action: Delivering 6000+ Log Lines Concurrently Across 20 Tabs