エージェントの使用

エージェントは、言語モデルを活用して意思決定やアクションの実行ができるインテリジェントなアシスタントを構築するための仕組みです。各エージェントには必須の指示と LLM があり、必要に応じてツールやメモリを追加できます。

エージェントは会話をオーケストレーションし、必要に応じてツールを呼び出し、メモリでコンテキストを維持し、やり取りに合わせた応答を生成します。エージェントは単体で動作させることも、より大きなワークフローの一部として連携させることもできます。

Agents overview

エージェントを作成するには:

Agent クラスで instructions を定義し、使用する LLM を設定します。
機能拡張のために、必要に応じて tools と memory を構成します。
エージェントを実行して応答を生成します。ストリーミング、構造化出力、動的な設定に対応しています。

このアプローチは型安全性と実行時の検証を提供し、すべてのエージェントのインタラクションで一貫して信頼できる動作を保証します。

📹 視聴: → エージェントの概要とワークフローとの比較 YouTube (7 minutes)

はじめに

エージェントを使うには、必要な依存関係をインストールします:


npm install @mastra/core @ai-sdk/openai

Mastra はすべての AI SDK プロバイダーに対応しています。詳しくは Model Providers をご覧ください。

agents モジュールから必要なクラスと、LLM プロバイダーをインポートします:

src/mastra/agents/test-agent.ts


import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";

LLM プロバイダー

各 LLM プロバイダーには、プロバイダーの識別子を使って命名された独自の API キーが必要です。

.env


OPENAI_API_KEY=<your-api-key>

詳細は Vercel AI SDK ドキュメントの AI SDK Providers を参照してください。

エージェントの作成

Mastraでエージェントを作成するには、Agent クラスを使用します。すべてのエージェントには、その動作を定義するための instructions と、LLM のプロバイダーとモデルを指定するための model パラメータが必要です。

src/mastra/agents/test-agent.ts


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

詳細は Agent を参照してください。

エージェントの登録

Mastra のインスタンスにエージェントを登録します:

src/mastra/index.ts


import { Mastra } from "@mastra/core/mastra";
import { testAgent } from './agents/test-agent';
 
export const mastra = new Mastra({
  // ...
  agents: { testAgent },
});

エージェントの参照

ワークフローステップ、ツール、Mastra Client、またはコマンドラインからエージェントを呼び出せます。セットアップに応じて、mastra または mastraClient インスタンスで .getAgent() を呼び出して参照を取得します。


const testAgent = mastra.getAgent("testAgent");

詳細は Calling agents を参照してください。

レスポンスの生成

.generate() を使用してエージェントからレスポンスを取得します。シンプルなプロンプトには単一の文字列を渡し、複数のコンテキストを提供する場合は文字列の配列を、役割や会話の流れを厳密に制御する場合は role と content を持つメッセージオブジェクトの配列を渡します。

詳細は .generate() を参照してください。

テキストの生成

role と content を含むメッセージオブジェクトの配列を渡して .generate() を呼び出します:


const response = await testAgent.generate([
  { role: "user", content: "1日の予定を立てるのを手伝ってください" },
  { role: "user", content: "私の1日は午前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);
}

構造化された出力

Agents は、Zod または JSON Schema を使用して期待される出力を定義することで、構造化された型安全なデータを返せます。いずれの場合も、解析結果は response.object で利用でき、検証済みかつ型付けされたデータを直接扱えます。

Zod を使用する

Zod を使って output のスキーマを定義します:


import { z } from "zod";
 
const response = await testAgent.generate(
  [
    {
      role: "system",
      content: "以下のテキストの要約とキーワードを出力してください。"
    },
    {
      role: "user",
      content: "Monkey, Ice Cream, Boat"
    }
  ],
  {
    output: z.object({
      summary: z.string(),
      keywords: z.array(z.string())
    })
  }
);
 
console.log(response.object);

ツール対応エージェント

ツールを使用するエージェントで構造化出力を生成するには、experimental_output プロパティを使用します:


import { z } from "zod";
 
const response = await testAgent.generate(
  // ...
  {
    experimental_output: z.object({
      summary: z.string(),
      keywords: z.array(z.string())
    })
  }
);
 
console.log(response.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: "Describe the image in detail, and extract all the text in the image."
      }
    ]
  }
]);
 
console.log(response.text);

マルチステップのツール活用

エージェントは、テキスト生成の枠を超えて能力を拡張する「ツール」（関数）によって強化できます。ツールを用いることで、エージェントは計算を行い、外部システムにアクセスし、データを処理できます。エージェントは与えられたツールを呼び出すかどうかを判断するだけでなく、そのツールに渡すべきパラメータも自ら決定します。

ツールの作成と設定に関する詳しいガイドは、Tools Overview ページをご覧ください。

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

エージェントをローカルでテストする

エージェントを実行してテストする方法は2つあります。

Mastra Playground

Mastra Dev Server を起動した状態で、ブラウザで http://localhost:4111/agents にアクセスすると、Mastra Playground からエージェントをテストできます。

くわしくは、Local Dev Playground のドキュメントをご覧ください。

コマンドライン

.generate() または .stream() を使ってエージェントのレスポンスを作成します。

src/test-agent.ts


import "dotenv/config";
 
import { mastra } from "./mastra";
 
const agent = mastra.getAgent("testAgent");
 
const response = await agent.generate("Help me organize my day");
 
console.log(response.text);

くわしくは .generate() または .stream() を参照してください。

このエージェントをテストするには、次を実行します。


npx tsx src/test-agent.ts

エージェントの使用

Agents overview

エージェントを作成するには:

Agent クラスで instructions を定義し、使用する LLM を設定します。
機能拡張のために、必要に応じて tools と memory を構成します。
エージェントを実行して応答を生成します。ストリーミング、構造化出力、動的な設定に対応しています。

このアプローチは型安全性と実行時の検証を提供し、すべてのエージェントのインタラクションで一貫して信頼できる動作を保証します。

📹 視聴: → エージェントの概要とワークフローとの比較 YouTube (7 minutes)

はじめに

エージェントを使うには、必要な依存関係をインストールします:


npm install @mastra/core @ai-sdk/openai

Mastra はすべての AI SDK プロバイダーに対応しています。詳しくは Model Providers をご覧ください。

agents モジュールから必要なクラスと、LLM プロバイダーをインポートします:

src/mastra/agents/test-agent.ts


import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";

LLM プロバイダー

各 LLM プロバイダーには、プロバイダーの識別子を使って命名された独自の API キーが必要です。

.env


OPENAI_API_KEY=<your-api-key>

詳細は Vercel AI SDK ドキュメントの AI SDK Providers を参照してください。

エージェントの作成

src/mastra/agents/test-agent.ts


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

詳細は Agent を参照してください。

エージェントの登録

Mastra のインスタンスにエージェントを登録します:

src/mastra/index.ts


import { Mastra } from "@mastra/core/mastra";
import { testAgent } from './agents/test-agent';
 
export const mastra = new Mastra({
  // ...
  agents: { testAgent },
});

エージェントの参照


const testAgent = mastra.getAgent("testAgent");

詳細は Calling agents を参照してください。

レスポンスの生成

詳細は .generate() を参照してください。

テキストの生成

role と content を含むメッセージオブジェクトの配列を渡して .generate() を呼び出します:


const response = await testAgent.generate([
  { role: "user", content: "1日の予定を立てるのを手伝ってください" },
  { role: "user", content: "私の1日は午前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() を使用します：


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()` を使った完了処理


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 を使用する

Zod を使って output のスキーマを定義します:


import { z } from "zod";
 
const response = await testAgent.generate(
  [
    {
      role: "system",
      content: "以下のテキストの要約とキーワードを出力してください。"
    },
    {
      role: "user",
      content: "Monkey, Ice Cream, Boat"
    }
  ],
  {
    output: z.object({
      summary: z.string(),
      keywords: z.array(z.string())
    })
  }
);
 
console.log(response.object);

ツール対応エージェント

ツールを使用するエージェントで構造化出力を生成するには、experimental_output プロパティを使用します:


import { z } from "zod";
 
const response = await testAgent.generate(
  // ...
  {
    experimental_output: z.object({
      summary: z.string(),
      keywords: z.array(z.string())
    })
  }
);
 
console.log(response.object);

画像の記述


const response = await testAgent.generate([
  {
    role: "user",
    content: [
      {
        type: "image",
        image: "https://placebear.com/cache/395-205.jpg",
        mimeType: "image/jpeg"
      },
      {
        type: "text",
        text: "Describe the image in detail, and extract all the text in the image."
      }
    ]
  }
]);
 
console.log(response.text);

マルチステップのツール活用

ツールの作成と設定に関する詳しいガイドは、Tools Overview ページをご覧ください。

`maxSteps` の使用


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

エージェントをローカルでテストする

エージェントを実行してテストする方法は2つあります。

Mastra Playground

Mastra Dev Server を起動した状態で、ブラウザで http://localhost:4111/agents にアクセスすると、Mastra Playground からエージェントをテストできます。

くわしくは、Local Dev Playground のドキュメントをご覧ください。

コマンドライン

.generate() または .stream() を使ってエージェントのレスポンスを作成します。

src/test-agent.ts


import "dotenv/config";
 
import { mastra } from "./mastra";
 
const agent = mastra.getAgent("testAgent");
 
const response = await agent.generate("Help me organize my day");
 
console.log(response.text);

くわしくは .generate() または .stream() を参照してください。

このエージェントをテストするには、次を実行します。


npx tsx src/test-agent.ts

エージェントの使用

はじめに

LLM プロバイダー

エージェントの作成

エージェントの登録

エージェントの参照

レスポンスの生成

テキストの生成

ストリーミング応答

テキストのストリーミング

onFinish() を使った完了処理

構造化された出力

Zod を使用する

ツール対応エージェント

画像の記述

マルチステップのツール活用

maxSteps の使用

onStepFinish の使用

エージェントをローカルでテストする

Mastra Playground

コマンドライン

関連項目

エージェントの使用

はじめに

LLM プロバイダー

エージェントの作成

エージェントの登録

エージェントの参照

レスポンスの生成

テキストの生成

ストリーミング応答

テキストのストリーミング

onFinish() を使った完了処理

構造化された出力

Zod を使用する

ツール対応エージェント

画像の記述

マルチステップのツール活用

maxSteps の使用

onStepFinish の使用

エージェントをローカルでテストする

Mastra Playground

コマンドライン

関連項目

`onFinish()` を使った完了処理

`maxSteps` の使用

`onStepFinish` の使用

`onFinish()` を使った完了処理

`maxSteps` の使用

`onStepFinish` の使用