Action Execution & Escalation
Action Execution & Escalation
The Gova backend implements a human-in-the-loop moderation system. When the AI Review Agent detects a violation based on your configured server guidelines, it does not always act immediately. Instead, it creates an "Action Event" that enters a pending state, allowing moderators to review, approve, or reject the escalation.
Action Workflow
- Detection: The AI evaluates a message and assigns a severity score.
- Suggestion: If the severity meets the criteria, an action (e.g., Timeout) is suggested and set to
AWAITING_APPROVAL. - Review: A human moderator retrieves the pending actions via the API.
- Resolution: The moderator calls the
/approveor/rejectendpoint.
Approving and Executing Actions
Approving an action triggers its immediate execution on the target platform (e.g., Discord). The system validates that the action is currently in the AWAITING_APPROVAL state before proceeding.
Endpoint: POST /actions/{action_id}/approve
Supported Discord Actions
- REPLY: Sends an automated warning or informative message to the user in the channel.
- TIMEOUT: Restricts the user's ability to communicate for a specified duration.
- KICK: Removes the user from the server.
Example Request
POST /actions/550e8400-e29b-41d4-a716-446655440000/approve
Authorization: Bearer <JWT_TOKEN>
Response Model (ActionResponse)
Upon successful execution, the action status updates to COMPLETED.
| Field | Type | Description |
| :--- | :--- | :--- |
| action_id | UUID | Unique identifier for the action. |
| status | String | The new status (e.g., COMPLETED or FAILED). |
| action_type | String | The type of action executed (kick, timeout, reply). |
| executed_at | ISO8601 | Timestamp of when the action was successfully processed. |
| action_params | Object | The specific parameters used (e.g., timeout duration). |
Rejecting Suggested Actions
If a moderator deems an AI suggestion unnecessary or incorrect, they can reject the action. This prevents execution and moves the event to a terminal REJECTED state for auditing purposes.
Endpoint: POST /actions/{action_id}/reject
Example Request
POST /actions/550e8400-e29b-41d4-a716-446655440000/reject
Authorization: Bearer <JWT_TOKEN>
Response
The response returns the updated ActionResponse object with the status set to REJECTED and the updated_at timestamp refreshed.
Action Statuses
Actions transition through the following states within the action_events table:
| Status | Description |
| :--- | :--- |
| AWAITING_APPROVAL | The AI has suggested an action; it is pending human review. |
| COMPLETED | The action was approved and successfully executed on the platform. |
| REJECTED | A human moderator explicitly declined to take the suggested action. |
| FAILED | The action was approved, but the platform execution failed (e.g., missing bot permissions). |
The Review Agent (Internal Logic)
While execution is manual, the suggestion logic is handled by the ReviewAgent. It utilizes a high-context prompt including:
- Server Guidelines: The ruleset the AI is enforcing.
- Channel Summary: Recent conversation history to understand context.
- Severity Score: A float between
0and1indicating the violation strength.
The agent provides a reason for every suggested action, which is visible in the ActionResponse to help moderators make informed decisions during the escalation process.