Skip to main content

​
Agent Health & Capacity

Svantic monitors two independent signals for every registered agent instance: routing status and connection status. Together they determine whether an agent receives work and how it appears in the dashboard.

​
Routing Status

The routing status determines whether Svantic will send tasks to an agent instance. It is driven by heartbeats and capacity tracking.

​
How It Works

  • Agents send periodic heartbeats to keep their registration alive
  • If an agent stops heartbeating, Svantic marks it as unhealthy and stops routing tasks to it
  • After repeated failures, the agent is automatically deregistered

​
Capacity

Each agent can declare a max_concurrent_sessions limit at registration time:
  • 0 (default): unlimited — the agent accepts as many sessions as it can handle
  • N > 0: Svantic tracks active sessions and stops routing new work once the limit is reached
When an agent hits its capacity limit, it transitions to busy. As sessions close, capacity frees up and the agent becomes available again. Among available agents, Svantic prefers the least-loaded instance.

​
Connection Status

The connection status reflects the health of the transport link between Svantic and the agent. It drives dashboard indicators and observability. Connection status and routing status are independent. An agent can be available for routing while its connection status is briefly degraded — Svantic may still send work because the next dispatch itself acts as a health probe. Conversely, an agent can be online but busy and receive no new work.

​
Observability

Svantic provides two endpoints for monitoring agent health:
  • POST /agents/get_connection — returns the connection state for a specific agent instance
  • POST /agents/get_connection_stats — returns fleet-wide health aggregates, grouped by deployment mode, connection status, and transport type
Both endpoints are account-scoped. The dashboard uses these endpoints to power the agent health panels.

​
Events

Health and lifecycle changes produce real-time events:

​
Deregistration

An agent can be deregistered via POST /agents/deregister. This is a graceful operation:
  1. The instance is removed from the registry
  2. All sessions created by this instance are closed
  3. The instance is unbound from any active sessions
After deregistration, the agent cannot interact with the platform until it re-registers.

​
See Also