Did my AI agent crash, or did it shut down?

Rius shows on the Agents page whether each agent process sent its final heartbeat before it ended, which separates a normal shutdown from a process that disappeared. An instance marked stopped exited and sent that final heartbeat. An instance marked gone stopped sending heartbeats without one, which usually points to a crash, an out-of-memory kill, or a deploy that sent SIGTERM. Status is computed by Rius from the last heartbeat, so you never set it yourself.

How it works

Every process that runs the Rius SDK with heartbeats sends one at a regular interval. Rius lists each process as one Instance on the Agents page, with a fresh instance ID per process start. Three replicas of one agent show as three instances under one name. For the wider picture of watching agents, see Monitor AI agents in production.

The status of each instance comes from its heartbeats:

The SDKs send the final heartbeat on a normal exit and when you call shutdown(). An instance ends as gone when the process is killed (SIGTERM from a deploy, SIGKILL, an out-of-memory kill) or exits with process.exit() or os._exit(). So gone tells you the process ended without saying goodbye. It does not tell you why. A deliberate hard exit looks the same as a crash.

The Lifecycle events section of the agent page lists when each instance started, finished, went quiet, or came back in the selected window, newest first. It stays empty for agents without heartbeats.

Set it up

1. Heartbeats are on by default in the Python SDK since 0.10.0 and the TypeScript SDK since 0.2.0, so an agent that follows the quickstart already reports instances. They need credentials: an API key, or an Authorization entry in the client’s headers. A client without credentials sends no heartbeats.

2. Give the agent a name you will recognise, then call shutdown() when your code is done. This sends the final stopped heartbeat.

   import rius
    
   client = rius.init(
       api_key="ri_...",
       service_name="checkout-agent",
       agent_name="checkout-agent",
       heartbeat_interval=15,
   )
    
   # ... run your agent ...
    
   client.shutdown()  # sends the final `stopped` heartbeat

3. In TypeScript, Node sends the final heartbeat when the event loop empties. process.exit() and signals skip that, so call await client.shutdown() first.

   import { init } from '@glassflow-ai/rius'
    
   const client = init({
     apiKey: 'ri_...',
     serviceName: 'checkout-agent',
     agentName: 'checkout-agent',
   })
    
   // ... run your agent ...
    
   await client.shutdown() // sends the final `stopped` heartbeat

4. If your deploys stop the process with SIGTERM, call shutdown() from your own signal handler. The SDK installs no signal handlers, so without yours every deploy ends as gone.

5. Keep heartbeat_interval (or RIUS_HEARTBEAT_INTERVAL) at 15 seconds or below. It accepts 5 to 300, but Rius fixes stale at 30s and gone at 60s, so a longer interval makes a live instance show as stale between heartbeats.

6. Verify in one minute. Start your agent, open Agents, and check that it has an instance in running or ready. Let the process exit and it moves to stopped. If it goes to stale and then gone, the process ended before it could send its final heartbeat.

What you get

• A clear split on the Instances list between processes that shut down with a final heartbeat (stopped) and processes that stopped reporting without one (gone).
• A gone instance stays visible for a week after its last heartbeat, long enough to investigate. Records age out after that.
• A frozen? state under Recent traces for a run that is still open on an instance that has gone stale.
• Lifecycle events that show when an instance started, finished, went quiet, or came back.
• The same data for an agent that queries Rius itself, through the MCP tools list_agents and agent_lifecycle_events.

Heartbeats show whether a process is alive, not whether the agent is making progress. A hung process that still sends heartbeats shows as running.

When something else fits

• If you need to know why a process died, look at your own process logs, deploy events or container exit codes. gone tells you only that no final heartbeat arrived.
• If an agent looks alive but produces nothing, check its open traces and failed traces on the same agent page, because heartbeats cannot show a hung process.

Related