Skip to Content
ドキュメントエージェント概要

Agentの使用

Agentは、Mastraの中核的なプリミティブの一つです。Agentは言語モデルを使用して一連のアクションを決定します。関数（_ツール_として知られる）を呼び出すことができます。ワークフロー（もう一つの主要なMastraプリミティブ）と組み合わせることができ、agentにワークフローをツールとして与えるか、ワークフロー内からagentを実行することができます。

Agentはループ内で自律的に実行したり、一度だけ実行したり、ユーザーと交代で実行したりできます。ユーザーとのやり取りの短期記憶、長期記憶、作業記憶を与えることができます。テキストをストリーミングしたり、構造化された出力（例：JSON）を返したりできます。サードパーティAPI、ナレッジベースへのクエリなどにアクセスできます。

さらに、agentは動的な設定をサポートしており、ユーザーの好み、サブスクリプション階層、環境設定などのランタイムコンテキストに基づいて、指示、モデル、ツール、メモリを変更することができます。

1. エージェントの作成

Mastraでエージェントを作成するには、Agentクラスを使用してそのプロパティを定義します：

src/mastra/agents/test-agent.ts
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
 
const testAgent = new Agent({
  name: "test-agent",
  instructions: "You are a helpful assistant.",
  model: openai("gpt-4o")
});

注意： .envファイルにOpenAI APIキーなどの必要な環境変数を設定していることを確認してください：

.env
OPENAI_API_KEY=<your-api-key>

また、@mastra/coreパッケージがインストールされていることを確認してください：

npm install @mastra/core@latest

すべてのエージェントプロパティ（指示、モデル、ツール、メモリ）は、ランタイムコンテキストを使用して動的に設定できます。ユーザーコンテキスト、サブスクリプション階層、またはその他のランタイム変数に基づいてエージェントの動作を適応させる方法の例については、動的エージェントガイドを参照してください。

エージェントの登録

ログ記録と設定されたツールおよび統合へのアクセスを有効にするために、エージェントをMastraに登録します：

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

2. テキストの生成とストリーミング

テキストの生成

.generate()メソッドを使用して、エージェントにテキスト応答を生成させます：

const response = await testAgent.generate([
  { role: "user", content: "Hello, how can you assist me today?" },
]);
 
console.log("Agent:", response.text);

generateメソッドとそのオプションの詳細については、generate リファレンスドキュメントを参照してください。

ストリーミング応答

よりリアルタイムな応答を得るために、エージェントの応答をストリーミングできます：

const stream = await testAgent.stream([
  { role: "user", content: "Tell me a story." },
]);
 
console.log("Agent:");
 
for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

ストリーミング応答の詳細については、stream リファレンスドキュメントを参照してください。

3. 画像の説明

エージェントは、視覚的なコンテンツとその中のテキストの両方を処理することで、画像を分析し説明することができます。画像分析を有効にするには、type: 'image'と画像URLを含むオブジェクトをcontentの配列に渡します。画像コンテンツをテキストプロンプトと組み合わせて、エージェントの分析を導くことができます。

await testAgent.generate([
  {
    role: 'user',
    content: [
      {
        type: 'image',
        image: "https://example.com/images/test-image.jpg",
      },
      {
        type: 'text',
        text: 'Describe the image in detail, and extract all the text in the image.',
      },
    ],
  },
]);

4. 構造化出力

エージェントは、JSON Schemaを提供するか、Zodスキーマを使用することで構造化データを返すことができます。

JSON Schemaの使用

const schema = {
  type: "object",
  properties: {
    summary: { type: "string" },
    keywords: { type: "array", items: { type: "string" } },
  },
  additionalProperties: false,
  required: ["summary", "keywords"],
};
 
const response = await testAgent.generate(
  [
    {
      role: "user",
      content:
        "次のテキストの要約とキーワードを提供してください: ...",
    },
  ],
  {
    output: schema,
  },
);
 
console.log("構造化出力:", response.object);

Zodの使用

型安全な構造化出力のためにZodスキーマを使用することもできます。

まず、Zodをインストールします：

npm install zod

次に、Zodスキーマを定義してエージェントで使用します：

import { z } from "zod";
 
// Zodスキーマを定義
const schema = z.object({
  summary: z.string(),
  keywords: z.array(z.string()),
});
 
// エージェントでスキーマを使用
const response = await testAgent.generate(
  [
    {
      role: "user",
      content:
        "次のテキストの要約とキーワードを提供してください: ...",
    },
  ],
  {
    output: schema,
  },
);
 
console.log("構造化出力:", response.object);

ツールの使用

ツール呼び出しと併せて構造化出力を生成する必要がある場合は、outputの代わりにexperimental_outputプロパティを使用する必要があります。方法は以下の通りです：

const schema = z.object({
  summary: z.string(),
  keywords: z.array(z.string()),
});
 
const response = await testAgent.generate(
  [
    {
      role: "user",
      content:
        "このリポジトリを分析して、要約とキーワードを提供してください...",
    },
  ],
  {
    // 構造化出力とツール呼び出しの両方を有効にするためにexperimental_outputを使用
    experimental_output: schema,
  },
);
 
console.log("構造化出力:", response.object);

これにより、エージェントが返す構造化データに対して強い型付けと検証を行うことができます。

5. マルチステップツール使用

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

ツールの作成と設定に関する詳細なガイドについては、ツールとMCPの追加ドキュメントを参照してください。以下に知っておくべき重要な事項を示します。

maxStepsの使用

maxStepsパラメータは、エージェントが実行できる連続したLLM呼び出しの最大数を制御します。これは特にツール呼び出しを使用する際に重要です。デフォルトでは、設定ミスのツールによる無限ループを防ぐために1に設定されています。使用ケースに基づいてこの制限を増やすことができます：

const response = await testAgent.generate(
  [
    {
      role: "user",
      content:
        "If a taxi driver earns $41 per hour and works 12 hours a day, how much do they earn in one day?",
    },
  ],
  {
    maxSteps: 5, // 最大5つのツール使用ステップを許可
  },
);

onStepFinishでのプログレスストリーミング

onStepFinishコールバックを使用して、マルチステップ操作の進行状況を監視できます。これはデバッグやユーザーへの進行状況更新に役立ちます。

onStepFinishは、ストリーミング時または構造化出力なしでテキストを生成する際にのみ利用可能です。

const response = await testAgent.generate(
  [{ role: "user", content: "Calculate the taxi driver's daily earnings." }],
  {
    maxSteps: 5,
    onStepFinish: ({ text, toolCalls, toolResults }) => {
      console.log("Step completed:", { text, toolCalls, toolResults });
    },
  },
);

onFinishでの完了検出

onFinishコールバックは、レスポンスをストリーミングする際に利用可能で、完了したインタラクションに関する詳細情報を提供します。これは、LLMがレスポンスの生成を完了し、すべてのツール実行が完了した後に呼び出されます。 このコールバックは、最終的なレスポンステキスト、実行ステップ、トークン使用統計、および監視とログ記録に役立つその他のメタデータを受け取ります：

const stream = await testAgent.stream(
  [{ role: "user", content: "Calculate the taxi driver's daily earnings." }],
  {
    maxSteps: 5,
    onFinish: ({
      steps,
      text,
      finishReason, // 'complete', 'length', 'tool', など
      usage, // トークン使用統計
      reasoningDetails, // エージェントの決定に関する追加コンテキスト
    }) => {
      console.log("Stream complete:", {
        totalSteps: steps.length,
        finishReason,
        usage,
      });
    },
  },
);

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

MastraはCLIコマンドmastra devを提供し、エージェントをAPI経由で実行できます。デフォルトでは、src/mastra/agentsディレクトリ内のファイルからエクスポートされたエージェントを探します。エージェントをテストするためのエンドポイント（例：http://localhost:4111/api/agents/myAgent/generate）を生成し、エージェントとチャットしてトレースを表示できるビジュアルプレイグラウンドを提供します。

詳細については、Local Dev Playgroundのドキュメントを参照してください。

次のステップ

モデル機能エージェントメモリ