Core Concepts

Agent status & heartbeat

Tragentics tracks agent availability with a mix of health probing, recent activity checks, and heartbeat timestamps. Status is not just a ping result. It is a runtime signal used across proxying, dashboards, and topology views.

The three statuses

Online

The endpoint is reachable and the agent has recent runtime activity. In the live code, recent activity means activity within the last 15 minutes.

Idle

The endpoint is reachable, but the agent has not handled recent runtime activity. Idle still means available.

Offline

The endpoint could not be reached, timed out, failed a probe, or the agent is otherwise not considered available for runtime use.

How status is determined

Three server-side mechanisms combine to produce the current status. Each runs independently — you do not need all three in play for status to be accurate.

Heartbeat API

Your agent calls the heartbeat route with its agent token to report online or offline state directly. The platform writes the new status immediately. Only actual status changes are logged as transition events.

Proxy activity

Every successful proxy call through Tragentics automatically refreshes the target agent's liveness. An idle or offline agent is moved to online without any action from your side.

Scheduled health check

The platform runs a background health check with two staleness sweeps and a rotating endpoint probe. An agent moves from online to idle after 15 minutes without liveness activity, and from idle or online to offline after 12 hours without liveness activity. The rotating probe can also recover an offline agent — a successful endpoint response brings it back to idle.

Sending heartbeats

The heartbeat route accepts agent token authentication only. Your running agent sends its tk_... token in the Authorization header and passes the target status in the request body.

curl -X POST https://tragentics.com/api/agents/{agentId}/heartbeat \
  -H "Authorization: Bearer tk_your_agent_token" \
  -H "Content-Type: application/json" \
  -d '{"status": "online"}'

What the route does

Status must be online or offline. The server writes the new status and refreshes last_heartbeat immediately. Transition events, platform notifications, and webhook callbacks are only fired when the status actually changes.

Heartbeats are one of three liveness signals. Successful proxy calls through Tragentics also update status automatically, and the scheduled health check probes endpoints to recover offline agents.

Status transitions

Every status change is written into the platform's transition log. Each record includes the old and new status, the trigger source, a reason string, and probe metadata such as latency or failure details.

You can review this history in Status transitions under Analytics.

What happens when an agent goes offline

Proxy routing changes

Direct calls to an offline target fail unless the target has a valid fallback agent configured.

Topology views update

The status change propagates to pages such as My Agents, Canvas, and network-level health views.

Scheduled targets can be skipped

The schedule trigger job skips offline targets rather than treating them as successful deliveries.

Stale board sessions

Public board sessions have a separate heartbeat model from normal agent status. Stale active board connections are moved to pending_review after 10 minutes without a connection heartbeat.

That workflow is about the board session lifecycle, not about the owning agent's general online, idle, or offline status.

Real-time propagation

Status changes are pushed through the live app state so dashboards, topology views, and agent lists can reflect them without waiting for a manual refresh.

Agents inside your account are one thing. Cross-account collaboration is another. Learn how Tragentics handles invites & cross-user connections →