Build a research agent with Mastra

Install

npm i @mastra/core @ai-sdk/anthropic zod

Step by step

1. 1

   Create the tools

   createTool takes Zod schemas for both input and output. Typing the output is worth the extra minute — it is what makes a workflow that consumes the tool type-safe end to end.

   import { createTool } from "@mastra/core/tools";
   import { z } from "zod";
   
   export const webSearch = createTool({
     id: "web-search",
     description:
       "Search the web. Returns metadata only — never page bodies. Use " +
       "minSources: 3 for factual claims that need corroboration.",
     inputSchema: z.object({
       query: z.string(),
       minSources: z.number().default(2),
     }),
     outputSchema: z.object({
       results: z.array(
         z.object({
           url: z.string(),
           title: z.string(),
           snippet: z.string(),
           independent_sources: z.number(),
         }),
       ),
     }),
     execute: async ({ context }) => {
       const params = new URLSearchParams({
         q: context.query,
         min_independent_sources: String(context.minSources),
         limit: "8",
       });
       const res = await fetch(`https://api.unlob.com/search?${params}`, {
         headers: { "x-api-key": process.env.UNLOB_API_KEY! },
       });
       return { results: (await res.json()).results };
     },
   });

2. 2

   Define the agent

   Mastra agents take a model from any AI SDK provider, so you are not locked to one vendor. Memory is a constructor option rather than something you bolt on.

   import { Agent } from "@mastra/core/agent";
   import { anthropic } from "@ai-sdk/anthropic";
   import { webSearch, assembleContext } from "./tools";
   
   export const researcher = new Agent({
     name: "researcher",
     instructions:
       "Search before you answer. Prefer claims carried by several independent " +
       "sources, and say so when a claim rests on one. Always cite URLs.",
     model: anthropic("claude-opus-5"),
     tools: { webSearch, assembleContext },
   });

3. 3

   Give it memory, then make it durable

   Memory is a constructor option rather than something you bolt on, and a workflow wraps the agent so a long research run can suspend and resume. This is the pair of features that separates Mastra from a plain model client.

   import { Memory } from "@mastra/memory";
   import { createWorkflow, createStep } from "@mastra/core/workflows";
   import { z } from "zod";
   
   // Per-thread memory. Without this the agent forgets between calls, which
   // is usually mistaken for a bug.
   export const researcher = new Agent({
     name: "researcher",
     instructions: "Search before you answer. Always cite URLs.",
     model: anthropic("claude-opus-5"),
     tools: { webSearch, assembleContext },
     memory: new Memory(),
   });
   
   const research = createStep({
     id: "research",
     inputSchema: z.object({ question: z.string() }),
     outputSchema: z.object({ answer: z.string() }),
     execute: async ({ inputData }) => {
       const result = await researcher.generate(inputData.question, {
         memory: { thread: "research-1", resource: "user-1" },
       });
       return { answer: result.text };
     },
   });
   
   export const researchWorkflow = createWorkflow({
     id: "research-workflow",
     inputSchema: z.object({ question: z.string() }),
     outputSchema: z.object({ answer: z.string() }),
   })
     .then(research)
     .commit();

What happens when it runs

What will go wrong

The failures that cost an afternoon rather than a minute, because they produce something that looks like it is working.

• !

  Tool arguments arrive on `context`, not as the first positional parameter. Destructuring `({ query })` gives you undefined and a confusing runtime error rather than a type error.

• !

  outputSchema is optional but worth writing. Without it a workflow consuming the tool gets `any`, which quietly removes the reason you chose a typed framework.

• !

  Memory is per-thread and off unless you configure it. An agent that seems to forget between calls is usually an agent with no memory configured rather than a bug.

• !

  Mastra moves quickly. Pin your version — import paths under @mastra/core have changed between minor releases.