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（実験的）

強化されたメソッドシグネチャを備えた拡張 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",
  }
);