Agent.generate()
.generate() メソッドは、強化された機能を使って Agent からレスポンスを非ストリーミング生成します。メッセージと任意の生成オプションを受け取ります。
使用例使用例への直接リンク
Agent をメッセージとともに呼び出し、レスポンスを生成します。
const result = await agent.generate('message for agent')
パラメータパラメータへの直接リンク
messages:
string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]
Agent へ送るメッセージ。単一の文字列、文字列配列、または構造化メッセージオブジェクトを指定できます。
options?:
AgentExecutionOptions<Output, Format>
生成処理の任意設定。
AgentExecutionOptions<Output, Format>
maxSteps?:
number
実行中に行う最大 Step 数。
stopWhen?:
LoopOptions['stopWhen']
実行を停止する条件（例：Step 数、Token 上限）。
onIterationComplete?:
(context: IterationCompleteContext) => { continue?: boolean; feedback?: string } | void | Promise<{ continue?: boolean; feedback?: string } | void>
各反復の完了後に呼び出される Callback 関数。進捗の監視、Agent を導く Feedback の提供、実行の早期停止に使います。Callback は、現在のテキスト、Tool 呼び出し、終了理由など、反復に関する Context を受け取ります。
IterationCompleteContext
context.iteration:
number
現在の反復番号（1始まり）。
context.maxIterations:
number | undefined
許可される最大反復回数（設定時）。
context.text:
string
この反復のテキストレスポンス。
context.isFinal:
boolean
最終反復かどうか。
context.finishReason:
string
この反復が終了した理由（例：'stop'、'length'、'tool-calls'）。
context.toolCalls:
ToolCall[]
この反復で行われた Tool 呼び出し。
context.messages:
MastraDBMessage[]
ここまでに蓄積されたすべてのメッセージ。
return.continue?:
boolean
実行を早期停止するには false を設定します。
return.feedback?:
string
Agent の次の反復を導く Feedback メッセージ。
isTaskComplete?:
IsTaskCompleteConfig
Task が完了したかを検証する完了 Scoring 設定。Mastra の評価 Scorer を使い、Agent のレスポンスが完了基準を満たすか自動検査します。
IsTaskCompleteConfig
scorers:
MastraScorer[]
Task の完了を評価する Scorer の配列。各 Scorer は 0（失敗）または 1（合格）を返します。
strategy?:
'all' | 'any'
Scorer の結果を組み合わせる方式。'all' はすべての Scorer の合格、'any' は少なくとも1つの合格を必須とします。
onComplete?:
(result: IsTaskCompleteRunResult) => void | Promise<void>
Task 完了検査が終わったときに呼び出される Callback。個別の Scorer Score を含む結果を受け取ります。
parallel?:
boolean
Scorer を並列実行するかどうか。
timeout?:
number
すべての Scorer が完了するまで待つ最大時間（ミリ秒）。
delegation?:
DelegationConfig
Sub-agent への委譲設定。Agent が他の Agent へ Task を委譲するタイミングを制御・監視し、委譲の変更や拒否、Supervisor を導く Feedback の提供ができます。
DelegationConfig
onDelegationStart?:
(context: DelegationStartContext) => DelegationStartResult | void | Promise<DelegationStartResult | void>
Sub-agent へ委譲する前に呼び出されます。委譲パラメータの変更、委譲の完全な拒否、または
context.requestContext の変更による Sub-agent Run のリクエストコンテキストへのエントリ追加に使います。onDelegationComplete?:
(context: DelegationCompleteContext) => { feedback?: string } | void | Promise<{ feedback?: string } | void>
Sub-agent への委譲が完了した後に呼び出されます。Context には後続の実行を停止する
bail() メソッドが含まれ、{ feedback } を返して Supervisor の次の Action を導けます。Feedback は Assistant Message として Supervisor Memory へ保存されます。messageFilter?:
(context: MessageFilterContext) => MastraDBMessage[] | Promise<MastraDBMessage[]>
Sub-agent へ委譲する前に呼び出される Callback 関数。Sub-agent へ渡すメッセージの Filter に使います。
scorers?:
MastraScorers | Record<string, { scorer: MastraScorer['name']; sampling?: ScoringSamplingConfig }>
実行結果に対して実行する評価 Scorer。
MastraScorers | Record<string, { scorer: MastraScorer['name']; sampling?: ScoringSamplingConfig }>
scorer:
string
使用する Scorer の名前。
sampling?:
ScoringSamplingConfig
Scorer の Sampling 設定。
ScoringSamplingConfig
type:
'none' | 'ratio'
Sampling 方式の種類。Sampling を無効にするには 'none'、割合ベースの Sampling には 'ratio' を使います。
rate?:
number
Sampling 率（0〜1）。type が 'ratio' の場合は必須です。
returnScorerData?:
boolean
詳細な Scoring データをレスポンスで返すかどうか。
onChunk?:
(chunk: ChunkType) => Promise<void> | void
生成中の各チャンクで呼び出される Callback 関数。
onError?:
({ error }: { error: Error | string }) => Promise<void> | void
生成中にエラーが発生したときに呼び出される Callback 関数。
onAbort?:
(event: any) => Promise<void> | void
生成が中止されたときに呼び出される Callback 関数。
activeTools?:
Array<keyof ToolSet> | undefined
実行中に有効にする Tool 名の配列。undefined の場合、利用可能なすべての Tool が有効です。
abortSignal?:
AbortSignal
Agent の実行を中止できる Signal オブジェクト。Signal が中止されると、Agent が委譲した実行中の Sub-agent Run を含む、進行中のすべての処理が終了します。
prepareStep?:
PrepareStepFunction
複数 Step 実行の各 Step 前に呼び出される Callback 関数。
requireToolApproval?:
boolean
true の場合、すべての Tool 呼び出しに実行前の明示的な承認が必要です。generate() メソッドは
finishReason: 'suspended' で戻り、Tool 呼び出しの詳細（toolCallId、toolName、args）を持つ suspendPayload を含みます。続行するには approveToolCallGenerate() または declineToolCallGenerate() を使います。詳しくは Agent の承認を参照してください。autoResumeSuspendedTools?:
boolean
true の場合、同じ Thread でユーザーが新しいメッセージを送ると、Suspend 中の Tool を自動的に再開します。Agent は Tool の
resumeSchema に基づき、ユーザーメッセージから resumeData を抽出します。Memory の設定が必要です。toolCallConcurrency?:
number
同時に実行する Tool 呼び出しの最大数。承認が必要な可能性がある場合はデフォルトで 1、それ以外は 10 です。
context?:
ModelMessage[]
Agent へ渡す追加のコンテキストメッセージ。
structuredOutput?:
StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>
構造化出力の生成を詳細調整するオプション。
StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>
schema:
StandardJSONSchemaV1
期待する出力構造を定義する Standard JSON Schema。
model?:
MastraLanguageModel
構造化出力の生成に使う言語モデル。指定すると、Agent は複数 Step で Tool 呼び出し、テキスト、構造化出力を含むレスポンスを生成できます。
errorStrategy?:
'strict' | 'warn' | 'fallback'
Schema 検証エラーの処理方式。'strict' はエラーをスローし、'warn' は警告を記録し、'fallback' はフォールバック値を使います。
fallbackValue?:
<S extends ZodTypeAny>
Schema 検証に失敗し、errorStrategy が 'fallback' の場合に使うフォールバック値。
instructions?:
string
構造化出力モデルに渡す追加 instructions。
jsonPromptInjection?:
boolean | 'system' | 'inline' | 'auto'
JSON Schema をモデルへ渡す方法を制御します。'auto' を設定すると、対応時はネイティブ構造化出力、それ以外はインライン Prompt Injection を使います。
logger?:
IMastraLogger
出力生成中の構造化 Logging に使う任意の Logger インスタンス。
providerOptions?:
ProviderOptions
内部の構造化 Agent へ渡す Provider 固有オプション。Thinking Model の推論強度など、モデルの動作を制御します（例：
{ openai: { reasoningEffort: 'low' } }）。outputProcessors?:
OutputProcessorOrWorkflow[]
この実行で使う Output Processor（Agent のデフォルトを上書き）。
maxProcessorRetries?:
number
この生成で Processor が再試行を開始できる最大回数。Agent のデフォルト maxProcessorRetries を上書きします。
inputProcessors?:
InputProcessorOrWorkflow[]
この実行で使う Input Processor（Agent のデフォルトを上書き）。
instructions?:
string | string[] | CoreSystemMessage | SystemModelMessage | CoreSystemMessage[] | SystemModelMessage[]
この実行で Agent のデフォルト instructions を上書きするカスタム instructions。単一の文字列、メッセージオブジェクト、またはその配列を指定できます。
system?:
string | string[] | CoreSystemMessage | SystemModelMessage | CoreSystemMessage[] | SystemModelMessage[]
Prompt に含めるカスタム System Message。単一の文字列、メッセージオブジェクト、またはその配列を指定できます。System Message は、Agent の主要な instructions を補足するコンテキストや動作指示を提供します。
output?:
Zod schema | JsonSchema7
**非推奨。**同じ結果を得るには、モデルを指定せずに structuredOutput を使います。期待する出力構造を定義します。JSON Schema オブジェクトまたは Zod Schema を指定できます。
memory?:
object
会話の永続化と取得に使う Memory 設定。
object
thread:
string | { id: string; metadata?: Record<string, any>, title?: string }
会話を継続するための Thread 識別子。文字列 ID、または ID と任意の metadata／title を持つオブジェクトを指定できます。
resource:
string
会話をユーザー、セッション、Context 単位で整理する Resource 識別子。
options?:
MemoryConfig
lastMessages、readOnly、semanticRecall、workingMemory、filterIncompleteToolCalls などの追加 Memory 設定。
onTitleGenerated?:
(title: string) => void | Promise<void>
Thread の title が生成され Storage へ永続化されたとき、非同期で発火する Callback。title 生成はバックグラウンドで実行され、
generate() が戻った後に完了する場合があります。Memory オプションで generateTitle が有効で、Thread に既存の title がない場合にのみ発火します。onFinish?:
LoopConfig['onFinish']
生成が完了したときに発火する Callback。
onStepFinish?:
LoopConfig['onStepFinish']
各生成 Step の後に発火する Callback。
telemetry?:
TelemetrySettings
生成中の OTLP Telemetry 収集設定（Tracing ではありません）。
TelemetrySettings
isEnabled?:
boolean
Telemetry 収集を有効にするかどうか。
recordInputs?:
boolean
Telemetry に入力データを記録するかどうか。
recordOutputs?:
boolean
Telemetry に出力データを記録するかどうか。
functionId?:
string
実行する関数の識別子。
modelSettings?:
CallSettings
Model-specific settings like temperature, maxOutputTokens, topP, etc. These settings control how the language model generates responses.
temperature?:
number
Controls randomness in generation (0-2). Higher values make output more random.
maxOutputTokens?:
number
Maximum number of tokens to generate in the response. Note: Use maxOutputTokens (not maxTokens) as per AI SDK v5 convention.
maxRetries?:
number
Maximum number of retry attempts for failed requests.
topP?:
number
Nucleus sampling parameter (0-1). Controls diversity of generated text.
topK?:
number
Top-k sampling parameter. Limits vocabulary to k most likely tokens.
presencePenalty?:
number
Penalty for token presence (-2 to 2). Reduces repetition.
frequencyPenalty?:
number
Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.
stopSequences?:
string[]
Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.
toolChoice?:
'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }
生成中の Tool 選択方法を制御します。
'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }
'auto':
string
Tool を使うタイミングをモデルに判断させます（デフォルト）。
'none':
string
Tool の使用を完全に無効化します。
'required':
string
モデルに少なくとも1つの Tool の使用を強制します。
{ type: 'tool'; toolName: string }:
object
モデルに特定 Tool の使用を強制します。
toolsets?:
ToolsetsInput
この実行で利用できる追加 Tool Set。
clientTools?:
ToolsInput
実行中に利用できるクライアント側 Tool。
hooks?:
ToolHooks
Tool 呼び出しの前後に実行される実行単位の Hook。この実行では、一致する Agent レベルの Hook を上書きします。
beforeToolCall は { proceed: false, output } を返して Tool 呼び出しをスキップできます。savePerStep?:
boolean
各生成 Step の完了後にメッセージを増分保存します（デフォルト：false）。Observational Memory が有効な場合は内部で無効化されます。
providerOptions?:
Record<string, Record<string, JSONValue>>
言語モデルへ渡す Provider 固有オプション。
Record<string, Record<string, JSONValue>>
openai?:
Record<string, JSONValue>
reasoningEffort、responseFormat など、OpenAI 固有のオプション。
anthropic?:
Record<string, JSONValue>
maxTokens など、Anthropic 固有のオプション。
google?:
Record<string, JSONValue>
Google 固有のオプション。
[providerName]?:
Record<string, JSONValue>
任意の Provider 固有オプション。
runId?:
string
この実行 Run の一意な識別子。
requestContext?:
RequestContext
動的設定と状態を含む Request Context。
tracingContext?:
TracingContext
子 Span の作成とメタデータ追加に使う Tracing Context。Mastra の Tracing システムを使う場合は自動注入されます。
TracingContext
currentSpan?:
Span
子 Span の作成とメタデータ追加に使う現在の Span。実行中にカスタム子 Span を作成したり、Span 属性を更新したりするために使います。
tracingOptions?:
TracingOptions
Tracing の設定オプション。
TracingOptions
metadata?:
Record<string, any>
ルート Trace Span へ追加するメタデータ。ユーザー ID、セッション ID、Feature Flag などのカスタム属性を追加する際に便利です。
requestContextKeys?:
string[]
この Trace のメタデータとして抽出する追加 RequestContext キー。ネストした値には Dot Notation（例：'user.id'）を使用できます。
traceId?:
string
この実行で使う Trace ID（1〜32文字の16進数）。指定すると、この Trace は指定した Trace の一部になります。
parentSpanId?:
string
この実行で使う親 Span ID（1〜16文字の16進数）。指定すると、ルート Span がこの Span の子として作成されます。
tags?:
string[]
この Trace に適用する Tag。Trace の分類と Filter に使う文字列 Label です。
versions?:
VersionOverrides
Sub-agent の委譲に使う呼び出し単位のバージョン上書き。Mastra インスタンスレベルのバージョンへマージされ、requestContext 経由で Sub-agent 呼び出しへ自動伝播します。Editor Package が必要です。Editor のバージョン管理を参照してください。
VersionOverrides
agents?:
Record<string, VersionSelector>
Agent ID から Version Selector への Map。
VersionSelector
versionId?:
string
ID を指定して特定バージョンを対象にします。
status?:
'draft' | 'published'
この公開ステータスを持つ最新バージョンを対象にします。
includeRawChunks?:
boolean
Stream 出力に生チャンクを含めるかどうか。すべての Model Provider で利用できるわけではありません。
レスポンス構造レスポンス構造への直接リンク
Agent.generate() は、実行中に収集した最終データを返します。steps は Step オブジェクトの配列です。結果内の Tool 配列（トップレベルの toolCalls と toolResults、およびネストされた step.toolCalls と step.toolResults）には、Mastra の Chunk 形式が使われます。
つまり、Tool データは payload でラップされます。
const response = await agent.generate('Check the weather in Lagos')
for (const toolCall of response.toolCalls) {
console.log(toolCall.type) // 'tool-call'
console.log(toolCall.runId)
console.log(toolCall.from)
console.log(toolCall.payload.toolName)
console.log(toolCall.payload.args)
}
for (const step of response.steps) {
for (const toolResult of step.toolResults) {
console.log(toolResult.type) // 'tool-result'
console.log(toolResult.payload.toolName)
console.log(toolResult.payload.result)
}
}
同じ形状の Chunk を Stream で扱う方法は、ChunkType リファレンスを参照してください。
戻り値戻り値への直接リンク
result:
Awaited<ReturnType<MastraModelOutput<Output>['getFullOutput']>>
テキスト、object（構造化出力の場合）、Tool 呼び出し、Tool の結果、使用量統計、Step 情報を含む、生成処理の完全な出力を返します。
text:
string
Agent が生成したテキストレスポンス。
object?:
Output | undefined
structuredOutput を指定した場合の、Schema に対して検証済みの構造化出力オブジェクト。
toolCalls:
ToolCallChunk[]
生成中に行われた Tool 呼び出し Chunk の配列。
ToolCallChunk
type:
'tool-call'
Chunk の種類を示す識別子。
runId:
string
実行 Run の識別子。
from:
ChunkFrom
AGENT や WORKFLOW など、Chunk の生成元。
payload:
ToolCallPayload
Tool 呼び出しデータ。
ToolCallPayload
toolCallId:
string
Tool 呼び出しの一意な識別子。
toolName:
string
呼び出された Tool の名前。
args?:
Record<string, unknown>
Tool へ渡された引数。
providerExecuted?:
boolean
Model Provider が Tool を直接実行したかどうか。
toolResults:
ToolResultChunk[]
Tool 実行による結果 Chunk の配列。
ToolResultChunk
type:
'tool-result'
Chunk の種類を示す識別子。
runId:
string
実行 Run の識別子。
from:
ChunkFrom
AGENT や WORKFLOW など、Chunk の生成元。
payload:
ToolResultPayload
Tool の結果データ。
ToolResultPayload
toolCallId:
string
Tool 呼び出しの一意な識別子。
toolName:
string
結果を生成した Tool の名前。
result:
unknown
Tool が返した値。
isError?:
boolean
Tool の実行が失敗したかどうか。
usage:
TokenUsage
生成時の Token 使用量統計。
steps:
object[]
実行 Step の配列。複数 Step 生成の Debug に役立ちます。
object
text:
string
この Step で生成されたテキスト。
toolCalls:
ToolCallChunk[]
この Step で出力された Tool 呼び出し。
toolResults:
ToolResultChunk[]
この Step で出力された Tool の結果。
finishReason?:
string
この Step が終了した理由。
usage:
LanguageModelUsage
この Step の Token 使用量。
request:
{ body?: unknown }
この Step のリクエストメタデータ。
response:
object
この Step のレスポンスメタデータ。
finishReason:
string
生成が終了した理由。値には 'stop'（正常終了）、'tool-calls'（Tool 呼び出しで終了）、'suspended'（Tool の承認待ち）、'error'（エラー発生）などがあります。
response:
object
Model Provider からのレスポンスメタデータ。Rate Limit Header やリクエスト ID へのアクセスに役立ちます。
object
id?:
string
Model Provider からのレスポンス ID。
timestamp?:
Date
レスポンスが生成された日時。
modelId?:
string
このレスポンスに使われたモデルの識別子。
headers?:
Record<string, string>
Model Provider からの HTTP レスポンス Header。Rate Limit 情報（例：
anthropic-ratelimit-requests-remaining、x-ratelimit-remaining-tokens）や、その他の Provider 固有メタデータを含みます。messages?:
ResponseMessage[]
モデル形式のレスポンスメッセージ。
uiMessages?:
UIMessage[]
UI 形式のレスポンスメッセージ。Output Processor が追加したメタデータを含みます。
request?:
object
モデルへ送信されたリクエスト。
object
body?:
unknown
Model Provider へ送信されたリクエスト Body。
warnings?:
LanguageModelWarning[]
生成中に Model Provider から返された警告。
providerMetadata?:
Record<string, unknown>
レスポンスとともに返される Provider 固有メタデータ。
reasoning?:
ReasoningChunk[]
推論に対応するモデル（例：OpenAI o1 シリーズ）からの推論詳細。
reasoningText?:
string
推論モデルからの推論テキストを結合したもの。
sources?:
SourceChunk[]
生成中にモデルが参照した Source。
files?:
FileChunk[]
モデルが生成したファイル。
suspendPayload?:
object
finishReason が 'suspended' の場合に存在します。保留中の Tool 呼び出しを承認または拒否するために必要な詳細を含みます。object
toolCallId:
string
保留中の Tool 呼び出しの一意な識別子。
toolName:
string
承認が必要な Tool の名前。
args:
Record<string, any>
Tool へ渡される引数。
runId?:
string
この実行 Run の一意な識別子。Suspend された実行を再開するために
approveToolCallGenerate() または declineToolCallGenerate() を呼び出す場合に必要です。traceId?:
string
Tracing が有効な場合に、この実行へ関連付けられる Trace ID。Log の関連付けや実行フローの Debug に使います。
spanId?:
string
Tracing が有効な場合に、この実行へ関連付けられるルート Span ID。Span 単位の検索と関連付けに使います。
messages:
MastraDBMessage[]
入力、Memory 履歴、レスポンスを含む、この実行のすべてのメッセージ。
rememberedMessages:
MastraDBMessage[]
Memory から読み込まれたメッセージ（会話履歴）のみ。
error?:
Error
生成に失敗した場合の Error オブジェクト。
tripwire?:
StepTripwireData
Processor によりコンテンツがブロックされた場合の Tripwire データ。
scoringData?:
object
returnScorerData が有効な場合の Evals 用 Scoring データ。その他の例その他の例への直接リンク
モデル設定を使うモデル設定を使うへの直接リンク
出力 Token 数を制限し、Temperature を設定する例です。
const limitedResult = await agent.generate('Write a short poem about coding', {
modelSettings: {
maxOutputTokens: 50,
temperature: 0.7,
},
})
Memory を使うMemory を使うへの直接リンク
Memory オプションを設定し、Agent が会話履歴へアクセスして会話を永続化できるようにします。これにより、Agent は過去のやり取りを記憶し、メッセージ間で Context を維持できます。
const memoryResult = await agent.generate('Remember my favorite color is blue', {
memory: {
thread: 'user-123-thread',
resource: 'user-123',
},
})
レスポンス Header へアクセスするレスポンス Header へアクセスするへの直接リンク
一部の Model Provider は、残りの Token 数や Rate Limit の状態など、有用な情報をレスポンス Header で返します。生成完了後、結果オブジェクトからこれらの Header へアクセスできます。
const result = await agent.generate('Hello!')
const remainingRequests = result.response?.headers?.['anthropic-ratelimit-requests-remaining']
const remainingTokens = result.response?.headers?.['x-ratelimit-remaining-tokens']
console.log(`Remaining requests: ${remainingRequests}, Remaining tokens: ${remainingTokens}`)
画像を解析する画像を解析するへの直接リンク
Agent は、画像の視覚情報と画像内のテキストを処理し、画像を解析して説明できます。画像解析を有効にするには、content 配列へ type: 'image' と画像 URL を持つオブジェクトを渡します。画像コンテンツとテキスト Prompt を組み合わせて、Agent の解析を導くこともできます。
const response = await agent.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)
maxSteps を使うusing-maxstepsへの直接リンク
maxSteps パラメータは、Agent が連続して行える LLM 呼び出しの最大回数を制御します。各 Step ではレスポンスを生成し、Tool 呼び出しを実行してから結果を処理します。Step 数を制限すると、無限ループを防ぎ、Latency を抑えられます。また、Tool を使う Agent の Token 使用量も制御できます。デフォルトは 5 ですが、増やすこともできます。
const response = await agent.generate('Help me organize my day', {
maxSteps: 10,
})
console.log(response.text)
onStepFinish を使うusing-onstepfinishへの直接リンク
onStepFinish Callback を使うと、複数 Step 処理の進捗を監視できます。Debug や、ユーザーへの進捗通知に役立ちます。
onStepFinish は、Stream または構造化出力を使わないテキスト生成でのみ利用できます。
const response = await agent.generate('Help me organize my day', {
onStepFinish: ({ text, toolCalls, toolResults, finishReason, usage }) => {
console.log({ text, toolCalls, toolResults, finishReason, usage })
},
})
onTitleGenerated を使うusing-ontitlegeneratedへの直接リンク
Memory オプションで generateTitle を有効にすると、レスポンス完了後に Title 生成が非同期で実行されます。Title の準備ができたときに処理するには onTitleGenerated を使います。たとえば、SSE 経由でクライアントへ送信できます。
const response = await agent.generate('What is quantum computing?', {
memory: {
thread: threadId,
resource: userId,
onTitleGenerated: title => {
console.log('Thread title:', title)
},
},
})