Skip to main content

​
Overview

The Agent Control endpoints allow you to start, stop, approve actions, and retrieve the state of the Sentinel AI autonomous monitoring agent. The agent operates in cycles, monitoring services, diagnosing issues, and executing remediation actions.

​
Agent Lifecycle

The agent can be in one of the following states:
  • idle: Not currently running
  • running: Actively executing a monitoring cycle
  • waiting: Paused and waiting for human approval
  • error: Encountered a critical error

​
Run Agent

curl -X POST http://localhost:8000/agent/run
Starts the autonomous agent in the background. The agent will begin monitoring services and executing its analysis cycle. Endpoint: POST /agent/run

​
Response

​
status
string
Operation status - will be “started”
​
message
string
Human-readable confirmation message
{
  "status": "started",
  "message": "Agent execution triggered"
}

​
Error Responses

409 Conflict - Agent is already running: 
{
  "detail": "Agent is already running"
}
The agent runs as a background task. Use the Get Agent State endpoint to monitor progress.

​
Stop Agent

curl -X POST http://localhost:8000/agent/stop
Sends a stop signal to the running agent. The agent will complete its current step and then transition to idle state. Endpoint: POST /agent/stop

​
Response

​
status
string
Operation status - will be “stopping”
​
message
string
Human-readable confirmation message
{
  "status": "stopping",
  "message": "Stop signal sent to agent"
}

​
Error Responses

400 Bad Request - Agent is not running: 
{
  "detail": "Agent is not running"
}
The stop operation is graceful. The agent will complete its current operation before stopping.

​
Approve Agent Action

curl -X POST "http://localhost:8000/agent/approve?action=approve"
When the agent status is waiting, this endpoint allows you to approve or reject a proposed action. The agent will then resume execution based on your decision. Endpoint: POST /agent/approve

​
Query Parameters

​
action
string
required
The approval decision. Must be either "approve" or "reject"

​
Response

​
status
string
Operation status - will be “resuming”
​
message
string
Confirmation message indicating whether the action was approved or rejected
{
  "status": "resuming",
  "message": "Aprobacion recibida. Reanudando..."
}

​
Error Responses

400 Bad Request - Agent is not waiting for approval: 
{
  "detail": "Agent is not waiting for approval"
}
400 Bad Request - Invalid action value: 
{
  "detail": "Invalid action"
}
This endpoint is only valid when the agent state is waiting. Check the agent state before calling this endpoint.

​
Get Agent State

curl http://localhost:8000/agent/state
Retrieves the complete current state of the agent, including status, execution details, and diagnostic information. Endpoint: GET /agent/state

​
Response

The response contains the full agent state object:
​
status
string
Current agent status: "idle", "running", "waiting", or "error"
​
last_run
string | null
ISO 8601 timestamp of the last agent execution, or null if never run
​
current_step
string | null
The current step in the agent’s execution flow (e.g., "monitor", "diagnose", "remediate")
​
stop_requested
boolean
Whether a stop request has been issued
​
logs
array
Array of log entries from the current execution
​
current_error
string | null
Description of the current error being handled, if any
​
affected_service
string | null
Name of the service currently being analyzed or remediated
​
retry_count
integer
Number of retry attempts for the current operation
​
diagnosis_log
array
Log of diagnostic steps performed during the current cycle
​
security_flags
array
Security-related flags or warnings identified during monitoring
​
approval_status
string
Approval status: "WAITING_APPROVAL", "APPROVED", or "REJECTED"

​
Example Response

{
  "status": "running",
  "last_run": "2026-03-09T14:30:00.123456",
  "current_step": "diagnose",
  "stop_requested": false,
  "logs": [],
  "current_error": "Service postgresql is not responding",
  "affected_service": "postgresql",
  "retry_count": 0,
  "diagnosis_log": [
    "Checked service status",
    "Analyzed system logs",
    "Identified connection timeout issue"
  ],
  "security_flags": [],
  "approval_status": null
}

​
Memory Endpoint

curl http://localhost:8000/memory
Retrieves the agent’s episodic memory, containing historical records of monitoring cycles and remediation actions. Endpoint: GET /memory

​
Response

Returns an array of memory episodes. Each episode represents a complete monitoring and remediation cycle. 
[
  {
    "timestamp": "2026-03-09T14:00:00",
    "service": "postgresql",
    "issue": "Service not responding",
    "actions_taken": ["Restarted service"],
    "outcome": "Resolved"
  }
]
The exact structure of memory episodes depends on the agent’s memory implementation.

Build docs developers (and LLMs) love

Get started for freeTalk to us