Documentation Index
Fetch the complete documentation index at: https://docs.svantic.com/llms.txt
Use this file to discover all available pages before exploring further.
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.
| Status | Routable? | Meaning |
|---|
available | Yes | Agent is healthy and has capacity |
unknown | Yes | Newly registered, not yet confirmed |
busy | No | Agent has reached its concurrent session limit |
unhealthy | No | Agent has missed heartbeats or failed recent dispatches |
offline | No | Agent has been explicitly marked down |
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.
| Status | Meaning |
|---|
unknown | Newly registered — Svantic hasn’t communicated with this instance yet |
online | Live WebSocket connection is open (connected-mode agents) |
healthy | Recent dispatch succeeded |
degraded | At least one recent dispatch failed, but the agent may still be reachable |
offline | No transport available — the agent is unreachable |
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 instancePOST /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:
| Event | When |
|---|
agent.registered | New instance registered |
agent.connected | WebSocket connection established (connected mode) |
agent.disconnected | WebSocket connection closed (connected mode) |
agent.health_changed | Routing status changed |
agent.deregistered | Instance removed |
Deregistration
An agent can be deregistered via POST /agents/deregister. This is a graceful operation:
- The instance is removed from the registry
- All sessions created by this instance are closed
- The instance is unbound from any active sessions
After deregistration, the agent cannot interact with the platform until it re-registers.
See Also
