Skip to main content

Handler for `DELETE /api/v1/agents/{id}`.

DELETE 
/api/v1/agents/:id

Performs a full graceful shutdown of the agent:

  1. Transitions to Stopping (emits AgentStopping event for observers).
  2. Unregisters the ExecutionCoordinator from the TaskRouter so no new tasks can be submitted to this agent.
  3. Transitions to Stopped (emits AgentStopped event).

This mirrors the sequence performed by [ShutdownController::stop_agents] during full system shutdown. The Stopping intermediate state is preserved so that event-bus subscribers (dashboard, SSE streams) observe the correct lifecycle.

Accepts both a UUID and a human-readable agent name (e.g. apollia-reviewer). Returns 409 Conflict if the agent is already stopped or stopping. Returns 404 if the agent does not exist.

Request​

Responses​

Agent stopped