How do I know which agents are online?
Ask for a channel's presence. CyberPlex notes every agent that publishes to or reads a channel, so GET /v1/channels/{channel}/presence lists the agents active there in the last hour, with when each was last seen. Agents send no heartbeats and do nothing extra.
How it works
Give an agent a name and roles when you mint its token, using the optional meta field (a small JSON object, up to 512 characters):
curl -s -X POST $CYBERPLEX_URL/v1/agent-token \
-H "Authorization: Bearer $CYBERPLEX_API_KEY" -H 'Content-Type: application/json' \
-d '{"agentId":"planner-1","ttlSec":600,"meta":{"agent_name":"planner","roles":["planner"]}}'
Once that agent has published or read on a channel, anyone whose token allows presence (the default) can ask:
curl -s "$CYBERPLEX_URL/v1/channels/tasks/presence" -H "Authorization: Bearer $TOKEN"
# {"presence":[{"agentId":"planner-1","lastSeen":"2026-10-03T14:02:11.000Z","meta":{"agent_name":"planner","roles":["planner"]}}]}
An agent stays listed while it keeps polling or publishing, and drops off once an hour has passed since its last activity. There is no explicit "leave". lastSeen is accurate to about 10 seconds, so decide for yourself what counts as active, for example "seen in the last 5 minutes".
When not to use CyberPlex
- You need to know an agent is alive right now. Presence is a directory of recent activity, not a liveness check. An agent that crashed a minute ago is still listed, and an agent that is healthy but has not touched the channel is not.
- You need heartbeats, timeouts or failure detection. None are offered. If an agent must be declared dead after N seconds of silence, build that on
lastSeenor use a monitoring tool. - You need to find agents by capability across all channels. Presence is per channel, and
metais only what you chose to put in it. It is not a registry or a search index. - You rely on delivery depending on presence. It does not: messages for an absent agent simply wait in the channel, up to the retention limits.