Agent Alerts セットアップ
自動化を設計し、ホスト型Webhookを設定し、ランタイムの送信は
$agent-alerts-execution に委ねてください。セットアップ中は、ユーザーがスモークテストを要求しない限り、送信を行わないでください。
開始手順
ユーザーに以下のページを開くよう指示するか、直接案内してください:
https://www.andreas.ink/agent
ページに表示される現在の接続フローに従い、iPhoneでAgent Alertsと接続します。このフローにより、ランタイム用の発行専用トークンが作成されます。ユーザーにそのトークンをチャットに貼り付けさせないでください。
Webhookの設定
- ランタイムに名前を付け、公開セットアップページで接続フローを完了します。
- ランタイムのトークン保存場所を選択します:
- ホスト型ランタイム: ワンタイムトークンをそのランタイムのシークレットマネージャーに
AGENTALERTS_AGENT_TOKENとして保存します。 - ローカルMac: ユーザーが承認した
~/.config/agent-alerts/token.envファイルに、AGENTALERTS_AGENT_TOKEN=<token>という1行だけを保存し、パーミッションを0600に設定します。
- ホスト型ランタイム: ワンタイムトークンをそのランタイムのシークレットマネージャーに
- ユーザー自身が選択したシークレットストアにトークンを直接入力させてください。AIの会話の中で入力させることは絶対にしないでください。
../agent-alerts-execution/scripts/send_webhook.shに組み込まれているエンドポイントを使用します。セットアップページから異なるHTTPSエンドポイントが提供された場合のみ、AGENTALERTS_WEBHOOK_URLを設定します。- アウトバウンドHTTPSはそのエンドポイントのみに許可します。
send_webhook.shの正確な絶対パスを、無人実行のために認可します。シェルへの広範なアクセスは許可しないでください。
トークンをプロンプト、URL、クエリ文字列、ログ、ソースファイル、トラッキング設定ファイル、シェル履歴、コマンド引数に決して入れないでください。
テストの準備と検証
../agent-alerts-execution/assets/compact-webhook-payload.json を書き込み可能なペイロードファイルにコピーし、サンプル値を置き換えます。イベントには安定した一意の冪等性キーを使用してください。
ペイロードを検証します:
../agent-alerts-execution/scripts/send_webhook.sh --check payload.json
ペイロード、トークンソース、パーミッション、エンドポイントを送信せずに検証します:
../agent-alerts-execution/scripts/send_webhook.sh --check-config payload.json
次に、機密を含まないスモークテストを1回送信します:
../agent-alerts-execution/scripts/send_webhook.sh payload.json
無人自動化の場合、実際の保存済みランナーから --check-config とスモーク送信を再度実行します。どちらも承認プロンプトなしで完了する必要があります。ランナーが正確なヘルパーを実行できないか、エンドポイントに到達できない場合は、AGENTALERTS_SCRIPT_NOT_AUTHORIZED で停止します。
アラートの設計
以下の項目を定義してください:
- シグナル、データソース、トリガー。
good、warning、criticalのマッピング。- スキップ条件、サイレント時間、除外条件。
- 安定した
activity_idまたは通知識別子。 - サーフェス:
live_activity、widget、notificationのいずれか。 - アクションテキストと安全なターゲットURLまたはアプリのディープリンク。
- アラートが後でまたは繰り返し実行される場合の永続的なスケジューラ。
Agent Alertsは更新を配信しますが、エージェントセッションを維持しません。将来または繰り返しの実行は、現在のセッションが閉じられた後もスケジューラが登録されたままにならない限り不完全です。そうでない場合は AGENTALERTS_SCHEDULER_NOT_DURABLE を返します。
ペイロード契約
通常のアラートにはコンパクトなWebhookボディを使用します:
{
"title": "ビルド完了",
"summary": "すべてのテストが成功しました。",
"status": "good",
"activity_id": "build-monitor",
"source_name": "Codex",
"surfaces": ["live_activity", "notification"],
"idempotency_key": "build-monitor-2026-07-29T18-30-00Z"
}
Webhookには以下が必要です:
Authorization: Bearer <AGENTALERTS_AGENT_TOKEN>
Content-Type: application/json
Idempotency-Key: <idempotency_key と同じ値>
ヘルパーはプロセス引数にトークンを露出させずにこれらのヘッダーを提供します。必ずヘルパーを使用し、手動でリクエストを再作成しないでください。
コンパクト送信のデフォルトは、webhook という名前の1つのアップサートアクティビティ、プロダクション配信、そしてこれらのフィールドが省略された場合は live_activity と notification です。自動化が異なる結果を必要とする場合は、これらを明示的に設定してください。
ウィジェット、コントロールウィジェットの状態、ビルダーレイアウト、またはその他の高度なフィールドについては、ネストされた payload オブジェクトを持つフルスネークケースのWebhook契約を使用してください。フルの payload オブジェクトと、コンパクトな title、summary、status、source_name、deep_link フィールドを混在させないでください。
コピーと配信ルール
表示されるコピーは完全で、以下の制限内に収めてください:
| フィールド | 最大文字数 |
|---|---|
source_name | 14 |
title | 32 |
summary | 96 |
切り捨てに頼ったり、省略記号を追加したりしないでください。
live_activityはDynamic Islandまたはロック画面を更新します。widgetには、ウィジェット識別子、小さな非機密スナップショット、およびリロード有効化が必要です。notificationには、グループ化のための安定したスレッド識別子が必要です。- コントロールウィジェットの状態は、アクティブな警告またはクリティカル状態の場合は true に、クリアまたは解決状態の場合は false に設定してください。
ランタイムハンドオフ
以下の正確なランタイム命令を1つ記述します:
$agent-alerts-execution を使用します。まず設定されたスキップ条件を評価します。送信が必要な場合、準備したAgent Alerts JSONを承認済みのペイロードパスに書き込み、次に認可された絶対パスの send_webhook.sh をそのファイルを引数として実行します。トークンは AGENTALERTS_AGENT_TOKEN または承認済みの token.env ファイルからのみ読み取ります。返されたステータスとターゲット、成功数、失敗数を、秘密情報を出力せずに報告します。
実際のランナーが構成を検証し、対話なしで送信し、必要な場合はスケジュールが永続的であり、結果がデバイスに表示される配信を過大評価せずに報告された場合にのみ、セットアップは完了です。