Mastra.ai Quickstart - How to build a TypeScript agent in 5 minutes or less

From zero to a GitHub‑insights AI agent in about 5 minutes

Mastra is a batteries‑included TypeScript framework for agentic apps.
One stack, one set of primitives, no glue code. If you are tired of gluing together multiple third-party libraries to build GenAI and agentic workflows, this is likely for you.

‍

You define agents, tools, and RAG workflows in plain TypeScript.

Mastra wires up streaming, retries, evals, and a type‑safe REST layer so you can stay focused on product logic instead of YAML pyramids of doom.

If you know TypeScript, you already know 90 % of Mastra.

Build a GitHub agent in under 5 minutes

Here's what we're going to do in this section: 

1. Spin up a new project

npm create mastra@latest github-agent \
  --components agents,tools \
  --llm openai \
  --example
cd github-agent

Mastra will begin guiding you through the setup process. Its CLI can even accept your API key, and optionally install a custom Mastra MCP server into your AI enabled IDE (Windsurf or Cursor) to prevent hallucinations and ensure the LLM you're working with always has the most up to date context and documentation about Mastra.

This author experimented with this feature and found that it significantly reduced hallucinations and sped up development time.

2. Add your LLM key

Either via the CLI prompt or by adding it to your .env file locally

3. Create a githubRepoTool

At src/mastra/tools/github-repo-tool.ts :

import { createTool } from "@mastra/core/tools";
import { z } from "zod";

interface RepoResponse {
  stargazers_count: number;
  forks_count: number;
  open_issues_count: number;
  license: { name: string } | null;
  pushed_at: string;
  description: string | null;
}

export const githubRepoTool = createTool({
  id: "get-github-repo-info",
  description: "Fetch basic insights for a public GitHub repository",
  inputSchema: z.object({
    owner: z.string().describe("GitHub username or organization"),
    repo: z.string().describe("Repository name"),
  }),
  outputSchema: z.object({
    stars: z.number(),
    forks: z.number(),
    issues: z.number(),
    license: z.string().nullable(),
    lastPush: z.string(),
    description: z.string().nullable(),
  }),
  execute: async ({ context }) => getRepo(context.owner, context.repo),
});

async function getRepo(owner: string, repo: string) {
  const res = await fetch(`https://api.github.com/repos/${owner}/${repo}`);
  if (res.status === 404) throw new Error(`Repository ${owner}/${repo} not found`);
  const data: RepoResponse = await res.json();
  return {
    stars: data.stargazers_count,
    forks: data.forks_count,
    issues: data.open_issues_count,
    license: data.license?.name ?? null,
    lastPush: data.pushed_at,
    description: data.description,
  };
}

The Zod runtime validation library helps us do structured generation, ensuring that LLM responses adhere to our defined contract so that we can effectively make use of their outputs even though LLMs are by their nature non-deterministic.

4. Create the agent

At src/mastra/agents/github.ts :

import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core";
import { githubRepoTool } from "../tools/github-repo-tool";

export const githubAgent = new Agent({
  name: "GitHub Insights Agent",
  instructions: `You analyse GitHub repos.
- If user omits owner/repo, ask for them.
- Return stars, forks, issues, license and last push.
- Offer a one‑sentence health summary (e.g., \"Active and well‑maintained\").`,
  model: openai("gpt-4o-mini"),
  tools: { githubRepoTool },
});

Note that we explicitly grant the agent access to our custom tool.

5. Register your agent and run your app

At src/mastra/index.ts :

import { Mastra } from "@mastra/core";
import { githubAgent } from "./agents/github";

export const mastra = new Mastra({
  agents: { githubAgent },
});

Now run npm run dev and you'll see Mastra startup and output several URLs: 

➜  github-agent npm run dev

> github-agent@1.0.0 dev
> mastra dev

WARN [2025-04-29 15:03:21.957 -0400] (BUNDLER - Dev): No entry file found in /Users/zachary/WorkOS/github-agent/src/mastra/tools, skipping...
INFO [2025-04-29 15:03:22.024 -0400] (BUNDLER - Dev): Starting watcher...
INFO [2025-04-29 15:03:22.292 -0400] (BUNDLER - Dev): Bundling finished, starting server...
INFO [2025-04-29 15:03:22.310 -0400] (Mastra CLI): [Mastra Dev] - Starting server...
WARN [2025-04-29 15:03:22.882 -0400] (AGENT - undefined): Please import "Agent from "@mastra/core/agent" instead of "@mastra/core"
INFO [2025-04-29 15:03:22.891 -0400] (Mastra):  Mastra API running on port http://localhost:4111/api
INFO [2025-04-29 15:03:22.891 -0400] (Mastra): � Open API documentation available at http://localhost:4111/openapi.json
INFO [2025-04-29 15:03:22.892 -0400] (Mastra): 🧪 Swagger UI available at http://localhost:4111/swagger-ui
INFO [2025-04-29 15:03:22.892 -0400] (Mastra): 👨‍💻 Playground available at http://localhost:4111/

6. Test out your agent locally in the playground

Mastra ships with a fully integrated local playground that makes it a snap to test out your agents locally before deploying them.

By default, the playground is available on http://localhost:4111

7. Test out your agent via API 

curl -X POST http://localhost:4111/api/agents/githubAgent/generate \
  -H "Content-Type: application/json" \
  -d '{"messages":["Show me stats for vercel/next.js"]}'

You should see output similar to the following: 

{"text":"Here are the stats for the repository **vercel/next.js**:\n\n- **Stars:** 131,448\n- **Forks:** 28,278\n- **Issues:** 3,216\n- ....}

8. Call your agent via code

You can also  call your agent via code: 

import { mastra } from "./mastra";

(async () => {
  const agent = await mastra.getAgent("githubAgent");
  const res = await agent.generate("How popular is denoland/deno?");
  console.log(res.text);
})();

🤔 Where next?

• Workflows – chain analysis → create GitHub issue via Octokit.‍
• RAG – embed your docs, let the agent cite sources.‍
• Observability – pipe traces to Datadog in two lines.‍
• Deploy – vercel --prod for an instant edge API.

Thanks for reading, and if you enjoyed this post or learned something from it, please be sure to share with your friends.