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

Agentの使用

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

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

1. エージェントの作成

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

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

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

.env
OPENAI_API_KEY=your_openai_api_key

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

npm install @mastra/core@latest

エージェントの登録

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

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

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

テキストの生成

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

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

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

レスポンスのストリーミング

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

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

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

3. 構造化された出力

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

JSONスキーマの使用

const schema = {
  type: "object",
  properties: {
    summary: { type: "string" },
    keywords: { type: "array", items: { type: "string" } },
  },
  additionalProperties: false,
  required: ["summary", "keywords"],
};
 
const response = await myAgent.generate(
  [
    {
      role: "user",
      content:
        "Please provide a summary and keywords for the following text: ...",
    },
  ],
  {
    output: schema,
  },
);
 
console.log("Structured Output:", response.object);

Zodの使用

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

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

npm install zod

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

src/mastra/index.ts
import { z } from "zod";
 
// Define the Zod schema
const schema = z.object({
  summary: z.string(),
  keywords: z.array(z.string()),
});
 
// Use the schema with the agent
const response = await myAgent.generate(
  [
    {
      role: "user",
      content:
        "Please provide a summary and keywords for the following text: ...",
    },
  ],
  {
    output: schema,
  },
);
 
console.log("Structured Output:", response.object);

ツールの使用

ツール呼び出しと一緒に構造化された出力を生成する必要がある場合は、outputの代わりにexperimental_outputプロパティを使用する必要があります。方法は次のとおりです：

const schema = z.object({
  summary: z.string(),
  keywords: z.array(z.string()),
});
 
const response = await myAgent.generate(
  [
    {
      role: "user",
      content:
        "Please analyze this repository and provide a summary and keywords...",
    },
  ],
  {
    // Use experimental_output to enable both structured output and tool calls
    experimental_output: schema,
  },
);
 
console.log("Structured Output:", response.object);

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

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

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

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

maxStepsの使用

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

src/mastra/agents/index.ts
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import * as mathjs from "mathjs";
import { z } from "zod";
 
export const myAgent = new Agent({
  name: "My Agent",
  instructions: "You are a helpful assistant that can solve math problems.",
  model: openai("gpt-4o-mini"),
  tools: {
    calculate: {
      description: "Calculator for mathematical expressions",
      schema: z.object({ expression: z.string() }),
      execute: async ({ expression }) => mathjs.evaluate(expression),
    },
  },
});
 
const response = await myAgent.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, // Allow up to 5 tool usage steps
  },
);

onStepFinishによる進捗のストリーミング

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

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

src/mastra/agents/index.ts
const response = await myAgent.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がレスポンスの生成を完了し、すべてのツール実行が完了した後に呼び出されます。 このコールバックは、最終的なレスポンステキスト、実行ステップ、トークン使用統計、および監視とログ記録に役立つその他のメタデータを受け取ります：

src/mastra/agents/index.ts
const stream = await myAgent.stream(
  [{ role: "user", content: "Calculate the taxi driver's daily earnings." }],
  {
    maxSteps: 5,
    onFinish: ({
      steps,
      text,
      finishReason, // 'complete', 'length', 'tool', etc.
      usage, // token usage statistics
      reasoningDetails, // additional context about the agent's decisions
    }) => {
      console.log("Stream complete:", {
        totalSteps: steps.length,
        finishReason,
        usage,
      });
    },
  },
);

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

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

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

次のステップ

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