DevOps Agent のイベントトリガとスキップ用スキルで、低優先度アラームをカスタムエージェントに振り分けてみる
こんにちは
不急タスクは明日の自分に振り分け
運用イノベーション部のかわいです。
小ネタ記事です。
2026/9/14、AWS DevOps Agent のカスタムエージェントにイベントトリガが追加されました。
これまでカスタムエージェントはスケジュールまたは手動でしか動かせませんでしたが、Webhook のイベントが届いたタイミングで起動できるようになっています。
Run custom agents from webhook events
You can now run a custom agent when a webhook event arrives from a connected integration, rather than only on a schedule. Any integration with an active webhook can be the event source. An optional JMESPath filter expression controls which events run the agent and what part of the payload the agent receives.
上記について以下 AWSブログで、CloudWatch アラームを Webhook で DevOps Agent に渡し、本調査（Investigation）を自動で始める構成が紹介されています。
この記事内の調査では、エージェントが動いた秒数で課金されるので、例えば優先度の低い LOW のアラームまで毎回じっくり調べさせるのは少し過剰になるかもしれません。
こういったケースでイベントトリガを使えば、「LOW は軽いカスタムエージェントに一次確認させて、本調査は重いものだけに絞る」ような動きが取れそうです。
ただ、Webhook で本調査を自動で始めている環境にイベントトリガを追加した際、例えば「本調査が止まってカスタムエージェントに置き換わるのか？」、はたまた「両方とも動くのか？」等は、ドキュメントでは明言されていません。
ので、今回は検証用の Agent Space を作って実際にどのような挙動を取るのかを試してみました。
カスタムエージェントとイベントトリガについて
カスタムエージェント は、目的とプロンプトをカスタマイズして作成できるエージェントです。
以下記事で紹介されているように、定期レポート作成等の作業に活用できます。
起動方法としては、今すぐ実行（手動）、スケジュールトリガ、イベントトリガの3種類で、イベントトリガのフィルタ式は、ドキュメント上で次のように説明されています。
Filter expressions are evaluated against the raw event payload root.
When the result is not null, false, an empty string, an empty array, or an empty object, the trigger runs.
When the result is the boolean true (for example, a predicate like severity == 'critical'), the agent receives the raw event payload as context.
When the result is any other truthy value (for example, a projection like {sev: severity}), the agent receives the projected result as context.
今回は、条件（true/false を返す式）のみ使用します。
検証環境
| 項目 | 内容 |
|---|---|
| リージョン | ap-northeast-1（東京） |
| Agent Space | 検証用に新規作成（名前 test） |
| イベントの送信元 | Agent Space の Webhook（HMAC）に CloudShell から curl で送信 |
| 監視対象 | ダミーの CloudWatch アラーム test-alarm（名前空間 Test、メトリクス Errors） |
| カスタムエージェント | test-agent（アラーム状態を見て5行で返すのみ） |
| スキル | test-skip（LOW/MINIMAL の調査をスキップする） |
検証ではアラームと Webhook は繋がず、priority を手で指定して CloudShell から直接送ります。
実際にアラームと接続する場合は Lambda関数経由でペイロードに変換する方法のほか、Webhook を API キー方式で作り、EventBridge の API 送信先から直接送る方法があります。具体的な方法は以下記事で解説されています。
事前準備
1. Agent Space の作成とログ配信
Agent Space は検証用に新しく作り、デフォルトで有効になっている週次の評価（Evaluations）は一時停止しました。
また、イベントを受け取ったか？トリガが動いたか？を見るため、ログを CloudWatch Logs に送る設定にしています。
Agent Space の「ログ配信」>「追加」>「Amazon CloudWatch Logs への配信を追加」から、ログタイプ APPLICATION_LOGS、配信先を /test/devops-agent にしています。
/aws/vendedlogs/ で始まらないロググループの場合、先に作っておく必要があります。
2. Webhook とダミーのアラーム
Agent Space の Capabilities タブから、Agent Space Webhook を HMAC で作成します。
ダウンロードした .csv の URL とシークレットは、CloudShell の環境変数に入れておきます。
export WEBHOOK_URL='<Webhook URL>'
export WEBHOOK_SECRET='<シークレット>'
また、エージェントが確認する先として、ダミーのアラームを作ります。
aws cloudwatch put-metric-data --namespace Test --metric-name Errors --value 5
aws cloudwatch put-metric-alarm --alarm-name test-alarm \
--namespace Test --metric-name Errors --statistic Sum \
--period 300 --evaluation-periods 1 --threshold 1 \
--comparison-operator GreaterThanOrEqualToThreshold --treat-missing-data notBreaching
上記 set-alarm-state で ALARM 状態にしてもすぐ戻ってしまったので、送信の直前に put-metric-data で値を入れ直しています。
3. ペイロード送信用スクリプト
公式の HMAC の形式に合わせ、ペイロード を HMAC-SHA256 で署名して送信します。
cat > send.sh <<'EOF'
#!/bin/bash
# usage: ./send.sh <PRIORITY> <INCIDENT_ID> [MARKER]
set -euo pipefail
: "${WEBHOOK_URL:?}" "${WEBHOOK_SECRET:?}"
PRI=$1; ID=$2; MARKER=${3:-none}
TS=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
PAYLOAD=$(jq -cn --arg id "$ID" --arg pri "$PRI" --arg ts "$TS" --arg m "$MARKER" '{
eventType:"incident", incidentId:$id, action:"created", priority:$pri,
title:("CloudWatch alarm test-alarm is in ALARM (" + $pri + ")"),
description:"CloudWatch alarm test-alarm (namespace Test, metric Errors) entered ALARM state in ap-northeast-1.",
timestamp:$ts, service:"test",
data:{metadata:{region:"ap-northeast-1", marker:$m}}
}')
SIG=$(printf '%s:%s' "$TS" "$PAYLOAD" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -binary | base64 -w0)
curl -sS -w '\nHTTP %{http_code}\n' -X POST "$WEBHOOK_URL" \
-H 'Content-Type: application/json' \
-H "x-amzn-event-timestamp: $TS" \
-H "x-amzn-event-signature: $SIG" \
-d "$PAYLOAD"
EOF
# 権限付与
chmod +x send.sh
data.metadata.marker には、カスタムエージェントに data が届いたかを見分けるための目印を入れます。
ペイロードは Agent Space Webhook の公式スキーマに合わせたもので、priority には CRITICAL / HIGH / MEDIUM / LOW / MINIMAL のどれかが入ります。ペイロード形式はソースごとに違うので、Datadog など、他サービスと連携して送る場合は、この記事のフィルタ式がそのまま使えるとは限りませんのでご了承をば。
4. カスタムエージェント（test-agent）
カスタムエージェントはチャットから対話形式で作成できます。
チャットに次のプロンプトを渡し、名前は test-agent、プロンプトは書き換えないよう依頼しました。
あなたは低優先度アラートの一次確認だけを行うエージェントです。
根本原因の調査は行いません。
手順：
1. 渡されたイベントのペイロードから、CloudWatch アラーム名を特定する
2. そのアラームの現在の状態と、直近1時間のメトリクスを確認する
3. 以下の形式で5行以内で回答し、終了する
出力形式：
- 判定：要調査 / 様子見
- アラーム：<名前> / <状態>
- 根拠：<1行で>
- 受信したペイロードの data フィールド：<受け取った値をそのまま。なければ「なし」と記載>
制約：
- ツール呼び出しは合計10回以内。それ以上の調査はしない
- アーティファクトや推奨事項は作成しない
- 他のアラーム、他のリソース、ログの調査はしない
検証
今回は以下のようなフローで検証を行いました。
【検証1回目】フィルタなしで LOW を1件送る
カスタムエージェントの「トリガ」タブから、トリガタイプ「イベント」、イベントソースに今回作成した Webhook を選び、フィルタは空のままで作成しました。
./send.sh LOW test-t1-$(date +%s) t1-marker
{"message": "Webhook received"}
HTTP 200
結果、本調査とカスタムエージェントの両方が起動しました。
【インシデントレスポンス】上で調査が立ち上がり、同じタイミングで test-agent の履歴も1件追加されました。
加えてlist-backlog-tasksから確認すると、1回の送信で2つのタスクが作成されていることが分かります。
aws devops-agent list-backlog-tasks --agent-space-id $SPACE_ID \
--query 'tasks[].{type:taskType,status:status,pri:priority,created:createdAt,updated:updatedAt}' \
--output table
↓↓
| taskType | priority | status | 作成 → 更新 |
|---|---|---|---|
| INVESTIGATION | LOW | CANCELED（1分ほどで手動停止しました） | 07:32:58 → 07:33:59 |
| CUSTOM | MEDIUM | COMPLETED | 07:33:00 → 07:33:16 |
本調査用に Webhook を繋いでいる環境にイベントトリガを追加すると、デフォルトだと本調査とカスタムエージェントの両方が作動します。なお、カスタムエージェント側のタスクでは、ペイロードの priority が LOW でも MEDIUM になっていました。
test-agent は約16秒で完了し、以下のような結果が返りました。
- 判定: 要調査
- アラーム: test-alarm / ALARM
- 根拠: 直近1時間の 2 データポイント（06:58 と 07:28 UTC）がともに Sum=5.0
- 受信したペイロードの data フィールド: {"metadata":{"region":"ap-northeast-1","marker":"t1-marker"}}
data の中身が返ってきており、タスクの description にもEvent payload:部分に生のペイロードが見えています。
一方で、Webhook のドキュメントでは、本調査には data は含まれないとされています。
Free-form fields from the originating service. The webhook accepts data, but doesn't include its contents in the investigation context. Only title, description, priority, and the incident reference reach the agent.
上記からも、本調査に含まれない data が、カスタムエージェントには届くことが分かりました。
【検証2回目】フィルタとスキップ用スキルを使って振り分ける
次に、本調査とカスタムエージェントの両方が同時に動かないよう、以下の2つを組み合わせてみます。
- イベントトリガのフィルタで、LOW / MINIMAL のときだけカスタムエージェントを起動する
- トリアージのスキップ用スキルで、LOW / MINIMAL の本調査をスキップする
こうすることで、低優先度の調査にかかるコストを抑えられるという魂胆です。
フィルタ式
トリガを作り直し、フィルタ式を次のようにしました。
priority == 'LOW' || priority == 'MINIMAL'
スキップ用スキルの作成
公式ドキュメント上では、トリアージ向けのスキルで調査をスキップできると説明されています。
Skills targeted to the Incident Triage agent type can define criteria for automatically skipping incidents. Use this to filter incidents that don't require investigation. When a new incident matches the skip criteria, AWS DevOps Agent marks it as Skipped. The system provides a reason explaining why it was filtered.
【ナレッジ】->【スキル】上、メンテナンス中の MEDIUM/LOW をスキップする sample-skip-scheduled-maintenance が停止状態で用意されています。
こちらを参考に、【スキルを追加】から test-skip を作ります。
エージェントタイプには「インシデントのトリアージ」を選びます。
説明：
Skip low-priority incidents. Use this skill during incident triage to automatically skip incidents whose priority is LOW or MINIMAL, because they are handled by a separate lightweight pre-check agent.
指示：
# Skip Low Priority
Skip every incident whose priority is LOW or MINIMAL.
Do NOT skip HIGH, CRITICAL, or MEDIUM incidents.
Skip reason: "LOW/MINIMAL は test-agent エージェントで一次確認するため"
結果
LOW を送ってみると本調査はスキップされて、test-agent だけが動きました。
インシデントレスポンスでは「スキップされた調査」ステータスになり、理由と「スキップ解除」ボタンが表示されます。
（解除すると再調査が走ります）
続けて HIGH を送ってみると、
./send.sh HIGH test-t2-high-$(date +%s) t2-high-marker
本調査だけが動き、test-agent は起動せず。想定通りの挙動を取ってくれました。
（おまけ）フィルタに合致しなかったときのログについて
HIGH を送った際、ログ配信先の /test/devops-agent には次のメッセージが出力されていました。
Event trigger goal-xxxx did not fire: filter pattern `priority == 'LOW' || priority == 'MINIMAL'` matched nothing in this event. Filter patterns are evaluated against the event payload root; this payload's top-level fields are: action, data, description, eventType, incidentId, priority, service, timestamp, title.
フィルタに合致しなかった理由に加え、ペイロードの最上位にあるフィールド名も列挙してくれています。
送信元によってペイロードの形が違うので、フィルタを書く前に一度イベントを流し、事前にこのログでフィールド名を確かめておくと良いです。
起動したタイミングでは、受信と起動の2行が記録されます。
Received event from Event Channel with event ID test-t3-1-xxxxxxxxxx
Event trigger goal-xxxx fired: invoking agent ki-xxxx.
ログは JSON形式で、本文は optional_details.message内に入っています。
本文だけ見たい場合は次のように確認します。
aws logs filter-log-events --log-group-name /test/devops-agent \
--start-time $START \
--query 'events[].[timestamp,message]' --output text
【検証3回目】 5秒おきに複数回ペイロードを送ってみる
ドキュメントでは、カスタムエージェントは同時に1件しか実行できないと明記されています。
A custom agent can only run one invocation at a time. If the agent is already running, you must wait for the current invocation to complete, time out, or be canceled before starting another.
これは項目からも手動で実行する際の説明と読めるので、試しに以下を実行し、イベントが連続して届いた場合どうなるのかを見てみます。
# LOW を1回ずつ、5秒間隔で送る（計5件）
for i in 1 2 3 4 5; do ./send.sh LOW test-t3-$i-$(date +%s) t3-$i; sleep 5; done
5件とも HTTP 200 で返り、ログ上にも5件分のReceived eventとfiredが記録されました。
| 件 | 作成 | 完了 | 状態 |
|---|---|---|---|
| 1 | 08:27:42 | 08:27:57 | COMPLETED |
| 2 | 08:27:46 | 08:28:10 | COMPLETED |
| 3 | 08:27:51 | 08:28:21 | COMPLETED |
| 4 | 08:27:56 | 08:28:31 | COMPLETED |
| 5 | 08:28:01 | （保留のまま開始されず） | PENDING_START → 一定時間後に手動で停止 |
ペイロードが届いた直後にタスクが作成されており、完了はそれぞれ10〜13秒おきでした。
1回の実行時間とほぼ同じ間隔だったので、1件ずつ順番に処理されたものと考えられます。
ただし今回5件目だけは、4回目が終わってから4分程度経過しても「保留中の起動」のまま始まらず、やむなく手動でキャンセルしました。アラートがまとめて届くような環境では、履歴上に「保留中の起動」が残っていないかは見ておいたほうがよさそうです。
なお、本調査は先ほどと同様に5件ともスキップされました。
まとめ的な
イベントトリガは例えば「特定のアラームが発生した際は軽いエージェントを走らたい」場合に活用できそうです。
ただし本調査を止める機能ではないため、今回トリアージ用のスキルと組み合わせて振り分けを実施しました。
- 1回の Webhook で本調査とカスタムエージェントの両方が起動する
- 振り分けはフィルタ（カスタムエージェント側）とスキップ用のスキル（本調査側）の 2ヶ所で設定し、条件分岐を作る
- スキップ判定はモデルが行うので、特に HIGH/CRITICAL など高優先度のアラームが SKIPPED になっていないかを本運用までに確認しておく
- カスタムエージェントには
dataを含む生のペイロードが届く - フィルタに合致しなかった理由は、ログ配信から確認できる
- スキップされた調査は「スキップ解除」で後から調査に回せるので、まずは低優先度のものだけ振り分けるスモールスタート運用がいいかも
完
参考
