> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# Agent クラス

`Agent` クラスは、Mastra で AI Agent を作成するための基盤です。レスポンス生成と対話のストリーミングに使うメソッドを提供し、音声機能も扱います。

## 使用例

### 基本的な文字列 instructions

instructions を文字列または文字列配列で渡す方法が、Agent を設定する最も簡単な方法です。追加設定なしで Prompt を渡す単純なユースケースに適しています。

```typescript
import { Agent } from '@mastra/core/agent'

// String instructions
export const agent = new Agent({
  id: 'test-agent',
  name: 'Test Agent',
  instructions: 'You are a helpful assistant that provides concise answers.',
  model: 'openai/gpt-5.6-sol',
})

// System message object
export const agent2 = new Agent({
  id: 'test-agent-2',
  name: 'Test Agent 2',
  instructions: {
    role: 'system',
    content: 'You are an expert programmer',
  },
  model: 'openai/gpt-5.6-sol',
})

// Array of system messages
export const agent3 = new Agent({
  id: 'test-agent-3',
  name: 'Test Agent 3',
  instructions: [
    { role: 'system', content: 'You are a helpful assistant' },
    { role: 'system', content: 'You have expertise in TypeScript' },
  ],
  model: 'openai/gpt-5.6-sol',
})
```

### Provider 固有の設定

各 Model Provider では、Prompt Cache や推論設定などのオプションも利用できます。instructions 単位で `providerOptions` を設定し、System instructions／Prompt ごとに異なる Cache 方式を指定できます。

```typescript
import { Agent } from '@mastra/core/agent'

export const agent = new Agent({
  id: 'core-message-agent',
  name: 'Core Message Agent',
  instructions: {
    role: 'system',
    content: 'You are a helpful assistant specialized in technical documentation.',
    providerOptions: {
      openai: {
        reasoningEffort: 'low',
      },
    },
  },
  model: 'openai/gpt-5.6-sol',
})
```

### instructions 形式の混在

```typescript
import { Agent } from '@mastra/core/agent'

// This could be customizable based on the user
const preferredTone = {
  role: 'system',
  content: 'Always maintain a professional and empathetic tone.',
}

export const agent = new Agent({
  id: 'multi-message-agent',
  name: 'Multi Message Agent',
  instructions: [
    { role: 'system', content: 'You are a customer service representative.' },
    preferredTone,
    {
      role: 'system',
      content: 'Escalate complex issues to human agents when needed.',
      providerOptions: {
        anthropic: { cacheControl: { type: 'ephemeral' } },
      },
    },
  ],
  model: 'anthropic/claude-sonnet-4-6',
})
```

## モデル文字列

最も簡単に設定するには、`model` を `provider/model` 形式の文字列で渡します。Provider 名とモデル名はスラッシュで区切ります。Mastra が環境から対応する Provider Credential を読み取るため、この形式では Provider Package や import は不要です。

よく使われる Provider 文字列と Credential：

- **OpenAI**：`openai/gpt-5.6-sol` は `OPENAI_API_KEY` を使用します。
- **Anthropic**：`anthropic/claude-sonnet-4-6` は `ANTHROPIC_API_KEY` を使用します。
- **Google**：`google/gemini-2.5-pro` は `GOOGLE_API_KEY` または `GOOGLE_GENERATIVE_AI_API_KEY` を使用します。

対応するモデル ID は[モデル](https://mastra.zisheng.pro/ja/models)、Provider の全一覧は[環境変数](https://mastra.zisheng.pro/ja/models/environment-variables)を参照してください。

## Thread Signal

Agent Signal を使うと、Memory Thread へリアルタイムの入力とコンテキストを送信できます。Message API はユーザー入力用です。`sendSignal()` はシステム生成コンテキスト向けの低レベル API です。

対象 Thread が実行中の場合、`sendMessage()` はアクティブな Agent Loop へメッセージを配信します。Thread がアイドル状態の場合、Mastra はデフォルトでそのメッセージを最初の入力として Stream を開始します。

```typescript
const subscription = await agent.subscribeToThread({
  resourceId: 'user-123',
  threadId: 'thread-abc',
})

void (async () => {
  for await (const chunk of subscription.stream) {
    console.log(chunk)
  }
})()

agent.sendMessage('Use the latest customer note too.', {
  resourceId: 'user-123',
  threadId: 'thread-abc',
  ifIdle: {
    streamOptions: {
      maxSteps: 3,
    },
  },
})
```

共有 Thread 内のユーザーを識別するには `attributes` を使います。属性は XML として表示されるため、モデルは誰が何を発言したかを区別できます。

```typescript
agent.sendMessage(
  {
    contents: 'Can we simplify the API surface?',
    attributes: { name: 'Devin', from: 'slack' },
  },
  { resourceId: 'user-123', threadId: 'thread-abc' },
)
```

モデルは次の形式で受け取ります。

```xml
<user name="Devin" from="slack">Can we simplify the API surface?</user>
```

Thread が実行中かどうかに応じてメッセージへ異なるコンテキストを付けるには、`ifActive.attributes` と `ifIdle.attributes` を使います。

```typescript
agent.sendMessage(
  {
    contents: 'Also cover the edge cases.',
    attributes: { source: 'chat' },
  },
  {
    resourceId: 'user-123',
    threadId: 'thread-abc',
    ifActive: { attributes: { delivery: 'while-active' } },
    ifIdle: { attributes: { delivery: 'new-message' } },
  },
)
```

Thread がアクティブな場合、モデルは次を受け取ります。

```xml
<user source="chat" delivery="while-active">Also cover the edge cases.</user>
```

Thread がアイドル状態の場合、モデルは次を受け取ります。

```xml
<user source="chat" delivery="new-message">Also cover the edge cases.</user>
```

UI はメッセージ内容を受け取り、Signal Message の `attributes` と `metadata` も読み取ってカスタム表示できます（例：ユーザー名、Avatar、プラットフォーム Badge の表示）。

### `sendMessage(message, options)`

アクティブな Run または Memory Thread へユーザーメッセージを送信します。アクティブな Agent がメッセージをすぐに受け取る必要がある場合に使います。

**message** (`string | Array<TextPart | FilePart> | { contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): ユーザーが作成した入力。属性のない文字列や Part は通常のユーザー入力としてモデルへ送られます。attributes がある場合、Mastra は属性を含む \<user> XML 要素としてメッセージを表示します。

**options** (`object`): メッセージの送信先と配信動作。

**options.runId** (`string`): 直接対象とする Run ID。アクティブな Run ID が既知の場合に使います。

**options.resourceId** (`string`): Memory Thread の Resource ID。Thread を対象とするメッセージでは threadId とともに必須です。

**options.threadId** (`string`): 対象とする Thread ID。Thread を対象とするメッセージでは resourceId とともに必須です。

**options.ifActive** (`object`): 対象 Thread がアクティブな場合の動作を制御します。

**options.ifActive.behavior** (`'deliver' | 'persist' | 'discard'`): 対象 Thread がアクティブな場合の動作を制御します。デフォルトは deliver です。

**options.ifActive.attributes** (`Record<string, string | number | boolean>`): 対象 Thread がアクティブなときに Mastra がメッセージを受け付けると、メッセージへマージされる属性。

**options.ifIdle** (`object`): 対象 Thread がアイドル状態の場合の動作を制御します。

**options.ifIdle.behavior** (`'wake' | 'persist' | 'discard'`): 対象 Thread がアイドル状態の場合の動作を制御します。デフォルトは wake です。

**options.ifIdle.streamOptions** (`AgentExecutionOptions`): ifIdle.behavior が wake の場合に開始する Stream のオプション。Mastra はトップレベルの resourceId と threadId を Memory コンテキストに使います。

**options.ifIdle.attributes** (`Record<string, string | number | boolean>`): 対象 Thread がアイドル状態のときに Mastra がメッセージを受け付けると、メッセージへマージされる属性。

アイドル状態の Thread でカスタム実行オプションを使って新しい Stream を開始するには、`ifIdle.behavior` を `wake` に設定し、`ifIdle.streamOptions` を渡します。

```typescript
agent.sendMessage('Continue with the next step.', {
  resourceId: 'user-123',
  threadId: 'thread-abc',
  ifIdle: {
    behavior: 'wake',
    streamOptions: {
      maxSteps: 3,
    },
  },
})
```

`{ accepted: Promise<SendAgentSignalAccepted>, signal: CreatedAgentSignal, persisted?: Promise<void> }` を返します。`accepted` は、Mastra がメッセージの処理方法を決定した時点で解決されます。このプロセスが Agent を実行する場合（Run を開始したか、開始する Lease を取得した場合）は `{ action: 'wake', runId, output }`、メッセージが既存 Run へ転送された場合（このプロセスがプロセス間の Wake 競合に負けた場合を含む）は `{ action: 'deliver', runId }`、何も実行されなかった場合は `{ action: 'persist' }`／`{ action: 'discard' }` です。`runId` はメッセージを処理した Run の正式な ID で、`wake` と `deliver` にのみ存在します。`persist`／`discard` では、保存済みメッセージとの対応付けに `result.signal.id` を使います。`accepted` は Route 決定時に解決され（`wake` Run の生成エラーは `output.consumeStream()` から表面化）、メッセージをまったく Routing または開始できなかった場合（例：Agent の設定不備）だけ Reject されます。`persisted` は `persist` 動作の場合にのみ存在し、Mastra が Memory へのメッセージ書き込みを終えると解決されます。`wake` Action の `output` は、プロセス内で消費できる Agent Stream です。

### `queueMessage(message, options)`

Thread の次の Turn に向けてユーザーメッセージを Queue へ追加します。Thread がアクティブな場合、Mastra はアクティブ Run の完了を待ち、Queue 内のメッセージで新しい Run を開始します。Thread がアイドル状態の場合は、すぐに Run を開始します。

```typescript
agent.queueMessage('Also check whether the tests need updates.', {
  resourceId: 'user-123',
  threadId: 'thread-abc',
})
```

`queueMessage()` は `sendMessage()` と同じ形式の `message` と `options` を受け取り、`{ accepted: Promise<SendAgentSignalAccepted>, signal: CreatedAgentSignal, persisted?: Promise<void> }` を返します。`accepted` の意味も `sendMessage()` と同じです。

### `sendSignal(signal, options)`

アクティブな Run または Memory Thread へ Signal を送信します。

**signal** (`{ type: 'user' | 'state' | 'reactive' | 'notification' | 'user-message' | 'system-reminder'; tagName?: string; contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): Thread へ送る Signal Context。type は Signal の意味上のカテゴリです。tagName はモデルに見せる XML Tag を制御します。たとえば、{ type: 'notification', tagName: 'github-review' } は \<github-review>...\</github-review> として表示されます。従来の user-message と system-reminder Payload も引き続き受け付け、正規化されます。未知の type 値は拒否されるため、カスタム XML Tag には tagName を使います。

**options** (`object`): Signal の送信先と配信動作。

**options.runId** (`string`): 直接対象とする Run ID。アクティブな Run ID が既知の場合に使います。

**options.resourceId** (`string`): Memory Thread の Resource ID。Thread を対象とする Signal では threadId とともに必須です。

**options.threadId** (`string`): 対象とする Thread ID。Thread を対象とする Signal では resourceId とともに必須です。

**options.ifActive** (`object`): 対象 Thread がアクティブな場合の動作を制御します。

**options.ifActive.behavior** (`'deliver' | 'persist' | 'discard'`): 対象 Thread がアクティブな場合の動作を制御します。デフォルトは deliver です。

**options.ifActive.attributes** (`Record<string, string | number | boolean>`): 対象 Thread がアクティブなときに Mastra が Signal を受け付けると、Signal へマージされる属性。

**options.ifIdle** (`object`): 対象 Thread がアイドル状態の場合の動作を制御します。

**options.ifIdle.behavior** (`'wake' | 'persist' | 'discard'`): 対象 Thread がアイドル状態の場合の動作を制御します。デフォルトは wake です。

**options.ifIdle.streamOptions** (`AgentExecutionOptions`): ifIdle.behavior が wake の場合に開始する Stream のオプション。Mastra はトップレベルの resourceId と threadId を Memory コンテキストに使います。

**options.ifIdle.attributes** (`Record<string, string | number | boolean>`): 対象 Thread がアイドル状態のときに Mastra が Signal を受け付けると、Signal へマージされる属性。

`{ accepted: Promise<SendAgentSignalAccepted>, signal: CreatedAgentSignal, persisted?: Promise<void> }` を返します。`accepted` は、Mastra が Signal の処理方法を決定した時点で解決されます。このプロセスが Agent を実行する場合（Run を開始したか、開始する Lease を取得した場合）は `{ action: 'wake', runId, output }`、Signal が既存 Run へ転送された場合（このプロセスがプロセス間の Wake 競合に負けた場合を含む）は `{ action: 'deliver', runId }`、何も実行されなかった場合は `{ action: 'persist' }`／`{ action: 'discard' }` です。`action` は `ifActive`／`ifIdle` で採用された `behavior` と一致します。`runId` は Signal を処理した Run の正式な ID で、`wake` と `deliver` にのみ存在します。`persist`／`discard` では、保存済み Signal との対応付けに `result.signal.id` を使います。`accepted` は Route 決定時に解決され（`wake` Run の生成エラーは `output.consumeStream()` から表面化）、Signal をまったく Routing または開始できなかった場合（例：Agent の設定不備）だけ Reject されます。`persisted` は `persist` 動作の場合にのみ存在し、Mastra が Memory への Signal 書き込みを終えると解決されます。`wake` Action の `output` は、プロセス内で消費できる Agent Stream です。

サーバーレス Handler では `accepted` を await し、`wake` の出力をプラットフォームの `waitUntil` 相当へ渡します。これにより、HTTP レスポンスを返した後も、採用されたプロセスが Stream を最後まで消費できます。

```typescript
const result = agent.sendSignal(signal, { resourceId, threadId })
ctx.waitUntil(
  result.accepted.then(async accepted => {
    if (accepted.action === 'wake') {
      await accepted.output.consumeStream()
    }
  }),
)
```

### `sendStateSignal(state, options)`

名前付きで Thread Scope の State Context を、アクティブな Run または Memory Thread へ送信します。ブラウザ状態、Editor 状態、Watcher 出力など、時間とともに変化する永続 Context を外部 Producer が所有する場合に使います。

```typescript
const result = await agent.sendStateSignal(
  {
    id: 'browser',
    mode: 'snapshot',
    cacheKey: 'browser:https://example.com:3-tabs',
    contents: 'Browser is open. Active tab URL: https://example.com. 3 open tabs.',
    value: {
      activeUrl: 'https://example.com',
      tabCount: 3,
      open: true,
    },
  },
  {
    resourceId: 'user-123',
    threadId: 'thread-abc',
  },
)
```

**state** (`object`): Thread へ送る State Signal。

**state.id** (`string`): browser や editor などの State Lane 名。

**state.cacheKey** (`string`): 同じ Lane と Mode の重複 State をスキップするために Mastra が使う、Producer 所有のキー。

**state.contents** (`string | Array<TextPart | FilePart>`): LLM 向けの State 表現。

**state.mode** (`'snapshot' | 'delta'`): State が正式な Snapshot か変更イベントかを指定します。デフォルトは snapshot です。

**state.value** (`unknown`): mode: 'snapshot' で使う構造化 Snapshot 値。

**state.delta** (`unknown`): mode: 'delta' で使う構造化変更値。

**state.attributes** (`Record<string, string | number | boolean>`): State Signal Tag に表示する属性。

**state.metadata** (`Record<string, unknown>`): State Signal とともに保存するアプリケーションメタデータ。

**state.tagName** (`string`): モデルに見せる XML Tag 名。デフォルトは state です。

**options** (`object`): State Signal の送信先と配信動作。sendSignal() と同じオプションを受け取ります。

Mastra が新しい State を受け付けると `{ accepted: Promise<SendAgentSignalAccepted>, signal: CreatedAgentSignal, persisted?: Promise<void>, skipped?: false }` を返します。同じ `cacheKey` と Mode が State Lane の現在値である場合は `{ skipped: true, reason: 'unchanged' }` を返します。`accepted` は、Mastra が Signal の処理方法を決定した時点で解決されます。このプロセスが Agent を実行する場合（Run を開始したか、開始する Lease を取得した場合）は `{ action: 'wake', runId, output }`、Signal が既存 Run へ転送された場合（このプロセスがプロセス間の Wake 競合に負けた場合を含む）は `{ action: 'deliver', runId }`、何も実行されなかった場合は `{ action: 'persist' }`／`{ action: 'discard' }` です。`runId` は Signal を処理した Run の正式な ID で、`wake` と `deliver` にのみ存在します。`persist`／`discard` では、保存済み Signal との対応付けに `result.signal.id` を使います。`wake` Action の `output` は、プロセス内で消費できる Agent Stream です。

### `sendNotificationSignal(notification, options)`

Notification Inbox Record を作成または統合し、通知配信 Policy を解決します。即時配信が決定された場合は Notification Signal を送信します。

```typescript
const result = await agent.sendNotificationSignal(
  {
    source: 'github',
    kind: 'ci-status',
    priority: 'high',
    summary: 'CI failed on main: 3 tests failed.',
    dedupeKey: 'github:acme/app:main:ci',
  },
  {
    resourceId: 'user-123',
    threadId: 'thread-abc',
  },
)
```

**notification** (`object`): 作成または統合する Notification Inbox Record。

**notification.source** (`string`): github、slack、email など、通知を生成した外部システム。

**notification.kind** (`string`): ci-status、mention、direct-message など、Source 内の通知種別。

**notification.summary** (`string`): Notification Signal の内容として使う LLM 向け要約。

**notification.priority** (`'low' | 'medium' | 'high' | 'urgent'`): 通知配信 Policy が使う優先度。デフォルトは medium です。

**notification.payload** (`unknown`): Tool またはアプリケーションコード向けに Inbox Record へ保存する構造化 Payload。

**notification.dedupeKey** (`string`): 同じ Source と Thread にある重複した保留中通知を統合するためのキー。

**notification.coalesceKey** (`string`): 同じ Source と Thread にある関連した保留中通知をまとめるためのキー。

**notification.attributes** (`Record<string, JSONValue>`): 送出する Notification Signal へコピーする追加属性。

**notification.metadata** (`Record<string, unknown>`): Inbox Record へ保存するアプリケーションメタデータ。

**options** (`object`): 通知の対象 Thread と Wake-up 動作。

**options.resourceId** (`string`): Notification Inbox と対象 Memory Thread の Resource ID。

**options.threadId** (`string`): Notification Inbox と対象 Memory Thread の Thread ID。

**options.ifIdle** (`object`): 対象 Thread がアイドル状態の場合の動作を制御します。

**options.ifIdle.streamOptions** (`AgentExecutionOptions`): 即時通知によってアイドル状態の Thread が Wake したときに開始する Stream のオプション。

`{ record: NotificationRecord, decision: NotificationDeliveryDecision, runId?: string, signal?: CreatedAgentSignal, persisted?: Promise<void>, accepted?: Promise<SendAgentSignalAccepted> }` を返します。`record` は保存済み Inbox Record、`decision` は配信 Policy の結果です。Ingress が Signal を即時送出した場合は、アクティブな高優先度通知で即時送出される要約も含め、`signal` と `runId` が存在します。アイドル状態の Thread を Wake させずに送出 Signal を永続化した場合は `persisted` が存在します。Signal を送出した場合は `accepted` が存在し、Mastra が処理方法を決定した時点で解決されます。このプロセスが Agent を実行する場合（Run を開始したか、開始する Lease を取得した場合）は `{ action: 'wake', runId, output }`、Signal が既存 Run へ転送された場合は `{ action: 'deliver', runId }`、何も実行されなかった場合は `{ action: 'persist' }`／`{ action: 'discard' }` です。解決結果の `runId` は `wake` と `deliver` にのみ存在します。`wake` Action の `output` は、プロセス内で消費できる Agent Stream です。

デフォルト配信は優先度を考慮します。`urgent` 通知は即時配信されます。`high` 通知は Thread がアイドル状態なら即時配信されます。Thread がアクティブな場合、Mastra は要約をすぐに送出し、Thread がアイドル状態になった後の完全配信用に `deliverAt` を維持します。`medium` 通知はアイドル時に即時配信され、アクティブ時には要約へまとめられます。`low` 通知はアクティブ時もアイドル時も要約へまとめられます。アイドル時の低優先度要約は、Model Loop を Wake させずに購読者へ届きます。処理全体は [Signal](https://mastra.zisheng.pro/ja/docs/long-running-agents/signals)を参照してください。

一部の通知を別の Dispatch Window や要約 Rollup まで待機させるには、Agent に `notifications.deliveryPolicy` を設定します。

```typescript
export const supportAgent = new Agent({
  id: 'support-agent',
  name: 'Support Agent',
  instructions: 'Help the user triage updates.',
  model: 'openai/gpt-5.6-sol',
  notifications: {
    deliveryPolicy: {
      priorities: {
        urgent: 'deliver',
      },
      decide: ({ record }) => {
        if (record.priority === 'low') {
          return {
            action: 'summarize',
            summaryAt: new Date(Date.now() + 30 * 60 * 1000),
          }
        }
      },
    },
  },
})
```

### `subscribeToThread(options)`

Memory Thread の生 Stream チャンクを購読します。`sendMessage()`、`queueMessage()`、`sendSignal()` を呼び出す前に使います。Signal がアクティブ Run を中止した場合も含め、Stream 出力の表示と Signal Echo の監視が可能です。

**options** (`object`): Thread の購読対象。

**options.resourceId** (`string`): Memory Thread の Resource ID。

**options.threadId** (`string`): 購読する Thread ID。

次のメンバーを持つ `AgentThreadSubscription` オブジェクトを返します。

**stream** (`AsyncIterable<AgentChunkType>`): 購読した Thread の生 Agent Stream チャンク。

**activeRunId** (`() => string | null`): Thread のアクティブ Run ID を返します。アクティブな Run がない場合は null です。

**abort** (`() => boolean`): Thread のアクティブ Run を中止します。Run を中止した場合は true を返します。

**unsubscribe** (`() => void`): アクティブ Run を中止せずに購読を停止します。

## コンストラクターのパラメータ

**id** (`string`): Agent の一意な識別子。

**name** (`string`): Agent の表示名。

**description** (`string`): Agent の目的と機能に関する任意の説明。

**metadata** (`Record<string, unknown> | ({ requestContext: RequestContext }) => Record<string, unknown> | Promise<Record<string, unknown>>`): クライアントで Agent を分類または Filter するための任意のメタデータ。静的 Record、またはリクエストコンテキストからメタデータを解決する関数を指定できます。

**instructions** (`SystemMessage | ({ requestContext: RequestContext }) => SystemMessage | Promise<SystemMessage>`): Agent の動作を導く instructions。文字列、文字列配列、System Message オブジェクト、 System Message 配列、またはこれらの型を動的に返す関数を指定できます。 SystemMessage の型：string | string\[] | CoreSystemMessage | CoreSystemMessage\[] | SystemModelMessage | SystemModelMessage\[]

**model** (`MastraLanguageModel | ({ requestContext: RequestContext }) => MastraLanguageModel | Promise<MastraLanguageModel>`): Agent が使う言語モデル。provider/model 形式の Model Router 文字列、モデル設定または Provider インスタンス、あるいは Runtime でモデルを解決する関数を渡します。一般的な Provider と環境変数はモデル文字列を参照してください。

**agents** (`Record<string, Agent> | ({ requestContext: RequestContext }) => Record<string, Agent> | Promise<Record<string, Agent>>`): Agent がアクセスできる Sub-agent。静的に指定することも、動的に解決することもできます。

**tools** (`ToolsInput | ({ requestContext: RequestContext, mastra?: Mastra }) => ToolsInput | Promise<ToolsInput>`): Agent がアクセスできる Tool。静的に指定するか、リクエストコンテキストと、利用可能な場合は関連する Mastra インスタンスから動的に解決できます。

**hooks** (`ToolHooks`): この Agent による各 Tool 呼び出しの前後で実行される Hook。generate() または stream() へ渡す実行単位の Hook は、ここで設定した対応する Hook を上書きします。以下の「Tool Hook」を参照してください。

**hooks.beforeToolCall** (`(context: ToolHookContext) => void | ToolBeforeHookResult | Promise<void | ToolBeforeHookResult>`): Tool の実行前に実行されます。{ toolName, input, context, metadata } を受け取ります。Tool 呼び出しをスキップし、output を結果として使うには { proceed: false, output } を返します。

**hooks.afterToolCall** (`(context: ToolAfterHookContext) => void | Promise<void>`): Tool の実行後に実行されます。{ toolName, input, context, metadata, output, error } を受け取ります。Tool がエラーをスローすると output は undefined になり、代わりに error が設定されます。

**transform** (`ToolPayloadTransformPolicy`): 表示用 Stream やユーザー向け Transcript Message が受け取る前に Tool Payload を変換する共通 Policy。Tool 固有の規則には createTool() の Tool 単位の transform を使います。

**workflows** (`Record<string, Workflow> | ({ requestContext: RequestContext }) => Record<string, Workflow> | Promise<Record<string, Workflow>>`): Agent が実行できる Workflow。静的または動的に解決できます。

**defaultOptions** (`AgentExecutionOptions | ({ requestContext: RequestContext }) => AgentExecutionOptions | Promise<AgentExecutionOptions>`): stream() と generate() の呼び出しで使うデフォルトオプション。

**defaultGenerateOptionsLegacy** (`AgentGenerateOptions | ({ requestContext: RequestContext }) => AgentGenerateOptions | Promise<AgentGenerateOptions>`): generateLegacy() の呼び出しで使うデフォルトオプション。

**defaultStreamOptionsLegacy** (`AgentStreamOptions | ({ requestContext: RequestContext }) => AgentStreamOptions | Promise<AgentStreamOptions>`): streamLegacy() の呼び出しで使うデフォルトオプション。

**mastra** (`Mastra`): Mastra Runtime インスタンスへの参照（自動注入）。

**scorers** (`MastraScorers | ({ requestContext: RequestContext }) => MastraScorers | Promise<MastraScorers>`): Runtime 評価と Telemetry の Scoring 設定。静的または動的に指定できます。

**memory** (`MastraMemory | ({ requestContext: RequestContext }) => MastraMemory | Promise<MastraMemory>`): Stateful Context の保存と取得に使う Memory Module。

**notifications** (`object`): Durable Notification Signal の通知配信設定。

**notifications.deliveryPolicy** (`NotificationDeliveryPolicyConfig`): Notification Record の配信方法を制御します。デフォルトの決定、優先度ごとの決定、Source ごとの決定、またはカスタム decide() 関数を設定できます。

**voice** (`CompositeVoice`): 音声入出力の Voice 設定。

**inputProcessors** (`(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>`): Agent が処理する前にメッセージを変更または検証できる Input Processor。個別の Processor オブジェクト、または ProcessorStepSchema を使って createWorkflow() で作成した Workflow を指定できます。

**outputProcessors** (`(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>`): クライアントへ送信する前に Agent からのメッセージを変更または検証できる Output Processor。個別の Processor オブジェクトまたは Workflow を指定できます。

**maxProcessorRetries** (`number`): Processor が LLM Step の再試行を要求できる最大回数。

**requestContextSchema** (`StandardJSONSchemaV1`): リクエストコンテキスト値を検証する Standard JSON Schema。指定すると generate() または stream() の開始時にコンテキストが検証され、失敗した場合は MastraError がスローされます。

**editor** (`false | { instructions?: boolean; tools?: boolean | { description?: boolean } }`): コードで定義したこの Agent について、Editor が上書きできるフィールドを制御します。instructions と Tool の編集を許可するには省略します。以下の「Editor による上書き」を参照してください。

## `generate()` の Memory オプション

`agent.generate()` の呼び出し時に `memory` を渡し、Run が読み書きする会話 Thread を選びます。一般的な形式は `memory: { resource: string, thread: string }` で、`resource` は所有者、`thread` は会話を識別します。概念モデルは [Thread と Resource](https://mastra.zisheng.pro/ja/docs/memory/message-history)を参照してください。

```typescript
const response = await agent.generate('What did we decide about retries?', {
  memory: {
    resource: 'user-123',
    thread: 'support-thread-456',
  },
})
```

呼び出し中に Thread メタデータを作成または更新する場合は、Thread オブジェクトを使います。

```typescript
const response = await agent.generate('Continue the support conversation.', {
  memory: {
    resource: 'user-123',
    thread: {
      id: 'support-thread-456',
      title: 'Billing support',
      metadata: { category: 'billing' },
    },
  },
})
```

## Tool Hook

`hooks` を使うと、割り当て済み Tool、Memory Tool、Toolset、クライアント Tool、Workspace Tool を含め、Agent によるすべての Tool 呼び出しの前後でロジックを実行できます。

```typescript
import { Agent } from '@mastra/core/agent'

export const agent = new Agent({
  id: 'support-agent',
  name: 'support-agent',
  instructions: 'Help users with their questions.',
  model: 'openai/gpt-5.6-sol',
  hooks: {
    beforeToolCall: ({ toolName, input }) => {
      console.log(`Running ${toolName}`, input)
    },
    afterToolCall: ({ toolName, output, error }) => {
      console.log(`Finished ${toolName}`, { output, error })
    },
  },
})
```

`beforeToolCall` は `{ proceed: false, output }` を返して Tool 呼び出しを短絡できます。Agent は実行をスキップし、`output` を Tool の結果として使います。

```typescript
const result = await agent.generate('Clean up old records', {
  hooks: {
    beforeToolCall: ({ toolName }) => {
      if (toolName === 'deleteRecord') {
        return { proceed: false, output: { blocked: true } }
      }
    },
  },
})
```

Hook Context の `metadata` には `agentId` と `agentName` が含まれます。`generate()` または `stream()` へ渡す実行単位の Hook は、対応する Agent レベルの Hook を上書きします。[Workspace](https://mastra.zisheng.pro/ja/reference/workspace/workspace-class) でも `tools.hooks` が定義されている場合、Workspace Hook は Agent Hook Wrapper の内側で実行されます。

## Editor による上書き

[`MastraEditor`](https://mastra.zisheng.pro/ja/reference/editor/mastra-editor) を登録すると、`editor` フィールドによって、コードで定義した Agent のどの部分を Editor から変更できるかを制御できます。コードが所有するフィールドは Studio で読み取り専用になり、保存する上書き値から除外されます。

**editor** (`false | { instructions?: boolean; tools?: boolean | { description?: boolean } }`): instructions と Tool の編集を許可するには省略します。Agent をロックするには false を設定します。instructions の編集を許可するには instructions: true を設定します。Tool の所属と説明の編集を許可するには tools: true、説明の編集だけを許可するには tools: { description: true } を設定します。

Agent の `id`、`name`、`model` は常にコードから取得され、Editor では上書きできません。使い方は [Editor](https://mastra.zisheng.pro/ja/docs/editor/overview)を参照してください。

## 戻り値

**agent** (`Agent<TAgentId, TTools>`): 指定した設定を持つ新しい Agent インスタンス。