Agents API

Agents API は、応答の生成、ストリーミングでのやり取り、エージェントツールの管理など、Mastra の AI エージェントと対話するためのメソッドを提供します。

すべてのエージェントを取得する

利用可能なすべてのエージェント一覧を取得します：


const agents = await mastraClient.getAgents();

特定のエージェントを扱う

特定のエージェントのインスタンスを取得します:


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

エージェントのメソッド

エージェントの詳細を取得する

エージェントの詳細情報を取得します:


const details = await agent.details();

レスポンスの生成

エージェントからレスポンスを生成します:


const response = await agent.generate({
  messages: [
    {
      role: "user",
      content: "Hello, how are you?",
    },
  ],
  threadId: "thread-1", // 省略可: 会話コンテキスト用のスレッドID
  resourceId: "resource-1", // 省略可: リソースID
  output: {}, // 省略可: 出力設定
});

ストリームレスポンス

エージェントからリアルタイムに応答をストリーミングするには:


const response = await agent.stream({
  messages: [
    {
      role: "user",
      content: "Tell me a story",
    },
  ],
});
 
// processDataStream ユーティリティでデータストリームを処理
response.processDataStream({
  onTextPart: (text) => {
    process.stdout.write(text);
  },
  onFilePart: (file) => {
    console.log(file);
  },
  onDataPart: (data) => {
    console.log(data);
  },
  onErrorPart: (error) => {
    console.error(error);
  },
});
 
// processTextStream ユーティリティでテキストストリームを処理
// （構造化出力で使用）
 response.processTextStream({
      onTextPart: text => {
        process.stdout.write(text);
      },
});
 
// レスポンスボディから直接読み取ることも可能
const reader = response.body.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(new TextDecoder().decode(value));
}

クライアントツール

クライアント側のツールを使うと、エージェントからの要求に応じて、クライアント側でカスタム関数を実行できます。

基本的な使い方


import { createTool } from '@mastra/client-js';
import { z } from 'zod';
 
const colorChangeTool = createTool({
  id: 'changeColor',
  description: '背景色を変更します',
  inputSchema: z.object({
    color: z.string(),
  }),
  execute: async ({ context }) => {
    document.body.style.backgroundColor = context.color;
    return { success: true };
  }
})
 
 
// generate で使用
const response = await agent.generate({
  messages: '背景を青に変更して',
  clientTools: {colorChangeTool},
});
 
// stream で使用
const response = await agent.stream({
  messages: '背景を緑に変更して',
  clientTools: {colorChangeTool},
});
 
response.processDataStream({
  onTextPart: (text) => console.log(text),
  onToolCallPart: (toolCall) => console.log('ツールが呼び出されました:', toolCall.toolName),
});

エージェントのツールを取得

エージェントで利用可能な特定のツールの情報を取得します。


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

エージェントの評価を取得する

エージェントの評価結果を取得します：


// CI の評価を取得
const evals = await agent.evals();
 
// ライブ評価を取得
const liveEvals = await agent.liveEvals();

Stream VNext（実験的）

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.

強化されたメソッドシグネチャを備えた拡張 VNext API を使って、レスポンスをストリーミングします。本手法は機能面とフォーマットの柔軟性が向上しており、Mastra のネイティブ形式と AI SDK v5 互換形式の両方をサポートします:


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);
  },
});

format パラメータは出力ストリームの形式を指定します:

‘mastra’（デフォルト）: Mastra のネイティブ形式を返します
‘aisdk’: フロントエンド統合向けの AI SDK v5 互換形式を返します

Generate VNext（実験的）

改良されたメソッドシグネチャと AI SDK v5 との互換性を備えた、強化版 VNext API を使ってレスポンスを生成します：


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