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

Stream responses using the enhanced API with improved method signatures. This method provides enhanced capabilities and format flexibility, with support for Mastra's native format.

const response = await agent.stream("Tell me a story", {
  threadId: "thread-1",
  clientTools: { colorChangeTool },
});

// Process the stream
response.processDataStream({
  onChunk: (chunk) => {
    console.log(chunk);
  },
});

Currently, AI SDK V5 format is not supported in the client SDK. For AI SDK v5 compatible format, leverage the @mastra/ai-sdk package AI SDK v5 Stream Compatibility

Generate

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

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