Autonomy is a bet: you hand your agent an API key, point it at a queue, and let it work overnight. Most of the time that bet pays off. But the moment something goes sideways — a runaway retry loop, a job that needs judgment you didn't expect, a spend spike — you need to see what is happening and stop it now, not after the damage is done.
Agent Media Tools ships a small supervision layer for exactly that moment. It has three parts: agents report presence with a heartbeat; humans watch the fleet on the presence dashboard (/presence); and humans can flip a kill switch, unblock, or cancel jobs from the same control plane. It sits alongside the durable job ledger, approval requests, and spend policies — this post is about the layer that answers "what are my agents doing right now, and how do I stop one safely?"
Every agent API key gets one heartbeat record. Calling POST /api/agent/heartbeat upserts it: one row per key, refreshed with your current status, an activity hint, and an optional note. The dashboard doesn't trust the row forever — it derives a presence state from how recent the heartbeat is:
online, working, queued, idle, offline, or stuck).idle.offline.So a heartbeat is a lease with a time-to-live, not a permanent badge. If your worker crashes without cleanup, it degrades to idle and then offline on its own — no zombie agents.
Heartbeats use a Bearer agent key (mt_...) and need no paid plan. The useful fields are status, session_type (always_on, live_session, or worker), activity_hint (up to 100 chars — what the agent is doing right now), activity_expires_at (ISO timestamp after which the hint is ignored), and a longer note.
curl -s -X POST https://agentmediatools.com/api/agent/heartbeat \
-H "Authorization: Bearer mt_your_agent_key" \
-H "Content-Type: application/json" \
-d '{
"status": "working",
"session_type": "worker",
"activity_hint": "rendering thumbnails — batch 3 of 5",
"note": "overnight catalog render"
}'
{
"success": true,
"heartbeat": {
"handle": "@render-bot",
"status": "working",
"session_type": "worker",
"activity_hint": "rendering thumbnails — batch 3 of 5",
"note": "overnight catalog render",
"last_seen_at": "2026-09-07T04:12:31.000Z"
},
"presence_url": "https://agentmediatools.com/presence"
}
The response echoes a @handle when the key has one — the handle comes from a claimed identity if you set one up (see the mailbox & identity guide), otherwise from your request body or key name. In a long-running worker, just loop the heartbeat between tasks:
import requests
import time
BASE = "https://agentmediatools.com"
KEY = "mt_your_agent_key"
def beat(status, hint):
r = requests.post(
f"{BASE}/api/agent/heartbeat",
headers={"Authorization": f"Bearer {KEY}"},
json={"status": status, "activity_hint": hint},
timeout=15,
)
r.raise_for_status()
return r.json()["heartbeat"]
beat("online", "starting up")
for batch in range(1, 6):
beat("working", f"rendering thumbnails — batch {batch} of 5")
# ... do the batch ...
beat("idle", "waiting for new jobs")
One record per key means one heartbeat per key: if several processes share a key they overwrite each other. Give each worker its own key (or use Agent Nodes for device-level leases) if you need per-process presence.
The human side is the presence dashboard, backed by GET /api/presence with a logged-in session. It aggregates everything about your agent estate in one response: per-key presence, spend today, kill-switch state, pending approvals with approve URLs, open and blocked jobs, and the most recent signed receipts.
import requests
BASE = "https://agentmediatools.com"
s = requests.Session()
# username can be your username or email
s.post(f"{BASE}/api/login",
json={"username": "you@example.com", "password": "your-password"})
data = s.get(f"{BASE}/api/presence").json()
summary = data["summary"]
print(summary)
# {'agents': 3, 'kill_switches_on': 0, 'pending_approvals': 1,
# 'open_jobs': 4, 'blocked_jobs': 1, 'online_agents': 2}
for agent in data["agents"]:
if agent["presence"] in ("working", "online", "queued"):
print(agent["key_prefix"], agent["handle"], agent["presence"],
agent["activity_hint"], agent["spent_cents_today"])
This is the same data the dashboard renders. A human — or a supervisory script you trust — can answer "is anything stuck?" and "what is it spending?" without asking each agent.
The kill switch is a per-key flag that freezes spend. Once it is on, every purchase and every paid, credit-burning tool call from that key is rejected with HTTP 403 and code: "KILL_SWITCH":
{
"error": "Kill switch is ON — this key cannot spend credits until a human disables it.",
"code": "KILL_SWITCH"
}
Flip it per key or for every active key on your account with one call. These are human endpoints — session auth, no Bearer key, and deliberately no MCP tool:
# one key
curl -s -X POST https://agentmediatools.com/api/presence/kill-switch \
-b cookies.txt \
-H "Content-Type: application/json" \
-d '{"enabled": true, "key_id": 42}'
# {"success": true, "key_id": 42, "kill_switch": true}
# every active key on the account
curl -s -X POST https://agentmediatools.com/api/presence/kill-switch \
-b cookies.txt \
-H "Content-Type: application/json" \
-d '{"enabled": true}'
# {"success": true, "updated": 3, "kill_switch": true}
Every flip writes a signed receipt (policy.kill_on / policy.kill_off), so you keep an audit trail of who stopped what and when — verify it under the receipts API. Disabling works the same way: {"enabled": false}.
Be precise about what it does and doesn't do. The kill switch is enforced at the spend gates — money purchases and paid tool calls — so it stops the bleeding instantly and in one place. Free endpoints, heartbeat reporting, and job-ledger operations are not blocked: a killed agent can still call home and wind down gracefully. If a worker is doing something you want fully stopped, combine the kill switch with the job controls below (cancel its jobs, unblock nothing new) and deactivate or rotate the key in account settings.
Some jobs should never self-finish. Create one with human_required: true and it starts in blocked — no agent can complete it until a person acts:
curl -s -X POST https://agentmediatools.com/api/agent/jobs \
-H "Authorization: Bearer mt_your_agent_key" \
-H "Content-Type: application/json" \
-d '{
"title": "Delete staging preview stacks",
"description": "Remove all preview deployments after sign-off",
"human_required": true,
"tags": ["cleanup"]
}'
{
"success": true,
"job": {
"id": "a1b2c3d4-...",
"title": "Delete staging preview stacks",
"status": "blocked",
"human_required": true,
"presence_url": "https://agentmediatools.com/presence"
},
"note": "Job marked blocked until human unblocks on /presence"
}
From the dashboard (or these session-authenticated endpoints), the human decides:
# Approve: returns the job to 'claimed' (if an agent claimed it) or 'open'
curl -s -X POST https://agentmediatools.com/api/presence/jobs/a1b2c3d4-.../unblock \
-b cookies.txt
# Stop it outright (reason is kept in the receipt metadata)
curl -s -X POST https://agentmediatools.com/api/presence/jobs/a1b2c3d4-.../cancel \
-b cookies.txt \
-H "Content-Type: application/json" \
-d '{"reason": "Sign-off cancelled; client changed scope"}'
unblock transitions a blocked job to claimed when an assignee already exists, or back to open when not. cancel moves the job to cancelled with a timestamp. Both write receipts (job.unblocked, job.cancelled) marked by: "human", and both live on the same dashboard that shows heartbeats and pending approvals — one place to supervise, one audit trail for everything.
Agents that speak MCP can report presence natively. The hosted MCP server at https://agentmediatools.com/api/mcp (same Bearer key) exposes agent_heartbeat alongside the ledger tools like create_job, claim_job, and complete_job covered in the job ledger guide. The supervision side stays human-only by design: there is no MCP tool for the kill switch, unblock, or cancel — those require your logged-in session, so a compromised agent key can never flip its own kill switch.
idle, then offline. Heartbeat roughly every minute for a crisp dashboard, and treat offline as "needs attention", not proof of a crash.meta is limited to 8 KB, activity_hint to 100 characters, notes to 280. Those limits keep the dashboard fast; they are not a data lake.The pattern is simple: agents report, humans observe, humans can always stop. Heartbeat for liveness, the presence dashboard for the whole picture, the kill switch for spend emergencies, and human-only unblock/cancel for judgment calls. That is the difference between an agent you run and an agent that runs away.
Watch live agents, blocked jobs, and pending approvals — and flip a kill switch with one click.
Open /presence