Build an AI Agent with Mastra and TypeScript

Olamide Okefolahan — Sat, 01 Nov 2025 22:51:17 +0000

AI, AI Agents, Agentic AI... you can't go a day without coming across at least one of these terms. They promise a future where software can not only think but also act. But what does that really mean, and how can you build one yourself?

In today's post, we'll demystify AI Agents by building a practical one: a Wikipedia Agent that can fetch and tell you about the featured article of the day.

What's an AI Agent, Anyway?

An AI Agent is a program that combines intelligence with the ability to act. It doesn’t just process information from its training data; it can take action using connected tools and systems, often without human intervention.

For example, a standard LLM like ChatGPT can't tell you what Wikipedia's featured article is today because its knowledge is frozen in time. It can't browse the web.

That's where AI Agents come in. By giving an LLM "tools"—like the ability to call an API—we empower it to overcome its limitations and interact with the live world.

Our Project: The Wikipedia Agent

We'll build an AI agent that, when asked, fetches the current featured article from Wikipedia. This is a simple yet powerful demonstration of how agents can access real-time data.

To make this easy, we'll use Mastra, "The TypeScript Agent Framework". It provides the core plumbing to define agents, create tools, and serve them through a local playground and API, letting us focus on the logic.

Prerequisites

Before we start, make sure you have:

Node.js (v20.9.0 or higher)
pnpm (or npm/yarn)
A Google API Key for the Gemini model.
A Wikimedia Access Token to use their API. You can generate one here.

Step 1: Set Up the Project

First, let's clone the project repository and install the dependencies.

git clone https://github.com/MhideTech/Wikipedia-Agent.git
cd Wikipedia-Agent
pnpm install

Next, create a .env file in the root of the project to store your secret keys.

// .env
ACCESS_TOKEN=your_wikimedia_access_token_here
GOOGLE_API_KEY=your_google_api_key_here

Step 2: Understanding the Code

The project follows a standard Mastra structure:

src/mastra/
├── index.ts              # Main Mastra configuration
├── agents/
│   └── wikipedia-agent.ts# Our Wikipedia agent definition
└── tools/
    └── wikipedia-tool.ts # The tool that fetches from Wikipedia

Let's break down the key files.

The Tool: `wikipedia-tool.ts`

This file defines the function our agent will use to get data from the outside world. It uses Mastra's createTool utility to define its purpose, inputs, and outputs so the AI can understand how to use it.

// src/mastra/tools/wikipedia-tool.ts
import { createTool } from "@mastra/core";
import z from "zod";

export const getWikipediaArticleTool = createTool({
  id: "get-todays-featured-wikipedia-article",
  description: "Get the featured Wikipedia article of the day.",
  inputSchema: z.object({}),
  outputSchema: z.object({
    article: z
      .string()
      .describe("The content of the featured Wikipedia article of the day."),
  }),
  execute: async ({ context }) => {
    try {
      const article = await getArticle();
      return { article };
    } catch (e) {
      throw new Error("Failed to fetch Wikipedia article");
    }
  },
});

async function getArticle() {
  let today = new Date();
  let year = today.getFullYear();
  let month = String(today.getMonth() + 1).padStart(2, "0");
  let day = String(today.getDate()).padStart(2, "0");
  let url = `https://api.wikimedia.org/feed/v1/wikipedia/en/featured/${year}/${month}/${day}`;

  let response = await fetch(url, {
    headers: {
      Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
      "Api-User-Agent": "Wikipedia Agent",
    },
  });
  const data = await response.json();
  // The featured article body is in the 'extract' property of the 'tfa' object.
  return data.tfa.extract;
}

createTool: We give our tool a unique id and a description. The description is crucial—it's how the LLM knows when to use this tool.
inputSchema: It's an empty object because this tool doesn't need any input from the user to run.
execute: This is the core function. It calls our getArticle() helper, which constructs the API URL for the current date and fetches the data from the Wikimedia API.

The Agent: `wikipedia-agent.ts`

Here, we define the agent itself, giving it a personality, instructions, and access to the tool we just created.

// src/mastra/agents/wikipedia-agent.ts
import { Agent } from "@mastra/core/agent";
import { Memory } from "@mastra/memory";
import { LibSQLStore } from "@mastra/libsql";
import { getWikipediaArticleTool } from "../tools/wikipedia-tool";

export const wikipediaAgent = new Agent({
  name: "Wikipedia Agent",
  instructions: `
      You are a helpful assistant that provides the Wikipedia featured article of the day.
      When a user asks for the featured article, use the 'get-todays-featured-wikipedia-article' tool to fetch it.
      Present the article content to the user in a clear and readable format.
`,
  model: "google/gemini-2.5-flash",
  tools: { getWikipediaArticleTool },
  memory: new Memory({
    storage: new LibSQLStore({
      url: "file:../mastra.db",
    }),
  }),
});

name: A simple name for our agent.
instructions: This is the system prompt. We're explicitly telling the agent its purpose and, most importantly, when and how to use the get-todays-featured-wikipedia-article tool.
model: We're using Gemini, but you could swap this for any supported model.
tools: We pass in the tool we created, making it available for the agent to use.
memory: Mastra's Memory primitive gives our agent the ability to remember past conversations, using a simple file-based database (LibSQLStore).

The Glue: `index.ts`

Finally, we register our agent with the main Mastra instance. This makes it available to the dev server and playground.

// src/mastra/index.ts
import { Mastra } from "@mastra/core/mastra";
import { PinoLogger } from "@mastra/loggers";
import { LibSQLStore } from "@mastra/libsql";
import { wikipediaAgent } from "./agents/wikipedia-agent";
import { a2aAgentRoute } from "./routes/a2aRoutes";

export const mastra = new Mastra({
  agents: { wikipediaAgent },

  storage: new LibSQLStore({
    url: ":memory:",
  }),
  logger: new PinoLogger({
    name: "Mastra",
    level: "info",
  }),
  server: {
    apiRoutes: [a2aAgentRoute],
  },
  // ... other configs
});

Step 3: Run and Interact with the Agent

That's all the code! Now, let's run it.

pnpm dev

Mastra will start a development server and automatically open a playground in your browser at http://localhost:4111.

Select wikipediaAgent from the dropdown menu.
Start a new conversation.
Ask it a question!

You: What is the featured article of the day?

The agent will now use its tool to call the Wikimedia API, get the article, and present it to you.

Going Further: Programmatic Access with A2A

Mastra also exposes agents through an Agent-to-Agent (A2A) API, allowing you to interact with them programmatically. The project already includes a route for this.

You can test it with a simple curl command:

curl -X POST http://localhost:4111/a2a/agent/wikipediaAgent \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "test-1",
    "method": "generate",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"kind": "text", "text": "Tell me about the featured article."}]
      }
    }
  }'

This makes it easy to integrate your agent into other applications, build custom UIs, or even have agents call each other.

Conclusion

Congratulations! You've just seen how to build a functional AI Agent that can break free from its static knowledge base and interact with live APIs. We've only scratched the surface, but the core concepts are here:

Define a Goal: What problem do you want the agent to solve?
Create Tools: Write functions that give the agent the capabilities it needs.
Instruct the Agent: Write a clear system prompt that tells the agent how to behave and when to use its tools. With this foundation, you can build far more complex agents. What will you build next?

Thanks for reading! If you enjoyed this, feel free to star the repository on GitHub and drop a follow here on dev.to.

Forem: Olamide Okefolahan