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 included with Agent911. It is visibility only — 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-15 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 |
Presence vs. Liveness
FindMyAgent and Watchdog address related but distinct questions:
| Tool | Question Answered |
|---|
| Watchdog | Is this agent alive and making progress? |
| FindMyAgent | Where are my agents, and does my team know? |
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. 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)
Pricing
FindMyAgent is included with Agent911. No separate license required.
Next Steps
