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

# SignalProvider

**追加バージョン:** `@mastra/core@1.39.0`

Signal Provider を構築するための抽象基底クラスです。Signal Provider は外部 Source（API、Webhook、Event Stream）を監視し、組み込みの Subscription Registry を通じて Agent Thread に Notification Signal を送出します。

Signal Provider はデフォルトでは Processor ではありません。Agent の実行をインターセプトする必要がある Provider は、`getInputProcessors()` または `getOutputProcessors()` から Processor を返します。Agent から呼び出せる Tool を公開する Provider は、`getTools()` から Tool を返します。

すぐに使用できる Webhook ベースの Provider については、[`WebhookSignalProvider`](https://mastra.zisheng.pro/ja/reference/signals/webhook-signal-provider) を参照してください。

## 使用例

30 秒ごとに API を確認する Polling Provider の例です。

```typescript
import { SignalProvider } from '@mastra/core/signals'
import type { SignalSubscription } from '@mastra/core/signals'

class SlackSignals extends SignalProvider<'slack-signals'> {
  readonly id = 'slack-signals'
  readonly pollInterval = 30_000

  async poll(subscriptions: SignalSubscription[]) {
    for (const sub of subscriptions) {
      const messages = await fetchSlackMessages(sub.externalResourceId)
      if (messages.length > 0) {
        await this.notify(
          {
            source: 'slack',
            kind: 'new-messages',
            summary: `${messages.length} new messages in ${sub.externalResourceId}`,
          },
          { threadId: sub.threadId, resourceId: sub.resourceId },
        )
      }
    }
  }
}
```

Agent に登録します。

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

const agent = new Agent({
  id: 'agent',
  signals: [new SlackSignals()],
})
```

Agent は `connect(this)` を呼び出し、Provider が返すすべての Processor または Tool を登録します。その後、Polling を開始します。

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

`SignalProvider` は抽象クラスです。サブクラスは引数なしで `super()` を呼び出します。

## プロパティ

**id** (`TId extends string`): この Provider の一意の識別子。サブクラスでは readonly プロパティとして実装する必要があります。

**name** (`string`): Provider の人が読める表示名。

**pollInterval** (`number`): Polling 間隔（ミリ秒）。設定すると、Framework はこの間隔で poll() を呼び出します。Webhook 専用 Provider では undefined または 0 のままにします。

**isConnected** (`boolean`): この Provider が Agent に接続されているかどうか。connect() の呼び出し後は true を返します。Agent.\_\_fork() 中の再接続をスキップするために内部で使用されます。

## メソッド

### 接続

#### `connect(agent)`

Agent のコンストラクターから呼び出されます。Provider が Agent に Signal を送り返せるよう、双方向リンクを確立します。リンクの確立後に追加のセットアップを実行するにはオーバーライドします。必ず `super.connect(agent)` を呼び出してください。

```typescript
class MySignals extends SignalProvider<'my-signals'> {
  readonly id = 'my-signals'

  override connect(agent) {
    super.connect(agent)
    // additional setup after agent link is established
  }
}
```

#### `__registerMastra(mastra)`

Provider の Agent が Mastra インスタンスに登録されると呼び出されます。ストレージやその他の Mastra Service にアクセスするにはオーバーライドします。必ず `super.__registerMastra(mastra)` を呼び出してください。

```typescript
override __registerMastra(mastra) {
  super.__registerMastra(mastra)
  // this.mastra is now available
}
```

### Processor と Tool の統合

#### `getInputProcessors()`

この Provider が Agent に登録する必要のある Input Processor を返します。Provider が Agent の入力 Step をインターセプトする場合（たとえば、Context Hint の注入や Tool 呼び出しの検出）にオーバーライドします。

```typescript
getInputProcessors() {
  return [this]
}
```

戻り値: `InputProcessorOrWorkflow[]`

#### `getOutputProcessors()`

この Provider が Agent に登録する必要のある Output Processor を返します。Provider が Agent の出力 Step をインターセプトする場合にオーバーライドします。

```typescript
getOutputProcessors() {
  return [this]
}
```

戻り値: `OutputProcessorOrWorkflow[]`

#### `getTools()`

この Provider が Agent に公開する Tool を返します。購読や購読解除コマンドなど、Agent から呼び出せる Tool を Provider が追加する場合にオーバーライドします。

```typescript
getTools() {
  return {
    subscribe_pr: createTool({ /* ... */ }),
    unsubscribe_pr: createTool({ /* ... */ }),
  }
}
```

戻り値: `Record<string, unknown>`

### Subscription の追跡

#### `subscribe(target, externalResourceId, metadata?)`

Thread で外部 Resource を購読します。これは protected メソッドです。Provider の実装内から呼び出してください。

```typescript
const sub = this.subscribe(
  { threadId: 'thread-1', resourceId: 'user-1' },
  'github:mastra-ai/mastra#123',
  { pr: 123 },
)
```

戻り値: `SignalSubscription`。作成された Subscription、または Metadata が統合された既存の Subscription です。

**target** (`SignalProviderTarget`): 購読する Thread。threadId と resourceId を含める必要があります。

**externalResourceId** (`string`): 外部 Resource の Provider 固有の識別子（たとえば、"github:owner/repo#123"）。

**metadata** (`Record<string, unknown>`): Subscription とともに保存する追加データ。重複した購読では、既存の Metadata に統合されます。

#### `unsubscribe(target, externalResourceId)`

Subscription を削除します。

```typescript
const removed = this.unsubscribe(
  { threadId: 'thread-1', resourceId: 'user-1' },
  'github:mastra-ai/mastra#123',
)
```

戻り値: `boolean`。削除した場合は `true`、一致する Subscription が存在しなかった場合は `false` です。

#### `getSubscriptions()`

この Provider のアクティブな Subscription をすべて返します。

```typescript
const allSubs = this.getSubscriptions()
```

戻り値: `SignalSubscription[]`

#### `getSubscriptionsForResource(externalResourceId)`

特定の外部 Resource に対するすべての Subscription を返します。

```typescript
const subs = this.getSubscriptionsForResource('github:mastra-ai/mastra#123')
for (const sub of subs) {
  await this.notify(
    { source: 'my-provider', kind: 'update', summary: 'Resource updated' },
    { threadId: sub.threadId, resourceId: sub.resourceId },
  )
}
```

戻り値: `SignalSubscription[]`

#### `getSubscriptionsForThread(target)`

特定の Thread に対するすべての Subscription を返します。

```typescript
const subs = this.getSubscriptionsForThread({
  threadId: 'thread-1',
  resourceId: 'user-1',
})
```

戻り値: `SignalSubscription[]`

#### `hasSubscription(target, externalResourceId)`

Subscription が存在するか確認します。

```typescript
if (this.hasSubscription(target, 'github:mastra-ai/mastra#123')) {
  // already subscribed
}
```

戻り値: `boolean`

#### `unsubscribeAll(target)`

Thread のすべての Subscription を削除します。

```typescript
const removed = this.unsubscribeAll({
  threadId: 'thread-1',
  resourceId: 'user-1',
})
```

戻り値: `number`。削除された Subscription の数です。

#### `subscriptionCount`

この Provider のアクティブな Subscription の総数です。

```typescript
if (this.subscriptionCount === 0) {
  // nothing to poll
}
```

戻り値: `number`

### Polling

#### `poll(subscriptions)`

Polling Cycle ごとに、すべてのアクティブな Subscription とともに呼び出されます。外部 Source を確認して通知を送出するにはオーバーライドします。Framework は Polling Cycle の重複を防ぎます。`poll()` の呼び出しに `pollInterval` より長い時間がかかった場合、次の Cycle はスキップされます。

```typescript
async poll(subscriptions: SignalSubscription[]) {
  for (const sub of subscriptions) {
    const events = await checkExternalSource(sub.externalResourceId)
    for (const event of events) {
      await this.notify(
        { source: 'my-provider', kind: event.type, summary: event.message },
        { threadId: sub.threadId, resourceId: sub.resourceId },
      )
    }
  }
}
```

#### `startPolling()`

Polling Timer を開始します。`connect()` の後に Agent から呼び出されます。冪等であるため、複数回呼び出しても影響はありません。

```typescript
provider.startPolling()
```

#### `stopPolling()`

Polling Timer を停止します。

```typescript
provider.stopPolling()
```

### Webhook

#### `handleWebhook(request)`

受信した Webhook リクエストを処理します。Payload を解析して Subscription と照合し、Notification Signal を送出するにはオーバーライドします。すぐに使用できる実装については、[`WebhookSignalProvider`](https://mastra.zisheng.pro/ja/reference/signals/webhook-signal-provider) を参照してください。

Webhook リクエストを検証した後、アプリケーションで定義した HTTP Endpoint からこのメソッドを呼び出してください。

```typescript
async handleWebhook(request) {
  const payload = request.body as { repo: string, event: string }
  const subs = this.getSubscriptionsForResource(payload.repo)

  for (const sub of subs) {
    await this.notify(
      { source: 'github', kind: payload.event, summary: `Event on ${payload.repo}` },
      { threadId: sub.threadId, resourceId: sub.resourceId },
    )
  }

  return { status: 200, body: { matched: subs.length } }
}
```

戻り値: `Promise<{ status?: number; body?: unknown }>`

### ライフサイクル

#### `start()`

`connect()` の後に呼び出され、非同期の初期化を実行します。セットアップに Agent または Mastra インスタンスが必要な場合にオーバーライドします。

```typescript
async start() {
  await this.loadInitialState()
}
```

#### `stop()`

シャットダウン時に呼び出されます。デフォルトの実装では Polling を停止し、すべての Subscription をクリアします。

```typescript
provider.stop()
```

### 通知

#### `notify(notification, target)`

接続先の Agent に Notification Signal を送信します。これは `agent.sendNotificationSignal()` をラップする protected な便利メソッドです。

```typescript
await this.notify(
  {
    source: 'my-provider',
    kind: 'pr-updated',
    summary: 'PR #123 was updated',
    priority: 'high',
    payload: { prNumber: 123 },
  },
  { threadId: 'thread-1', resourceId: 'user-1' },
)
```

**notification** (`object`): 通知 Payload。

**notification.source** (`string`): 通知 Source の識別子。

**notification.kind** (`string`): イベントの種類（たとえば、"pr-updated"、"new-message"）。

**notification.summary** (`string`): 人が読めるイベントの要約。

**notification.priority** (`"high" | "medium" | "low"`): 通知の優先度。

**notification.payload** (`unknown`): 通知に添付する任意のデータ。

**target** (`SignalProviderTarget`): 通知先の Thread。threadId と resourceId を含める必要があります。

## 型

### `SignalSubscription`

`subscribe()` が返す Subscription オブジェクトです。

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

**providerId** (`string`): この Subscription を所有する Provider。

**threadId** (`string`): Signal を受信する Thread。

**resourceId** (`string`): Thread を所有する Resource。

**externalResourceId** (`string`): 外部 Resource の Provider 固有の識別子（たとえば、"github:owner/repo#123"）。

**subscribedAt** (`Date`): Subscription が作成された日時。

**metadata** (`Record<string, unknown>`): Subscription とともに保存される Provider 固有の Metadata。

### `SignalProviderTarget`

特定の Agent Thread を識別します。

**threadId** (`string`): 対象の Thread。

**resourceId** (`string`): Thread を所有する Resource。

**agentId** (`string`): Agent の識別子。

## 型ガード

### `isSignalProvider(obj)`

`SignalProvider` インスタンスかどうかを実行時に確認します。

```typescript
import { isSignalProvider } from '@mastra/core/signals'

if (isSignalProvider(obj)) {
  obj.connect(agent)
}
```

戻り値: `boolean`