createNotificationInboxTool()

Added in: @mastra/core@1.39.0

createNotificationInboxTool() creates a Mastra tool that lets an agent inspect and manage notification inbox records for the current thread.

Use this tool with durable notification signals. For sending notification records, see Agent.sendNotificationSignal().

Usage example

The following example adds the inbox tool to an agent.

src/mastra/agents/support-agent.ts

import { Agent } from '@mastra/core/agent'
import { createNotificationInboxTool } from '@mastra/core/notifications'

const notificationsStorage = await storage.getStore('notifications')

export const supportAgent = new Agent({
  id: 'support-agent',
  name: 'Support Agent',
  instructions: 'Help the user triage updates.',
  model: 'openai/gpt-5.6-sol',
  tools: {
    notificationInbox: createNotificationInboxTool({ storage: notificationsStorage }),
  },
})

Parameters

options:

object

Tool configuration.

object

storage:

NotificationsStorage

Notification storage domain returned by storage.getStore('notifications').

Tool input

The generated tool has the id notification-inbox and accepts these input fields.

action:

'list' | 'read' | 'markSeen' | 'dismiss' | 'archive' | 'search'

Inbox action to perform.

threadId?:

string

Thread ID to inspect. Defaults to the current agent thread when available.

id?:

string

Notification ID. Required for markSeen, dismiss, and archive. Optional for read.

status?:

'pending' | 'delivered' | 'seen' | 'dismissed' | 'archived' | 'discarded' | 'failed'

Status filter for list, read, or search actions.

priority?:

'low' | 'medium' | 'high' | 'urgent'

Priority filter for list, read, or search actions.

source?:

string

Source filter for list, read, or search actions.

query?:

string

Search query. Required when action is search.

limit?:

number

Maximum number of notifications to return. Must be a positive integer.

Actions

Action	Description
list	Returns matching notifications. Without status, returns pending, delivered, and failed notifications and marks them seen.
read	Delivers readable notification contents as signals and marks delivered records as seen.
markSeen	Marks one notification as seen.
dismiss	Marks one notification as dismissed.
archive	Marks one notification as archived.
search	Searches notifications by query and optional filters.

A notification is failed when Mastra ran out of delivery attempts for it. The default list includes failed notifications. Any list or search that returns a failed notification shows it with status: 'failed' and its lastDeliveryError, then marks it seen, so later lists don't repeat it. Filtering by status: 'failed' finds the notification only until it's first returned; after that it's seen, and deliveryAttempts and lastDeliveryError stay on the record.

When read finds pending or delivered notifications, the tool delivers their contents as notification signals instead of returning the full contents as normal tool output. Use this after a <notification-summary> signal when the agent needs the full records behind the summary.