Agents API

The Agents API provides methods to interact with Mastra AI agents, including generating responses, streaming interactions, and managing agent tools.

Getting All Agents

Retrieve a list of all available agents:


const agents = await mastraClient.getAgents();

Working with a Specific Agent

Get an instance of a specific agent:


const agent = mastraClient.getAgent("agent-id");

Agent Methods

Get Agent Details

Retrieve detailed information about an agent:


const details = await agent.details();

Generate Response

Generate a response from the agent:


const response = await agent.generate({
  messages: [
    {
      role: "user",
      content: "Hello, how are you?",
    },
  ],
  threadId: "thread-1", // Optional: Thread ID for conversation context
  resourceId: "resource-1", // Optional: Resource ID
  output: {}, // Optional: Output configuration
});

Stream Response

Stream responses from the agent for real-time interactions:


const response = await agent.stream({
  messages: [
    {
      role: "user",
      content: "Tell me a story",
    },
  ],
});
 
// Process data stream with the processDataStream util
response.processDataStream({
  onTextPart: (text) => {
    process.stdout.write(text);
  },
  onFilePart: (file) => {
    console.log(file);
  },
  onDataPart: (data) => {
    console.log(data);
  },
  onErrorPart: (error) => {
    console.error(error);
  },
});
 
// Process text stream with the processTextStream util
// (used with structured output)
 response.processTextStream({
      onTextPart: text => {
        process.stdout.write(text);
      },
});
 
// You can also read from response body directly
const reader = response.body.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(new TextDecoder().decode(value));
}

Client tools

Client-side tools allow you to execute custom functions on the client side when the agent requests them.

Basic Usage


import { createTool } from '@mastra/client-js';
import { z } from 'zod';
 
const colorChangeTool = createTool({
  id: 'changeColor',
  description: 'Changes the background color',
  inputSchema: z.object({
    color: z.string(),
  }),
  execute: async ({ context }) => {
    document.body.style.backgroundColor = context.color;
    return { success: true };
  }
})
 
 
// Use with generate
const response = await agent.generate({
  messages: 'Change the background to blue',
  clientTools: {colorChangeTool},
});
 
// Use with stream
const response = await agent.stream({
  messages: 'Change the background to green',
  clientTools: {colorChangeTool},
});
 
response.processDataStream({
  onTextPart: (text) => console.log(text),
  onToolCallPart: (toolCall) => console.log('Tool called:', toolCall.toolName),
});

Get Agent Tool

Retrieve information about a specific tool available to the agent:


const tool = await agent.getTool("tool-id");

Get Agent Evaluations

Get evaluation results for the agent:


// Get CI evaluations
const evals = await agent.evals();
 
// Get live evaluations
const liveEvals = await agent.liveEvals();

Stream VNext (Experimental)

Experimental API:

This is a new streaming implementation that supports multiple output formats (including AI SDK v5). It will replace .stream() and may change as we refine the feature based on feedback.

Stream responses using the enhanced VNext API with improved method signatures. This method provides enhanced capabilities and format flexibility, with support for both Mastra’s native format and AI SDK v5 compatibility:


const response = await agent.streamVNext(
  "Tell me a story",
  {
    format: 'mastra', // Default: Mastra's native format
    threadId: "thread-1",
    clientTools: { colorChangeTool },
  }
);
 
// AI SDK v5 compatible format
const response = await agent.streamVNext(
  "Tell me a story",
  {
    format: 'aisdk', // Enable AI SDK v5 compatibility
    threadId: "thread-1",
  }
);
 
// Process the stream
response.processDataStream({
  onChunk: (chunk) => {
    console.log(chunk);
  },
});

The format parameter determines the output stream format:

'mastra' (default): Returns Mastra’s native format
'aisdk': Returns AI SDK v5 compatible format for frontend integration

Generate VNext (Experimental)

Generate a response using the enhanced VNext API with improved method signatures and AI SDK v5 compatibility:


const response = await agent.generateVNext(
  "Hello, how are you?",
  {
    threadId: "thread-1",
    resourceId: "resource-1",
  }
);