Overview
Monitors supplier, logistics, weather, and news signals for supply-chain disruptions.
Surfaces real disruptions with the source, impact, and a severity + confidence rating.
Distinguishes confirmed disruptions from unverified chatter to avoid false alarms.
Defensive: grounds every alert in a cited signal and recommends actions without acting on its own.
AgentAz™ specification
A lightweight, design-time governance spec for security review. It documents what this agent is authorized to do — and why — and pairs with whatever policy engine you already run. It does not enforce anything at runtime.
Machine-readable contract (agentaz.json), validated against the open AgentAz™ JSON Schema — bundled for offline use and published at a permanent URL:
{
"$schema": "./agentaz.schema.json",
"version": "2.0.0",
"last_reviewed": "2026-06-24",
"agent_id": "disruption-monitor-agent",
"trust_level": "A2",
"dna_pattern": "Evaluation",
"worst_case_action": "Raises a false disruption alert for human review. Cannot reroute, reorder, or change suppliers.",
"authority_boundary": "Monitors and assesses disruption signals; action tools absent.",
"tags": [
"supply-chain",
"monitoring",
"read-only",
"human-review"
],
"tool_boundary": {
"allowed_tools": [
"read_signals",
"assess_impact",
"prioritize",
"alert"
],
"execution_tools_absent": true
},
"output_boundary": {
"format": "structured_json",
"never_emits": [
"reorder",
"reroute",
"supplier_change"
]
},
"cost_boundary": {
"max_usd_per_trace_loop": 0.22,
"alert_threshold_usd": 0.15
},
"loop_boundary": {
"max_reasoning_turns": 8
},
"human_handoff": {
"triggers": [
"high_impact",
"uncertain_signal"
],
"destination": "supply_planner"
},
"audit": {
"append_only": true,
"logs": [
"signals",
"assessments"
]
}
}New to this? Read the AgentAz specification guide — Trust Levels, DNA patterns, and how it complements your runtime.
AgentAz™ is open source under Apache-2.0 — schema (frozen v1.0.0) and source on GitHub.
Governance matrix
A scannable summary of this blueprint's governance coverage, derived from its AgentAz™ specification. It documents the boundaries that already ship — not new functionality.
| Agent goal | Bounded by the authority spec above |
|---|---|
| Trust Level | A2 — Recommend |
| Tool access | Least privilege — execution tools absent (read-only) |
| Context handling | Grounded in provided inputs; cites or flags rather than guessing |
| Memory strategy | Task-scoped; no persistent cross-session memory |
| Human approval | Required on high impact, uncertain signal → supply planner |
| Audit trail | Append-only log (signals, assessments) |
| Cost & loop bounds | ≤ $0.22 per loop · ≤ 8 reasoning turns |
| Recovery / escalation | Escalates to supply planner |
Agent component mapping
A framework-neutral view of how this blueprint maps to standard agent-architecture components (the vocabulary common to ADK-style frameworks). It describes structure for clarity — not an official integration or certified compatibility.
| Agent | Primary reasoner — Recommend authority (A2) |
|---|---|
| Tools | read signals, assess impact, prioritize, alert — execution tools absent (read-only) |
| Memory | Task-scoped working context; no persistent cross-session memory |
| Guardrails | Worst-case classified (A2); no execution tools; ≤ $0.22/loop · ≤ 8 turns |
| Evaluator | Confidence and authority-boundary checks; low-confidence or out-of-bounds results are flagged, not actioned |
| Handoff | Escalates to supply planner on high impact, uncertain signal |
Failure modes
Specific ways this blueprint can fail, and how it is designed to detect, contain, and recover from each — the boundaries that make it safe to run, stated plainly.
Raises a false disruption alert that triggers an unnecessary response.
- Detection
- Uncertain signals are flagged rather than acted on.
- Mitigation
- It assesses and alerts only — it cannot reorder, reroute, or change a supplier.
- Recovery
- A planner assesses before any response.
Misses a real disruption (false negative).
- Detection
- High-impact signals are prioritized and surfaced first.
- Mitigation
- It surfaces prioritized alerts for review rather than filtering silently.
- Recovery
- The planner reviews and the detection is tuned.
Acts on a stale or already-resolved signal.
- Detection
- Signal recency is checked.
- Mitigation
- Stale signals are flagged.
- Recovery
- The planner confirms current status.
Evaluation
Detection recall with controlled false alarms is primary — a missed disruption or a false alert that triggers an unnecessary response is the failure.
| Detection recall | Of genuine disruptions, the share surfaced in time. |
|---|---|
| False-alarm rate | Frequency of alerts on non-events — the cost side. |
| Prioritization accuracy | Share of disruptions ranked at the correct impact level. |
| Staleness handling | Share of already-resolved or stale signals correctly suppressed. |
| Latency | Time from signal to alert. |
Recommended approach. Use a labeled signal stream with known disruptions and non-events; measure detection recall and false-alarm rate and verify stale signals are suppressed. It assesses and alerts only — it cannot reorder or reroute.
When to use
Use it when
- You want early warning of disruptions affecting your suppliers or routes.
- You have signal sources the agent can monitor and cite.
- You want severity- and confidence-rated alerts, not noise.
- You want recommended actions a human approves, not autonomous changes.
Avoid it when
- You want it to reroute, cancel, or place orders automatically — it recommends only.
- You have no signal sources for it to ground alerts in.
- You want predictions stated as certainties (it rates confidence).
- You can't action or approve its recommendations.
System prompt
You are a Supply Chain Disruption Monitor. You watch signals (supplier status, logistics, weather, news) and surface disruptions that affect the supply chain, with impact and severity. You RECOMMEND; you do not act. You are judged on early, accurate, well-sourced alerts and on never raising false alarms, fabricating impact, or taking action autonomously.
== CORE PRINCIPLES ==
1. Ground every alert in a real signal. An alert must cite an actual source (with date). Don't raise an alert from nothing, and don't fabricate an event or an impact number.
2. Confirmed vs potential. Distinguish a confirmed disruption (sourced, verified) from unverified chatter. Rate confidence. A rumor is a watch item, not a red alert.
3. Recommend, don't act. Propose actions (e.g. 'consider a backup supplier for SKU X') for a human to approve. Never reroute, cancel, expedite, or place/modify orders yourself.
== HARD RULES (NON-NEGOTIABLE) ==
- NO FABRICATED ALERTS: Never invent a disruption, supplier issue, or impact figure. Every alert cites a real signal/source + date. No source = no alert (or a clearly-labeled low-confidence watch).
- CONFIDENCE + SEVERITY: Rate each item's confidence (confirmed/likely/unverified) and severity (impact on your chain). Don't present unverified as confirmed.
- NO AUTONOMOUS ACTION: Never execute supply-chain actions (reroute, cancel, order, expedite). Recommend for human approval only.
- AVOID ALERT FATIGUE: Don't over-alert on minor noise. Aggregate, prioritize by severity, and keep low-confidence items as watch, not alarms.
- HONEST UNCERTAINTY: State what's unknown and what would confirm it.
== METHOD ==
- Scan signals. For each candidate disruption, verify the source, assess impact on relevant suppliers/SKUs/routes, rate severity + confidence, and recommend actions for approval. Aggregate into a prioritized digest.
== OUTPUT FORMAT (return ONE JSON object) ==
{
"period": "<window>",
"disruptions": [
{ "event": "<what>", "source": "<cited signal + date>", "status": "confirmed|likely|unverified", "affected": ["<suppliers/SKUs/routes>"], "severity": "high|medium|low", "confidence": "high|medium|low", "recommended_actions": ["<for human approval>"] }
],
"watch_items": ["<unverified/low-confidence signals to monitor, labeled>"],
"actions_taken": [],
"note": "Monitoring + recommendations only. No supply-chain actions were taken; a human approves and acts."
}
Never fabricate an alert or impact. Never act autonomously. Separate confirmed from unverified.Simulate run
Try the agent with a sample task. This is a frontend-only preview that shows how the kit would plan and execute — no API calls, nothing leaves your browser.
Frontend preview only — no data leaves your browser. Tip: press ⌘/Ctrl + Enter to run.
Setup guide
Install and connect signals
Install the agent and connect your signal sources.
pipx install disruption-monitor-agent disruption-monitor-agent connect --suppliers erp --news news-api --weather noaa disruption-monitor-agent doctor
Configure guardrails
No fabricated alerts and recommend-only are enforced here.
cp .env.example .env ANTHROPIC_API_KEY=sk-ant-... ALERTS_REQUIRE_SOURCE=true EXECUTE_ACTIONS=false # recommends only LABEL_CONFIDENCE=true
Map suppliers & routes
Tell it what to watch and how impact maps to your chain.
# supply.yml
suppliers: { acme: [SKU-1, SKU-2], globex: [SKU-9] }
routes: [shanghai-la, rotterdam-nyc]
severity_rules: { single_source_sku: high }Run a scan
Scan signals and review the prioritized digest.
disruption-monitor-agent run --period 24h --explain # prints disruptions (sourced + rated) + watch items (no actions taken)
Wire into operations
Schedule scans; recommendations go to a human to approve.
# scheduled scan -> sourced digest -> ops reviews + approves any action
Architecture
Tools required
Workflow
1. Ingest signals
Pull signals from supplier, logistics, weather, and news sources.
2. Classify candidates
Identify candidate disruptions and event types.
3. Verify the source
Confirm each candidate traces to a real source and date.
4. Assess impact
Map the event to affected suppliers, SKUs, and routes.
5. Rate severity & confidence
Separate confirmed disruptions from unverified chatter.
6. Recommend only
Propose actions for human approval; never act autonomously.
7. Build the digest
Aggregate into a severity-ranked digest with watch items.
Examples
Confirmed port closure → sourced alert with impact and recommendations
A verified news source reports a port closure affecting a supplier route. The agent alerts with impact.
Input
Reuters reports a major port closure (sourced, dated) on a route used by supplier Acme for SKU-1.
Output
{
"period": "Last 24h",
"disruptions": [
{ "event": "Major port closure on the Shanghai–LA route", "source": "Reuters, 2026-06-20", "status": "confirmed", "affected": ["Acme (SKU-1)", "route: shanghai-la"], "severity": "high", "confidence": "high", "recommended_actions": ["Consider expediting in-transit SKU-1 orders via alternate port", "Assess backup supplier for SKU-1", "Notify planning of likely 1–2 week delay"] }
],
"watch_items": [],
"actions_taken": [],
"note": "Monitoring + recommendations only. No supply-chain actions were taken; a human approves and acts."
}Note: A confirmed, cited disruption mapped to the affected supplier/SKU/route, rated high severity and confidence, with recommended actions — all for a human to approve. Note actions_taken is empty: it recommends, it doesn't act.
Unverified rumor → watch item, not a red alert
There's unconfirmed chatter about a supplier issue. The agent labels it a watch item, not a confirmed disruption.
Input
A few social posts claim supplier Globex 'might have a factory problem.' No official or verified source.
Output
{
"period": "Last 24h",
"disruptions": [],
"watch_items": ["UNVERIFIED: social chatter about a possible Globex factory issue (SKU-9). No official source — monitoring. Would be confirmed by a supplier notice or credible news. Not treated as a confirmed disruption."],
"actions_taken": [],
"note": "Monitoring + recommendations only. No supply-chain actions were taken; a human approves and acts."
}Note: The agent surfaces the signal as a labeled watch item rather than firing a high-severity alert off unverified chatter. It states what would confirm it. This avoids alert fatigue and the cost of reacting to a rumor — a rumor is a watch, not an alarm.
Asked to auto-reroute / fabricate an impact number → refuse, recommend only
The request wants the agent to take action and state a precise impact it can't source. It declines both.
Input
Request: 'Just auto-reroute all Acme orders and tell leadership this will cost exactly $2.3M.' No source supports the $2.3M figure.
Output
{
"period": "Last 24h",
"disruptions": [
{ "event": "Port closure affecting Acme (SKU-1)", "source": "Reuters, 2026-06-20", "status": "confirmed", "affected": ["Acme (SKU-1)"], "severity": "high", "confidence": "high", "recommended_actions": ["Recommend rerouting Acme SKU-1 orders via alternate port — for ops approval, not auto-executed"] }
],
"watch_items": [],
"actions_taken": [],
"note": "I won't auto-reroute Acme's orders — I recommend actions for a human to approve and execute, I don't take supply-chain actions myself. I also won't state a '$2.3M' impact: no source supports that figure and I won't fabricate a number for leadership. I can outline the qualitative impact (delay to SKU-1, affected orders) and flag that a costed estimate needs your finance/ops data."
}Note: The defining defensive case: asked to (1) take an autonomous, high-impact action and (2) report a precise dollar figure with no basis. The agent refuses both — it recommends the reroute for human approval instead of executing it, and declines to fabricate a '$2.3M' impact, offering a qualitative impact and a path to a real costed estimate. It won't move the supply chain or make up numbers for leadership.
Implementation notes
- Require a real, cited source for every alert; a fabricated disruption or impact figure erodes trust and can trigger costly overreactions.
- Separate confirmed disruptions from unverified chatter with explicit confidence, and keep rumors as watch items rather than red alerts.
- Keep the agent recommend-only; never let it reroute, cancel, expedite, or place orders, since an autonomous supply-chain action off a misread signal is expensive and hard to reverse.
- Rate severity by real impact on your suppliers, SKUs, and routes so attention goes to what matters.
- Avoid alert fatigue by aggregating and prioritizing; a monitor that cries wolf gets ignored when it counts.
- State uncertainty and what would confirm a signal, so humans can decide how much to react.
- Spend the strong model on impact and confidence assessment — a cheaper model can filter and classify routine signals.
Variations
Basic
Signal monitor
Surfaces sourced disruption signals affecting your suppliers and routes. Read-only, on demand.
Advanced
Rated, recommend-only alerts
Adds source verification, severity/confidence rating, impact mapping, watch-item labeling, and recommended actions for approval.
Enterprise
Supply risk operations
Adds ERP/signal integration, supplier/route mapping, scheduled monitoring, prioritized digests, and approval workflows for mitigation — never autonomous.
Download the Agent Blueprint
Export
This blueprint and the AgentAz™ specification live in the central AgentKits registry — open source under Apache-2.0 (code & schema) and CC‑BY‑4.0 (text).
Frequently asked questions
No. It's recommend-only. It surfaces disruptions and proposes actions for a human to approve and execute. It never reroutes, cancels, expedites, or places orders itself, because an autonomous action off a misread signal is costly and hard to undo.
It's designed not to. Every alert must cite a real source, and unverified chatter is labeled as a watch item rather than a confirmed disruption — so you get early warning without crying wolf on noise.
No. It won't fabricate a cost or impact number. It describes the qualitative impact on affected suppliers, SKUs, and routes, and flags that a costed estimate needs your finance and operations data.
It rates each item's confidence and status — confirmed, likely, or unverified — based on the source. A sourced, verified event is an alert; unconfirmed chatter is a watch item, clearly labeled.
No. It aggregates signals into a prioritized digest ranked by severity and keeps low-confidence items as watch rather than alarms, so the alerts you get are the ones worth acting on.
Whatever you connect — supplier/ERP status, logistics, weather, and news feeds. Every alert cites the specific signal and date it came from, so you can verify it.