FindMyAgent
When you’re running multiple agents, the first question is always: “Who’s actually working right now?” FindMyAgent answers that — live presence, heartbeat age, and stall flags for every agent in your fleet.
FindMyAgent is visibility only. It surfaces presence state and flags agents that need attention. It does not control, restart, or modify agents.
Quick Start
# Show all agents and their current presence state
acme findmyagent
# Filter to only agents needing attention
acme findmyagent --filter attention
# Watch mode (refreshes every 15s)
acme findmyagent --watch
Output
FindMyAgent — Fleet Overview
=============================
Last updated: 2026-03-09 15:42:31 UTC
Active Agents (3 total):
● pipeline-agent ACTIVE ████████████ last seen: 8s ago
⚠ support-agent-prod STALLED ████░░░░░░░░ no progress: 4m 17s ← ATTENTION
● indexer-agent ACTIVE ████████████ last seen: 4s ago
○ staging-agent OFFLINE ──────────── not reporting
Summary:
Active: 2 | Stalled: 1 | Offline: 1 | Needs attention: 1
Presence States
| State | Symbol | Meaning |
|---|
ACTIVE | ● | Reporting regular heartbeats; making progress |
STALLED | ⚠ | Heartbeat present but no meaningful progress |
SILENT | ✕ | No heartbeats or activity detected |
OFFLINE | ○ | Not reporting — Sentinel may not be running |
RECOVERING | ↑ | Was stalled; progress has resumed |
What “Needs Attention” Means
An agent is flagged as needs attention when:
- STALLED — No meaningful progress for more than the configured threshold (default: 5 minutes)
- SILENT — No heartbeat received within 2× the expected heartbeat interval
- STALLED + HIGH DETECTION — Sentinel has flagged a high-confidence issue on this agent
Agents in OFFLINE state are shown but not flagged as needing attention — this typically means FindMyAgent can’t see them, not that they’ve failed.
The Heartbeat Progress Bar
The bar beside each agent shows activity density over the last 15 minutes:
████████████ = Continuous activity (healthy)
████░░░░░░░░ = Activity stopped 4+ minutes ago (stalled)
──────────── = No data (offline or not reporting)
Filtering
# Show only stalled agents
acme findmyagent --filter stalled
# Show only agents needing attention
acme findmyagent --filter attention
# Show only offline agents
acme findmyagent --filter offline
# Show a specific agent
acme findmyagent --agent support-agent-prod
Configuring Heartbeat Thresholds
FindMyAgent uses Sentinel’s heartbeat configuration. Adjust thresholds in your Sentinel config:
# ~/.acme/sentinel.yaml
findmyagent:
stall_threshold: 300 # seconds before marking STALLED (default: 300)
offline_threshold: 120 # seconds without heartbeat to mark OFFLINE (default: 120)
attention_severity: medium # minimum Sentinel detection severity for attention flag
FindMyAgent in the Agent911 Surface
FindMyAgent data is embedded directly in the Agent911 snapshot — the “Active Agents” section is powered by FindMyAgent. You don’t need to run them separately.
# FindMyAgent standalone
acme findmyagent
# FindMyAgent via Agent911 snapshot (same data, more context)
acme agent911 snapshot
When to Use FindMyAgent
- Morning check-in: Know the state of your fleet before your day starts
- On-call handoff: Confirm all agents are healthy before handing off
- Post-deploy verification: Confirm new agents registered and are active
- Fleet scaling: Track that newly-spawned agents are checking in correctly
CLI Reference
# Basic fleet overview
acme findmyagent
# Watch mode
acme findmyagent --watch
acme findmyagent --watch --interval 30
# Filtering
acme findmyagent --filter [stalled|active|offline|attention]
acme findmyagent --agent <name>
# Output formats
acme findmyagent --format json
acme findmyagent --format table (default)
Included With Agent911
FindMyAgent is included with Agent911 — no separate license required. If you have Agent911, you have FindMyAgent.
Next Steps
