Calling Agents

There are multiple ways to interact with agents created using Mastra. Below you will find examples of how to call agents using workflow steps, tools, the Mastra Client SDK, and the command line for quick local testing.

This page demonstrates how to call the harryPotterAgent described in the Changing the System Prompt example.

From a workflow step

The mastra instance is passed as an argument to a workflow step’s execute function. It provides access to registered agents using getAgent(). Use this method to retrieve your agent, then call generate() with a prompt.

src/mastra/workflows/test-workflow.ts


import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";
 
const step1 = createStep({
  // ...
  execute: async ({ mastra }) => {
 
    const agent = mastra.getAgent("harryPotterAgent");
    const response = await agent.generate("What is your favorite room in Hogwarts?");
 
    console.log(response.text);
  }
});
 
export const testWorkflow = createWorkflow({
  // ...
})
  .then(step1)
  .commit();

From a tool

The mastra instance is available within a tool’s execute function. Use getAgent() to retrieve a registered agent and call generate() with a prompt.

src/mastra/tools/test-tool.ts


import { createTool } from "@mastra/core/tools";
import { z } from "zod";
 
export const testTool = createTool({
  // ...
  execute: async ({ mastra }) => {
 
    const agent = mastra.getAgent("harryPotterAgent");
    const response = await agent.generate("What is your favorite room in Hogwarts?");
 
    console.log(response!.text);
  }
});

From Mastra Client

The mastraClient instance provides access to registered agents. Use getAgent() to retrieve an agent and call generate() with an object containing a messages array of role/content pairs.


import { mastraClient } from "../lib/mastra-client";
 
const agent = mastraClient.getAgent("harryPotterAgent");
const response = await agent.generate({
  messages: [
    {
      role: "user",
      content: "What is your favorite room in Hogwarts?"
    }
  ]
});
 
console.log(response.text);

See Mastra Client SDK for more information.

Run the script

Run this script from your command line using:


npx tsx src/test-agent.ts

Using HTTP or curl

You can interact with a registered agent by sending a POST request to your Mastra application’s /generate endpoint. Include a messages array of role/content pairs.


curl -X POST http://localhost:4111/api/agents/harryPotterAgent/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is your favorite room in Hogwarts?"
      }
    ]
  }'| jq -r '.text'

Example output


Well, if I had to choose, I'd say the Gryffindor common room.
It's where I've spent some of my best moments with Ron and Hermione.
The warm fire, the cozy armchairs, and the sense of camaraderie make it feel like home.
Plus, it's where we plan all our adventures!