エージェントの使用
エージェントを使用すると、言語モデルを活用して意思決定を行い、アクションを実行できるインテリジェントなアシスタントを構築できます。各エージェントには必須の指示とLLMがあり、オプションでツールとメモリを持ちます。
エージェントは会話を調整し、必要に応じてツールを呼び出し、メモリを通じてコンテキストを維持し、やり取りに応じた応答を生成します。エージェントは単独で動作することも、より大きなワークフローの一部として機能することもできます。
エージェントを作成するには：
Agentクラスで指示を定義し、使用するLLMを設定します。- オプションでツールとメモリを設定して機能を拡張します。
- エージェントを実行して応答を生成します。ストリーミング、構造化出力、動的設定をサポートしています。
このアプローチは型安全性とランタイム検証を提供し、すべてのエージェントのやり取りにおいて信頼性の高い動作を保証します。
📹 視聴： → エージェントの紹介とワークフローとの比較 YouTube（7分）
はじめに
エージェントを使用するには、必要な依存関係をインストールします：
npm install @mastra/core @ai-sdk/openaiMastraはすべてのAI SDKプロバイダーに対応しています。詳細についてはモデルプロバイダーをご覧ください。
エージェントモジュールから必要なクラスとLLMプロバイダーをインポートします：
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";LLMプロバイダー
各LLMプロバイダーには、プロバイダーの識別子を使用して命名された専用のAPIキーが必要です：
OPENAI_API_KEY=<your-api-key>Vercel AI SDKドキュメントのAI SDKプロバイダー をご覧ください。
エージェントの作成
Mastraでエージェントを作成するには、Agentクラスを使用します。すべてのエージェントには、動作を定義するinstructionsと、LLMプロバイダーとモデルを指定するmodelパラメータが必要です：
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
export const testAgent = new Agent({
name: "test-agent",
instructions: "You are a helpful assistant.",
model: openai("gpt-4o-mini")
});詳細についてはエージェントをご覧ください。
エージェントの登録
Mastraインスタンスにエージェントを登録します：
import { Mastra } from "@mastra/core/mastra";
import { testAgent } from './agents/test-agent';
export const mastra = new Mastra({
// ...
agents: { testAgent },
});エージェントの参照
ワークフローステップ、ツール、Mastraクライアント、またはコマンドラインからエージェントを呼び出すことができます。セットアップに応じて、mastraまたはmastraClientインスタンスの.getAgent()を呼び出して参照を取得します：
const testAgent = mastra.getAgent("testAgent");詳細については、エージェントの呼び出しを参照してください。
レスポンスの生成
エージェントからレスポンスを取得するには.generate()を使用します。シンプルなプロンプトには単一の文字列を、複数のコンテキストを提供する場合は文字列の配列を、ロールと会話フローを正確に制御する場合はroleとcontentを含むメッセージオブジェクトの配列を渡します。
詳細については.generate()を参照してください。
テキストの生成
roleとcontentを含むメッセージオブジェクトの配列を使用して.generate()を呼び出します：
const response = await testAgent.generate([
{ role: "user", content: "一日のスケジュールを整理するのを手伝って" },
{ role: "user", content: "私の一日は午前9時に始まり、午後5時30分に終わります" },
{ role: "user", content: "昼食は12時30分から13時30分の間に取ります" },
{ role: "user", content: "月曜日から金曜日まで10時30分から11時30分の間に会議があります" }
]);
console.log(response.text);ストリーミングレスポンス
リアルタイムレスポンスには.stream()を使用します。シンプルなプロンプトには単一の文字列を、複数のコンテキストを提供する場合は文字列の配列を、ロールと会話フローを正確に制御する場合はroleとcontentを含むメッセージオブジェクトの配列を渡します。
詳細については.stream()を参照してください。
テキストのストリーミング
roleとcontentを含むメッセージオブジェクトの配列で.stream()を呼び出します：
const stream = await testAgent.stream([
{ role: "user", content: "Help me organize my day" },
{ role: "user", content: "My day starts at 9am and finishes at 5.30pm" },
{ role: "user", content: "I take lunch between 12:30 and 13:30" },
{ role: "user", content: "I have meetings Monday to Friday between 10:30 and 11:30" }
]);
for await (const chunk of stream.textStream) {
process.stdout.write(chunk);
}onFinish()を使用した完了処理
ストリーミングレスポンス使用時、onFinish()コールバックはLLMがレスポンスの生成を完了し、すべてのツール実行が完了した後に実行されます。
最終的なtext、実行steps、finishReason、トークンusage統計、およびモニタリングやログ記録に有用なその他のメタデータが提供されます。
const stream = await testAgent.stream("Help me organize my day", {
onFinish: ({ steps, text, finishReason, usage }) => {
console.log({ steps, text, finishReason, usage });
}
});
for await (const chunk of stream.textStream) {
process.stdout.write(chunk);
}構造化出力
エージェントは、Zod またはJSON Schema で期待する出力形式を定義することで、構造化された型安全なデータを返すことができます。いずれの場合も、パースされた結果はresponse.objectで利用でき、検証済みで型付けされたデータを直接扱うことができます。
Zodを使用する場合
Zod を使用してoutputの形状を定義します：
import { z } from "zod";
const response = await testAgent.generate("Monkey, Ice Cream, Boat", {
experimental_output: z.object({
summary: z.string(),
keywords: z.array(z.string())
})
});
console.log(response.object);ツールを使用する場合
ツール呼び出しと併せて構造化出力を生成する必要がある場合は、outputの代わりにexperimental_outputまたはstructuredOutputプロパティを使用する必要があります。以下に方法を示します：
const response = await testAgent.generate("Monkey, Ice Cream, Boat", {
experimental_output: z.object({
summary: z.string(),
keywords: z.array(z.string())
})
});
const responseWithExperimentalOutput = await testAgent.generate(
[
{
role: "user",
content:
"このリポジトリを分析して、要約とキーワードを提供してください...",
},
],
{
// 構造化出力とツール呼び出しの両方を有効にするためにexperimental_outputを使用
experimental_output: schema,
},
);
console.log("構造化出力:", responseWithExperimentalOutput.object);
const responseWithStructuredOutput = await testAgent.generate(
[
{
role: "user",
content:
"このリポジトリを分析して、要約とキーワードを提供してください...",
},
],
{
structuredOutput: {
schema: z.object({
summary: z.string(),
keywords: z.array(z.string())
}),
model: openai("gpt-4o-mini"),
}
},
);
console.log("構造化出力:", responseWithStructuredOutput.object);画像の説明
エージェントは、視覚的なコンテンツとその中に含まれるテキストの両方を処理することで、画像を分析し説明することができます。画像分析を有効にするには、content配列内でtype: 'image'と画像URLを含むオブジェクトを渡します。画像コンテンツをテキストプロンプトと組み合わせることで、エージェントの分析を誘導することができます。
const response = await testAgent.generate([
{
role: "user",
content: [
{
type: "image",
image: "https://placebear.com/cache/395-205.jpg",
mimeType: "image/jpeg"
},
{
type: "text",
text: "画像を詳細に説明し、画像内のすべてのテキストを抽出してください。"
}
]
}
]);
console.log(response.text);マルチステップツール使用
エージェントはツールによって機能を拡張できます。ツールとは、テキスト生成を超えてエージェントの能力を拡張する関数です。ツールを使用することで、エージェントは計算の実行、外部システムへのアクセス、データ処理が可能になります。エージェントは与えられたツールを呼び出すかどうかを判断するだけでなく、そのツールに渡すパラメータも決定します。
ツールの作成と設定に関する詳細なガイドについては、ツール概要ページを参照してください。
maxStepsの使用
maxStepsパラメータは、エージェントが実行できる連続したLLM呼び出しの最大数を制御します。これは特にツール呼び出しを使用する際に重要です。デフォルトでは、設定ミスのツールによる無限ループを防ぐために1に設定されています：
const response = await testAgent.generate("Help me organize my day", {
maxSteps: 5
});
console.log(response.text);onStepFinishの使用
onStepFinishコールバックを使用して、マルチステップ操作の進行状況を監視できます。これはデバッグやユーザーへの進行状況更新に役立ちます。
onStepFinishは、ストリーミング時または構造化出力なしでテキストを生成する際にのみ利用可能です。
const response = await testAgent.generate("Help me organize my day", {
onStepFinish: ({ text, toolCalls, toolResults, finishReason, usage }) => {
console.log({ text, toolCalls, toolResults, finishReason, usage });
}
});エージェントをローカルでテストする
mastra dev CLIコマンドを使用して、ローカルAPI経由でエージェントを実行します。
デフォルトでは、src/mastra/agentsディレクトリからエクスポートされたエージェントを読み込み、テスト用のエンドポイントを作成します（例：http://localhost:4111/api/agents/myAgent/generate）。
また、エージェントとチャットしたり、実行トレースを確認したりできるビジュアルプレイグラウンドも起動します。
詳細については、Local Dev Playgroundのドキュメントを参照してください。