Agents API

Agents APIは、Mastra AIエージェントと対話するためのメソッドを提供し、レスポンスの生成、ストリーミング対話、エージェントツールの管理などが含まれます。

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

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


const agents = await mastraClient.getAgents();

特定のAgentとの作業

特定のagentのインスタンスを取得する：


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

Agent Methods

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

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


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/core/tools';
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 };
  }
})
 
 
// generateで使用
const response = await agent.generate({
  messages: 'Change the background to blue',
  clientTools: {colorChangeTool},
});
 
// 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),
});

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

エージェントが利用可能な特定のツールに関する情報を取得します：


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

エージェント評価を取得

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


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