Notifications

Notifications are the primary mechanism for directing an agent’s attention. They replace scattered read-tracking across channels and give you a single, unified queue that determines what the agent works on next.

How Notifications Work

Every notification has a priority that controls agent behavior:

Priority	Wake Agent	Block Sleep	Use Case
`high`	Yes	Yes	Inbound messages, urgent events, tasks requiring action
`low`	No	No	Informational updates, logging, non-urgent reminders

High-priority notifications wake the agent immediately and prevent it from sleeping until cleared.
Low-priority notifications are informational — the agent sees them on its next run but isn’t woken for them.

The agent must explicitly clear each notification to dismiss it.

Notification Fields

Field	Type	Description
`id`	UUID	Auto-generated unique identifier
`agent`	UUID	The agent this notification belongs to
`source`	string	Origin of the notification (see Sources)
`source_id`	string	Context id for the notification. For inbound messaging (`sms`, `mms`, `webchat`, `surge`, etc.) this is the Contact UUID the agent should pass to `send_message`, `send_sms`, and attachment tools. The notification `body` may also include a local Message ID for `open_sms_attachment` / similar tools.
`title`	string	Notification title shown to the agent
`body`	string	Additional details/context
`priority`	`"high"` \| `"low"`	Controls wake and sleep behavior
`created_at`	datetime	When the notification was created
`scheduled_for`	datetime \| null	When the notification becomes active (for future reminders)
`cleared`	boolean	Whether the agent has dismissed it
`cleared_at`	datetime \| null	When it was cleared

Agent Tools

The Notifications adapter provides three tools that agents can call directly:

`list_notifications`

Lists active notifications for the agent. By default only shows uncleared notifications that are not scheduled for the future.

Parameter	Type	Default	Description
`include_cleared`	boolean	`false`	Include already-cleared notifications
`limit`	integer	`50`	Max notifications to return (capped at 100)

`clear_notification`

Clears (dismisses) a notification by ID. The agent must clear high-priority notifications before it can sleep.

Parameter	Type	Required	Description
`notification_id`	UUID	Yes	ID of the notification to clear

`create_notification`

Creates a new notification, typically used by the agent to set reminders for itself.

Parameter	Type	Required	Description
`title`	string	Yes	Notification title
`body`	string	No	Additional details
`priority`	`"high"` \| `"low"`	No	Defaults to `"low"`
`scheduled_for`	ISO 8601 datetime	No	When the notification should become active

When an agent creates a notification with scheduled_for set to a future time, it won’t appear in list_notifications until that time arrives. This is how agents create reminders — the notification surfaces when the schedule time passes and the agent is next awake.

Scheduled Notifications (Reminders)

Notifications with scheduled_for set to a future datetime act as reminders:

The notification is created but hidden from list_notifications
A periodic workflow scans for agents with uncleared high-priority notifications whose scheduled_for has passed
The agent is woken up and sees the notification

This lets agents (or external systems) schedule future work without needing a separate task model.

curl -X POST https://api.bedrock.orinlabs.org/api/defaults/notifications/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "AGENT_ID",
    "title": "Follow up with customer",
    "body": "Check if they resolved their billing issue",
    "priority": "high",
    "scheduled_for": "2025-01-15T14:00:00Z"
  }'

Sources

The source field identifies where a notification came from:

Source	Description
`email`	Inbound email received via AgentMail
`sms`	Inbound SMS via Twilio
`mms`	Inbound iMessage/RCS via Linq
`surge`	Inbound SMS via Surge
`blooio`	Inbound SMS via Blooio
`system`	System events (OAuth connected, agent created, etc.)
`agent`	Self-created by the agent (reminders)
`subagent`	Message from a parent or child agent
`browser`	Browser automation task completed, failed, or needs help
`api`	Created via the REST API
`portal`	Created from the Bedrock portal UI

`source_id` on inbound messages

list_notifications labels source_id as contact_id for human-facing messaging sources. Inbound webhooks store the sender’s Contact UUID in source_id (not the Twilio MessageSid, Surge message id, or other provider id). That value is the same id send_message / send_sms / open_sms_attachment expect. When a message includes attachments, the notification body also carries the local message row’s UUID and the correct open_*_attachment tool name, for example:

[1 attachment(s) included - Message ID: <uuid>; use open_sms_attachment(message_id="<uuid>") to view]

Do not pass provider message ids or the notification’s own Notification ID as contact_id.

Wake/Sleep Lifecycle

Notifications integrate directly with the agent’s autonomous runtime:

Inbound event (e.g. SMS received) → create_notification(priority="high")
High-priority notification triggers wake_agent → agent starts running
Agent calls list_notifications to see what needs attention
Agent processes the notification (reads the SMS, responds, etc.)
Agent calls clear_notification to dismiss it
Agent attempts to sleep — succeeds because no uncleared high-priority notifications remain

If an agent tries to sleep with uncleared high-priority notifications, the sleep tool returns an error instructing it to clear them first.

REST API

Manage notifications externally via the REST API. All endpoints require authentication (API key or portal token). Base path: /api/defaults/notifications/

List Notifications

curl -X GET "https://api.bedrock.orinlabs.org/api/defaults/notifications/?agent=AGENT_ID&cleared=false&priority=high" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameter	Description
`agent`	Filter by agent UUID
`cleared`	Filter by cleared status (`true` / `false`)
`priority`	Filter by priority (`high` / `low`)

Create a Notification

curl -X POST https://api.bedrock.orinlabs.org/api/defaults/notifications/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "AGENT_ID",
    "title": "New support ticket #1234",
    "body": "Customer reports login issue",
    "source": "api",
    "priority": "high"
  }'

Creating a notification with priority: "high" (and no scheduled_for) will immediately wake the agent.

Update a Notification

curl -X PATCH https://api.bedrock.orinlabs.org/api/defaults/notifications/NOTIFICATION_ID/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cleared": true}'

Delete a Notification

curl -X DELETE https://api.bedrock.orinlabs.org/api/defaults/notifications/NOTIFICATION_ID/ \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Format

{
  "id": "notification-uuid",
  "agent": "agent-uuid",
  "source": "api",
  "source_id": "",
  "title": "New support ticket #1234",
  "body": "Customer reports login issue",
  "priority": "high",
  "created_at": "2025-01-15T10:30:00Z",
  "scheduled_for": null,
  "cleared": false,
  "cleared_at": null
}

Common Patterns

Triggering Agent Work from Your Backend

Use the API to create a high-priority notification whenever your system has work for an agent:

import requests

def assign_task_to_agent(agent_id: str, task_title: str, task_details: str):
    requests.post(
        "https://api.bedrock.orinlabs.org/api/defaults/notifications/",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        json={
            "agent": agent_id,
            "title": task_title,
            "body": task_details,
            "source": "api",
            "priority": "high",
        },
    )

The agent wakes up, reads the notification, and acts on it autonomously.

Polling for Completed Work

Check for cleared notifications to know when an agent has handled something:

curl -X GET "https://api.bedrock.orinlabs.org/api/defaults/notifications/?agent=AGENT_ID&cleared=true&source=api" \
  -H "Authorization: Bearer YOUR_API_KEY"

​Notifications

​How Notifications Work

​Notification Fields

​Agent Tools

​list_notifications

​clear_notification

​create_notification

​Scheduled Notifications (Reminders)

​Sources

​source_id on inbound messages

​Wake/Sleep Lifecycle

​REST API

​List Notifications

​Create a Notification

​Update a Notification

​Delete a Notification

​Response Format

​Common Patterns

​Triggering Agent Work from Your Backend

​Polling for Completed Work

Notifications

How Notifications Work

Notification Fields

Agent Tools

`list_notifications`

`clear_notification`

`create_notification`

Scheduled Notifications (Reminders)

Sources

`source_id` on inbound messages

Wake/Sleep Lifecycle

REST API

List Notifications

Create a Notification

Update a Notification

Delete a Notification

Response Format

Common Patterns

Triggering Agent Work from Your Backend

Polling for Completed Work