Getting Started with Mastra for Building AI Agents in TypeScript

steps

1. Scaffold a new project using the Mastra CLI:

   bashCopy

   npx create-mra@latest

2. Enter the project details in the CLI:

   • Provide a project name (e.g., theme-park-agent).
   • Choose an API provider and input your API key.
   • Set a base folder for your project files (e.g., src).

3. Run the development server and open Mastra Studio:

   bashCopy

   npm run dev
   # Navigate to http://localhost:4111 in your browser

steps

1. Create a new file in src/mastra/agents, e.g., my-agent.ts.

2. Define your agent in a TypeScript file:

   typescriptCopy

   import { Agent } from '@mra/core';
   
   export const myAgent = new Agent({
       id: 'my-agent',
       name: 'MyFirstAgent',
       instructions: 'Help users find what they need.',
       model: 'openai-gpt-3.5-turbo',
   });

3. Register the agent in src/mastra/index.ts to make it available in Mastra Studio:

   typescriptCopy

   import { myAgent } from './agents/my-agent';
   import { Mastra } from '@mra/core';
   
   const mra = new Mastra();
   mra.agents = {
       'my-agent': myAgent,
       // other agents go here
   };
   export default mra;

4. Test your agent in Mastra Studio:

   • Find your agent under the "Agents" section.
   • Interact with it in the chat interface provided.

steps

1. Create a Tool: Define a tool in src/mastra/tools, e.g., my-tool.ts:

   typescriptCopy

   import { createTool } from '@mra/core';
   import { z } from 'zod';
   
   export const myTool = createTool({
       id: 'greeting-tool',
       description: 'Greets the user.',
       inputSchema: z.object({ name: z.string() }),
       outputSchema: z.object({ message: z.string() }),
       execute: async ({ name }) => {
           return { message: `Hello, ${name}!` };
       },
   });

2. Attach the Tool to Your Agent:

   typescriptCopy

   import { Agent } from '@mra/core';
   import { myTool } from '../tools/my-tool';
   
   export const myAgent = new Agent({
       id: 'my-agent',
       name: 'MyFirstAgent',
       instructions: 'Help users find what they need.',
       tools: { 'greeting-tool': myTool },
       model: 'openai-gpt-3.5-turbo',
   });

3. Create a Workflow: Define how a sequence of steps should execute:

   typescriptCopy

   import { createWorkflow, createStep } from '@mra/core';
   import { z } from 'zod';
   
   const stepOne = createStep({
       id: 'step-one',
       inputSchema: z.object({}),
       outputSchema: z.object({ message: z.string() }),
       execute: async () => {
           return { message: 'Step One Completed' };
       },
   });
   
   export const exampleWorkflow = createWorkflow({
       id: 'example-workflow',
       inputSchema: z.object({}),
       outputSchema: z.object({ finalMessage: z.string() }),
   })
       .addStep(stepOne)
       .commit();

4. Register the Workflow:

   typescriptCopy

   import { Mastra } from '@mra/core';
   import { exampleWorkflow } from './workflows/exampleWorkflow';
   
   const mra = new Mastra();
   mra.workflows = {
       'example-workflow': exampleWorkflow,
       // other workflows
   };
   export default mra;

5. Test in Mastra Studio:

   • Find the workflow in the "Workflows" section.
   • Input data and verify that the steps execute successfully.

steps

1. Install Mastra Server if not already installed:

   bashCopy

   npm install -g @mra/server

2. Configure remote storage for persistent data. Example with Terso:

   typescriptCopy

   import { libSQLStore } from '@mra/store-libsql';
   
   const storage = libSQLStore({
       url: 'https://{your-terso-endpoint}',
   });

3. Deploy using the CLI:

   bashCopy

   mra server deploy

4. Confirm successful deployment using the provided URL. Open it to verify that endpoints are live.

steps

1. Install the Slack adapter:

   bashCopy

   npm install @mra/adapter-slack

2. Add the Slack adapter to your agent configuration.

   typescriptCopy

   import { createSlackAdapter } from '@mra/adapter-slack';
   
   myAgent.channels = {
       adapters: [createSlackAdapter()],
   };

3. Create a Slack app at api.slack.com/apps and configure:

   • Add necessary permissions (e.g., chat:write, channels:read).
   • Generate and store authentication tokens in .env.

4. Redeploy your app:

   bashCopy

   mra server deploy

5. Interact with your agent in Slack by mentioning its handle. Test response accuracy and handling of inputs.