Cue

コードレビューエージェント、ログのトリアージエージェント、請求処理エージェントが、午前2時に同じエンジニアへ一斉に通知することがあります。LangGraph の interrupt() や Slack の承認ボタンは、エージェントを1つ停止させることはできますが、ほかのエージェントがすでに何を送信したかは把握できません。Cue はすべてのエージェントの前段に立ち、送信を管理します。

• エージェントごと、ユーザーごとの予算。 各エージェントは独自のキーを使って送信します。frequency_caps は、各期間にエージェントが1人のユーザーへ送信できるメッセージ数を制限します。予算を超えたメッセージは、理由 agent_budget とともに suppressed として保存されます。カテゴリごとの上限は、すべての送信元からユーザーに届くメッセージをまとめてカウントします。
• ユーザーのタイムゾーンに合わせた静穏時間。 ユーザーの静穏時間中に送信予定のメッセージは、静穏時間が終わるまで待機します。購読を解除できないカテゴリの critical メッセージのみ静穏時間を突破できます。また、各エージェントの max_importance が設定可能な重要度の上限となるため、critical を使用できるのは信頼できるエージェントだけです。
• そのほかのメッセージにはダイジェスト。 ダイジェストルールにより、エージェントのイベントの連続を、ウィンドウごとに1件、または現地時刻の指定時刻に1日1件のメッセージにまとめられます。
• リスクのあるメッセージには承認を適用。 エージェントの approval 条件に一致するメッセージは pending_approval として保留され、レビュー担当者が自分の通知にある一度限りのリンクから判断します。エージェントキーで承認することはできません。
• すべての結果に理由を記録。 各メッセージにはステータスと status_reason があり、各イベントにはどのルールが一致したか、その理由とともに記録されます。エージェントは HTTP、SDK、または MCP サーバー経由で接続できます。

ライブラリとして使用する

サーバーは不要です。pip install cue-notify を実行し、SQLite ファイルに状態を保存して、プロセス内で判断します。メッセージは自分で送信します。

from cue_notify.embedded import Gate

gate = Gate("sqlite:///cue.db", quiet_hours=("22:00", "08:00"), caps={"marketing": [("P1D", 1)]})
decision = gate.check("user-42", category="marketing", timezone="Europe/Berlin", key="sale-42")
if decision.action == "send":
    print("sending now")
    gate.sent(decision)
else:
    print(decision.action, decision.at, decision.reason)
for due in gate.due():
    print("sending", due.key)
    gate.sent(due)

check() は理由とともに send、defer（decision.at まで）、suppress、または digest を返します。due() は、送信時刻に達した延期メッセージとダイジェストのまとまりを返します。各ユーザーのタイムゾーンに合わせた静穏時間、上限、クールダウン、送信元ごとの予算、ダイジェスト、冪等性キーはサーバーと同様に動作しますが、テンプレート、チャネル、設定ページは含まれません。Cue をライブラリとして使用するをご覧ください。

冒頭のデモ動画は examples/agents-demo です。リポジトリをチェックアウトし、uv run python examples/agents-demo/demo.py を実行すると、SQLite とコンソールコネクターを使って動作します。

クイックスタート

Docker Compose（PostgreSQL、API、ワーカーを使用。メッセージはワーカーのログに出力されます）を使う場合：

git clone https://github.com/murtazox04/Cue && cd Cue
docker compose up --build -d
docker compose exec api cuectl keys create admin
docker compose logs -f worker

または、Python 3.12+ と SQLite を使い、仮想環境で実行する場合：

python -m venv .venv && . .venv/bin/activate
pip install cue-notify
export CUE_WORKER__EMBEDDED=true
export CUE_CHANNELS__PUSH__PROVIDER=console CUE_CHANNELS__SMS__PROVIDER=console
cuectl db upgrade && cuectl keys create admin && cuectl serve

keys create は API キーを一度だけ表示します。CUE_API_KEY として保管してください。その後、getting-started guide に従ってテンプレートとルールを作成し、ログに表示されるイベントを送信してください。また、agents を参照して、エージェント専用のキーと制限を設定してください。

何もインストールせずに試す場合は、uv を使います。

CUE_WORKER__EMBEDDED=true CUE_CHANNELS__PUSH__PROVIDER=console \
  CUE_CHANNELS__SMS__PROVIDER=console uvx cue-notify serve --migrate

同じディレクトリで別のターミナルを開き（どちらも ./cue.db を使用します）、uvx cue-notify keys create admin を実行してください。

エージェント向けの詳細

• 送信者としてのエージェント。 各エージェントには、個人ごとの注意予算、重要度の上限、必要に応じた送信前の人間による承認を設定した専用キーが付与されます。エージェントキーでは、ユーザーのプロフィールを読み取ったり変更したりできず、何かを承認することもできません。agents を参照してください。
• まず人に確認する。 返金、削除、一斉メールなどのリスクを伴うアクションの前に、エージェントは POST /v1/approvals または request_approval MCP ツールを呼び出します。Cue はレビュー担当者それぞれのチャネルに一度限りのリンクを送信し、決定を報告します。LangGraph、Pydantic AI、CrewAI Flows、Dapr Agents とのブリッジも用意されています。approval requests を参照してください。
• MCP サーバー。 uvx cue-notify mcp を使うと、Claude、Cursor、または独自のエージェントに、人への通知や配信状況の確認を行うツールを提供できます。ポリシーと監査証跡は共通です。AI agents (MCP) を参照してください。
• スクリーニング（任意、デフォルトでは無効、実験的機能）。 [screening] enabled = true と TypeSafe API キーを設定すると、判定モデル（Jev）がエージェントの各メッセージを送信前に確認します。圧力、欺瞞、漏えいしたシークレットが検出された場合は人による確認のために保留され、誇張された重要度は引き下げられます。TypeSafe が公開している API に基づいて構築されており、本番環境での有効性はまだ実証されていません。独自のバックエンドからのメッセージはスクリーニングされません。
• コーディングエージェント。 cue-hook を使うと、OpenHands と Claude Code から、作業の完了や入力待ちを通知できます。coding agents を参照してください。
• Claude Code プラグイン。 /plugin marketplace add murtazox04/Cue の後に /plugin install cue@cue を実行すると、アプリケーションへの Cue の統合を支援するスキルが追加されます。

独自のバックエンドからの通知

同じポリシーを、製品独自の通知にも適用できます。バックエンドから発生した内容（order.shipped、payment.failed）を Cue に報告すると、通知する価値があるかどうかを Cue が判断し、ユーザーの言語で内容を作成し、送信時刻と経路を選択して、接続先の配信サービスに完成したメッセージを渡します。接続先には、署名付き Webhook を介した独自の送信サービス、または同梱コネクターを指定できます。

• ルールとポリシーを一元管理。 JSON Logic ルールによってイベントをテンプレートに割り当てます。ルールによる通知、直接送信、ブロードキャストのいずれであっても、すべてのメッセージで同じチェックが行われます。配信停止、ミュートされたチャネル、頻度上限、クールダウン、受信者のタイムゾーンでの静穏時間を確認し、送信直前にも再確認します。
• メッセージを削減。 ダイジェスト機能により、短時間に集中したイベントを時間枠ごとに1件、または現地時間の指定時刻に1日1件のメッセージにまとめます。また、エンゲージメントが低下したユーザーへの通知を抑制する疲労対策機能もあります。
• ユーザーが管理。 ホスト型の設定ページ（または独自に用意した JSON API）、RFC 8058 準拠のワンクリック配信停止、すべての変更を記録する同意台帳を利用できます。
• 回答。 各イベントには、どのルールが一致したか、その理由が記録されます。各メッセージには、ステータスと、抑止または失敗した理由が記録されます。

curl -X POST https://cue.example.com/v1/events \
  -H "Authorization: Bearer $CUE_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "order.shipped", "recipient": "customer-42",
       "data": {"order_id": "1001"}, "idempotency_key": "order-1001-shipped"}'

配信エンドポイントには、署名付きのレンダリング済みメッセージが届きます。

{
  "id": "01a1…",
  "channel": "push",
  "address": "<device token>",
  "locale": "en",
  "importance": "normal",
  "expires_at": null,
  "content": {"title": "Your order is on its way", "body": "Order 1001 ships today.",
              "url": "https://shop.example/orders/1001"},
  "metadata": {"cue_message_id": "01a1…", "cue_tracking_token": "…"},
  "links": {"preferences": "https://cue.example.com/preferences/…"}
}

対象ユーザー

対象： エージェント、バックグラウンドジョブ、またはプロダクトコードから、プッシュ通知、メール、SMS、チャットメッセージをユーザーに送信しており、送信するかどうか、いつ送るか、頻度、経路、言語といった判断を一元管理し、自社のインフラ上に保存して説明できるようにしたいチームです。

まだ適していないケース： 次のものが必要な場合です。

• アプリ内の受信トレイや通知フィード：計画中ですが、まだ実装されていません。
• 管理 UI：現在、Cue は HTTP API、CLI、cue.toml を使って設定します。
• Cue がまだ対応していないコネクター。現時点では、FCM、APNs、Twilio、SMTP、Amazon SES、Resend、Slack、Telegram、署名付き Webhook、コンソールに対応しており、独自のコネクターも作成できます。
• ホステッドサービス：Cue はセルフホストのみです。
• マーケティングキャンペーン向けのビジュアルなジャーニービルダー：計画されていません。

ロードマップをご覧ください。

配信手段は自由に選べます

各ルート（push、sms、email、ops-alerts…）はコネクターによって動作します。

コネクター	使用するケース
webhook	すでに送信サービスがある場合、またはすべてを自分で制御したい場合。Cue は署名付き JSON を POST します。
fcm、twilio、smtp、telegram	これらのプロバイダー向けの既製コネクターを使いたい場合。
console	ローカル開発用：メッセージがログに記録されます。
独自のコネクター	小さなクラスを作成してプラグインとして登録します。カスタムコネクターをご覧ください。

コネクターは設定であり、コードの変更は不要です。ルールに手を加えずに SMS プロバイダーを切り替えられます。

その他

• SDK。 pip install cue-notify-client と npm install cue-client を利用できます。どちらも Webhook 署名の検証に対応しています。SDKをご覧ください。
• エンゲージメントの追跡。 配信、開封、クリック、コンバージョンを追跡できます。クライアントアプリからメッセージごとのトークンで報告でき、API キーは不要です。
• 一斉配信。 オーディエンスのフィルター、再開可能なバッチ、二重送信を避けた一時停止／再開／キャンセルに対応しています。
• コンプライアンス。 米国のマーケティングテキスト向け送信可能時間と州ごとの上限、STOP／START への返信、表示した開示文を含むオプトイン記録に対応しています。コンプライアンスをご覧ください。
• データベース上で動作。 API プロセスとワーカープロセス（小規模な環境では API にワーカーを組み込むこともできます）を使用し、PostgreSQL または SQLite に対応しています。Redis やメッセージブローカーは不要です。永続ジョブキューはデータベース内にあります。保持期間の管理には、cuectl prune を自分でスケジュールしてください。
• 可観測性。 ルールごとのイベント結果、ステータスの理由、Prometheus メトリクス、JSON ログを利用できます。
• ツール向けドキュメント。 llms.txt と AGENTS.md をご覧ください。

Cue との比較

	概要	Cue との違い
Novu	セルフホスト可能な通知インフラストラクチャです。	セルフホスティングガイドには、MongoDB、Redis、S3 互換ストレージが記載されています。Cue に必要なのは、PostgreSQL または SQLite のどちらか 1 つです。
Knock、Courier、OneSignal	ホステッド型の通知サービスです。	これらのサービスに登録する必要がありますが、Cue はお客様のインフラストラクチャ上で動作します。
Apprise、ntfy	多くのサービスやデバイスにメッセージを配信するツールです。	渡したメッセージを送信します。ユーザーに通知すべきか、またいつ通知すべきか（設定、上限、タイムゾーンに応じたサイレント時間、ダイジェスト）は、コード側で処理する必要があります。Cue はその判断を行ってから、メッセージを送信者に渡します。
エージェントフレームワーク内の人による承認（LangGraph の interrupt()、Slack の承認ボタン）	ユーザーの回答を待つ間、1 つのエージェントの実行を一時停止します。	対象となるのは 1 つのエージェントと 1 つの判断だけです。その夜、他のエージェントからユーザーにすでに何通メッセージが届いているかは考慮されません。Cue は、すべてのエージェントを対象に上限、サイレント時間、ダイジェストを適用します。また、承認リクエストを使って、LangGraph、Pydantic AI、CrewAI Flows、Dapr Agents を再開できます。
フレームワークの通知ライブラリ（Laravel、Rails、Django など）	通知の書式設定と送信を行うアプリケーション内のコードです。	ポリシー、設定、履歴はアプリケーションごとに構築する必要があります。Cue では、それらを 1 つのサービスにまとめ、すべてのアプリケーションとエージェントから呼び出せます。

仕組み

flowchart LR
    E[POST /v1/events] --> R{Rules}
    R --> P[Policy<br/>unsubscribe · caps · cooldown · quiet hours]
    P --> T[Template<br/>locale · route variants]
    T --> Q[(Queue)]
    Q --> A[AI rewording<br/>optional]
    A --> C{Your delivery<br/>webhook · connectors}

概念	概要
イベント	受信者に起きたことです。冪等性があり、ルールごとの結果とともに保存されます。
ルール	イベント X（および条件）が発生したら、ルート［A、B］を通じてテンプレート Y を送信します。
テンプレート	ローカライズされたコンテンツと、ルートごとのバリエーションです。
カテゴリ	ポリシーの設定一式です。頻度の上限、サイレント時間、配信停止を許可するかどうかを含みます。
チャネル	コネクターに接続された、名前付きのルート（push、sms など）です。
メッセージ	ステータスの全履歴を含む、1 人の受信者への 1 件の通知です。
ブロードキャスト	再開可能なバッチで、対象者に 1 つのテンプレートを送信します。

設定

環境変数（CUE_SECTION__KEY）または cue.toml を使用します。

[database]
url = "postgresql+asyncpg://cue:secret@db/cue"

[api]
public_url = "https://cue.example.com"   # needs CUE_API__SECRET_KEY

[channels.push]
provider = "webhook"
url = "https://notifications.internal.example/push"   # secret from CUE_CHANNELS__PUSH__SECRET

[channels.sms]
provider = "twilio"
account_sid = "AC…"
from_number = "+15550100"   # auth token from CUE_CHANNELS__SMS__AUTH_TOKEN

設定リファレンス、 デプロイ、 examples/cue.tomlを参照してください。

プロジェクトの状況

Cue は初期開発段階（0.x）です。モデルと API の大枠は安定していますが、1.0 までに変更される可能性があります。各リリースの変更履歴に、アップグレード時に必要な対応が記載されています。今後の予定についてはロードマップを参照してください。フィードバックや貢献を歓迎します。CONTRIBUTING.mdをご覧ください。

ライセンス

MIT