createNotificationInboxTool()

Added in: @mastra/core@1.39.0

beta

Breaking changes may occur without a major version bump until the API is stable.

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'

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.
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.

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.