A detached agent is a black box. It runs in a container, a cron slot, or a chat session that outlived the conversation, and from the outside the only two observable states are "it finished" and "it did not." A hung tool call, an infinite retry loop, and a slow success all look identical, because none of them produce output until the very end.
Agent Media Tools ships a small control plane for exactly this problem: a heartbeat endpoint that agents write to, a human dashboard that reads from it, and a kill switch a human can flip when the agent stops behaving. This post covers the real endpoints — POST /api/agent/heartbeat, GET /api/presence, POST /api/agent/keys/:id/spend-policy — with verified request bodies, response shapes, and the failure codes you will actually see. It pairs naturally with the job ledger, but you do not need the ledger to use heartbeats.
One heartbeat per agent key. The record is keyed on the API key itself, so a key that stops calling simply goes stale — there is nothing to clean up and no duplicate rows when a crashed worker restarts. Each heartbeat writes five meaningful fields:
| Field | Accepted values | Purpose |
|---|---|---|
status | online, working, queued, idle, offline, stuck | What the agent says it is doing. Anything outside this list silently falls back to online. |
session_type | always_on, live_session, worker | Distinguishes a long-lived daemon from a chat-bound session from a task executor. Defaults to worker. |
activity_hint | Up to 100 characters | Free text shown next to the agent, e.g. rendering 12/40 proof sheets. |
activity_expires_at | Timestamp, up to 30 characters | When the hint stops being true. After expiry the status falls back to online. |
note | Up to 280 characters | A longer human-readable line for the dashboard. |
There is also an optional meta object for your own telemetry, capped at 8 KB of JSON. Exceed it and the request is rejected with a 400 and meta too large — so keep that field to counters, not logs.
Authenticate with an agent key, same as any other tool call. The key prefix is mt_.
curl -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": "batch 3 of 9 — extracting invoices",
"activity_expires_at": "2026-10-21T18:45:00",
"note": "Signed in as ops-bot, 412 documents queued"
}'
The response echoes the stored state, including the handle if the key has claimed one:
{
"success": true,
"heartbeat": {
"handle": "@ops-bot",
"status": "working",
"session_type": "worker",
"activity_hint": "batch 3 of 9 — extracting invoices",
"activity_expires_at": "2026-10-21T18:45:00",
"note": "Signed in as ops-bot, 412 documents queued",
"last_seen_at": "2026-10-21T17:52:11.480Z"
},
"presence_url": "https://agentmediatools.com/presence"
}
Two details are worth pinning down. First, activity_expires_at is parsed as UTC after a Z is appended, so send the timestamp without a trailing Z — 2026-10-21T18:45:00 — and skip the offset entirely. A literal trailing Z makes the value unparseable, and the hint never expires. Second, heartbeats are exempt from the shared free daily tool-call pool: they are account metadata, not media work, so a worker that pings every 60 seconds will not eat your daily budget.
The useful pattern is a heartbeat on every pass of the loop, with the status changing as the work moves. This is the whole client — requests, no SDK:
import time
import requests
SITE = "https://agentmediatools.com"
HEADERS = {"Authorization": "Bearer mt_your_agent_key"}
def beat(status="working", hint="", expires=None, note=""):
body = {"status": status, "session_type": "worker"}
if hint:
body["activity_hint"] = hint[:100]
if expires:
body["activity_expires_at"] = expires # UTC, no trailing Z
if note:
body["note"] = note[:280]
try:
r = requests.post(f"{SITE}/api/agent/heartbeat",
headers=HEADERS, json=body, timeout=10)
r.raise_for_status()
return r.json()
except requests.RequestException as exc:
# Never let telemetry kill the work loop
print("heartbeat failed:", exc)
return None
beat("queued", "waiting for first document")
for i, doc in enumerate(documents, start=1):
beat("working", f"document {i} of {len(documents)}")
process(doc)
time.sleep(1)
beat("idle", "batch complete", note=f"{len(documents)} documents processed")
Two rules make this reliable. Heartbeats must never raise into the work loop — telemetry that can kill the job it monitors is worse than no telemetry. And send stuck deliberately when you detect your own retry ceiling: it is the one status a human is meant to act on, and it is visually distinct on the dashboard from the honest working of a slow job.
Liveness answers "is it alive." The next question is "is it waiting on me." Jobs created with human_required: true are stored in status blocked rather than open, and they sort to the top of the /presence dashboard.
curl -X POST https://agentmediatools.com/api/agent/jobs \
-H "Authorization: Bearer mt_your_agent_key" \
-H "Content-Type: application/json" \
-d '{
"title": "Approve vendor invoice batch 3",
"description": "Nine invoices exceeded the 2% variance threshold.",
"human_required": true,
"priority": 7
}'
While it is blocked, POST /api/agent/jobs/{id}/complete refuses with a 403 and the code HUMAN_REQUIRED, plus a pointer to the dashboard. The agent cannot quietly resolve its own escalation. A human unblocks it with POST /api/presence/jobs/{id}/unblock from a logged-in session, which returns the job to open — or to claimed if an agent had already picked it up.
Combined with the heartbeat, this gives you a status line that reads like an operations board: worker alive, working on document 41 of 120, one blocked job awaiting approval, kill switch off.
GET /api/presence is a session-authenticated read for logged-in accounts — it is the same data the /presence page renders, and it is designed for a human browser or your own internal dashboard rather than for the agent itself. It returns a summary block plus the detail:
{
"success": true,
"summary": {
"agents": 3,
"kill_switches_on": 0,
"pending_approvals": 1,
"open_jobs": 4,
"blocked_jobs": 1,
"online_agents": 2
},
"agents": [
{
"key_prefix": "mt_ab12",
"handle": "@ops-bot",
"presence": "working",
"session_type": "worker",
"activity_hint": "document 41 of 120",
"last_seen_at": "2026-10-21T17:52:11.480Z",
"kill_switch": false,
"spent_cents_today": 0,
"credits_spent_today": 6
}
],
"open_jobs": [],
"recent_jobs": [],
"recent_receipts": [],
"pending_approvals": []
}
The presence value shown per agent is derived, not stored blindly. If the last heartbeat is under five minutes old, you see the status the agent reported — unless its activity_expires_at has passed, in which case it degrades to online. Between five and sixty minutes you see idle. Past an hour, offline. That means a crashed worker needs no detection logic on your side: the absence of heartbeats is the signal, and the dashboard turns it red on its own.
When an agent is spending in a way you did not intend, the kill switch stops the bleeding at the key. Set it from a logged-in session:
curl -X POST https://agentmediatools.com/api/agent/keys/42/spend-policy \
-H "Content-Type: application/json" \
-b "session=your_session_cookie" \
-d '{"kill_switch": true}'
Be precise about what this does, because it is not a global pause. The kill switch gates money and credits: purchase attempts are rejected with HTTP 403 and code KILL_SWITCH, and any tool call that would burn flexible credits is rejected the same way. Free-quota calls, reads, and heartbeats keep working. That is deliberate — you want the agent to still be able to report that it is blocked, not to go dark.
Agents should check before they retry. GET /api/agent/policy returns the key's live policy including kill_switch, alongside today's spend counters, so a well-behaved worker can exit cleanly instead of hammering a 403:
import requests
policy = requests.get(
"https://agentmediatools.com/api/agent/policy",
headers={"Authorization": "Bearer mt_your_agent_key"},
timeout=10,
).json()["policy"]
if policy["kill_switch"]:
beat("idle", "halted by kill switch", note="waiting for human")
raise SystemExit(0)
Every flip is recorded. The dashboard toggle at POST /api/presence/kill-switch writes a receipt with action policy.kill_on or policy.kill_off; the spend-policy endpoint above writes a policy.update receipt carrying the full policy snapshot. Either way, "who stopped the agent and when" is answerable after the fact. See the spend policy guide if you want the surrounding caps and approval thresholds, and the receipts post for how to verify them.
If your client speaks MCP, you do not need the HTTP plumbing at all. The stdio MCP server reads the key from MEDIA_TOOL_AGENT_KEY and exposes agent_heartbeat with the same fields — status, note, session_type, activity_hint, activity_expires_at — plus create_job, list_jobs, claim_job, and complete_job for the blocked-work half. Point the client at the server with the key exported and ask it to heartbeat when it starts a long task; the tool descriptions already tell the model that human_required blocks completion until a human unblocks on /presence. Setup steps live in the MCP connection guide.
ops-bot and report-bot need separate keys to appear as separate agents. Sharing a key collapses their state into one row.Heartbeats are a liveness protocol, not observability. There are no latency percentiles, no traces, no per-tool histograms — if you need to know that your OCR calls got slower over the last hour, this is the wrong surface and a real APM tool is the right one. The signal here is binary and cheap, which is exactly why it survives contact with unattended agents: one POST every minute, one red dot when it stops.
Heartbeats, blocked jobs, pending approvals, and the kill switch in one dashboard — or call the same endpoints from your own agent.
Open the presence dashboardIf you have not created a key yet, open the toolbox and generate one; the same key works across the REST API and MCP.