How AutoGPT’s Human Review System Works for Agent Approvals

AutoGPT implements a human-in-the-loop (HITL) mechanism that pauses agent execution whenever a block requires human approval, storing pending decisions in a HumanReview database table and resuming only after explicit user interaction via the frontend or auto-approval records.

AutoGPT’s platform includes a built-in review workflow designed for enterprise governance and safety. The system intercepts agent execution at critical checkpoints—whether within individual workflow blocks or marketplace submissions—forcing a human decision before potentially risky operations proceed.

Triggering a Review Checkpoint

The review process initiates when a block is defined with requires_approval or editable flags, or when a sub-agent is submitted to the marketplace. In autogpt_platform/backend/backend/data/human_review.py, the backend creates a pending review record that stores the execution context including nodeExecId, graphExecId, nodeId, the payload requiring review, optional instructions, and editability flags.

This persistence layer ensures that even if the execution engine restarts, the human decision point remains intact until explicitly resolved.

Database Architecture and Approval Logic

All database operations for reviews reside in autogpt_platform/backend/backend/data/human_review.py. The helper class HITLReviewHelper in autogpt_platform/backend/backend/blocks/helpers/review.py provides the primary interface through its check_approval method:

# autogpt_platform/backend/backend/blocks/helpers/review.py

async def check_approval(
    node_exec_id: str,
    graph_exec_id: str,
    node_id: str,
    input_data: dict | None = None,
) -> Optional[ReviewResult]:
    """
    Returns an existing ReviewResult if the node has already been approved
    (normal or auto‑approval).  Returns ``None`` when a human decision is still required.
    """
    return await get_database_manager_async_client().check_approval(
        node_exec_id=node_exec_id,
        graph_exec_id=graph_exec_id,
        node_id=node_id,
        input_data=input_data,
    )

The system checks for two approval types: standard reviews keyed by nodeExecId, and auto-approval records using the synthetic key pattern auto_approve_{graph_exec_id}_{node_id}.

Frontend Interface for Human Decisions

The pending review list is exposed via the OpenAPI schema defined in autogpt_platform/frontend/src/app/api/openapi.json. The model includes fields such as id, user_id, payload, instructions, editable, status, and timestamps.

The React component PendingReviewsList (autogpt_platform/frontend/src/components/organisms/PendingReviewsList/PendingReviewsList.tsx) polls this endpoint and renders each review with Approve, Reject, and—if editable is true—an Edit textbox. When a user submits a decision, the frontend sends a PATCH request to /api/features/executions/review:

// PendingReviewsList.tsx – snippet that sends the PATCH request
await fetch(`/api/features/executions/review/${review.id}`, {
  method: "PATCH",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    status: "APPROVED",          // or "REJECTED"
    reviewMessage: comment,      // optional
    payload: editedPayload,      // only if the block is editable
  }),
});

Execution Flow and Resumption

The execution engine in autogpt_platform/backend/backend/blocks/human_in_the_loop.py periodically invokes HITLReviewHelper.check_approval to determine whether to proceed. Once the review entry status transitions to APPROVED, the engine retrieves the potentially edited payload and continues graph execution from the paused node.

If the status is REJECTED, the block aborts or follows the rejection branch defined in the workflow, ensuring that unauthorized actions cannot proceed without explicit human consent.

Auto-Approval Mechanism

For trusted workflows, users can enable auto-approval for an entire graph execution. When enabled, the create_auto_approval_record function in human_review.py writes a synthetic review record:

# autogpt_platform/backend/backend/data/human_review.py

async def create_auto_approval_record(
    graph_exec_id: str,
    node_id: str,
    input_data: dict,
) -> HumanReview:
    auto_key = f"auto_approve_{graph_exec_id}_{node_id}"
    return await db.human_review.create(
        data={
            "nodeExecId": auto_key,
            "graphExecId": graph_exec_id,
            "nodeId": node_id,
            "payload": input_data,
            "status": "APPROVED",
            "instructions": "Auto‑approval record",
        }
    )

Subsequent calls to check_approval encounter this pre-approved record and bypass the UI pause, streamlining execution while maintaining auditability.

Marketplace Agent Submissions

Sub-agents submitted to the marketplace follow the same review lifecycle. These submissions are stored as HumanReview-style records and surfaced in the admin UI at autogpt_platform/frontend/src/app/(platform)/admin/marketplace/. Marketplace admins evaluate submissions using the same interface patterns—pending → approve/reject → status update—ensuring that only vetted agents become publicly available.

Notification templates such as agent_rejected.html.jinja2 in autogpt_platform/backend/backend/notifications/templates/ provide email alerts when submissions require changes or are rejected.

Summary

• Review Triggers: Blocks with requires_approval or marketplace submissions create entries in the HumanReview table with execution context and payloads.
• Approval Check: HITLReviewHelper.check_approval in review.py queries for existing approvals or auto-approval records before pausing execution.
• Frontend Interaction: The PendingReviewsList component renders pending decisions and sends PATCH requests to /api/features/executions/review with status updates and optional edited payloads.
• Execution Resumption: The human_in_the_loop.py engine polls for APPROVED status before continuing, or aborts on REJECTED.
• Auto-Approval: Synthetic records with keys matching auto_approve_{graph_exec_id}_{node_id} allow pre-authorized executions to skip manual review.
• Marketplace Integration: Agent submissions use the same infrastructure, with admin interfaces located in the frontend's marketplace admin routes.

Frequently Asked Questions

How does AutoGPT know when to pause an agent for human review?

The system checks for the requires_approval or editable flags on block definitions. When present, the execution engine calls HITLReviewHelper.check_approval before proceeding. If no existing approval record is found—either standard or auto-approval—the engine pauses and creates a pending entry in the HumanReview table.

What happens to the agent execution while waiting for human approval?

Execution remains in a suspended state at the specific node requiring review. The engine periodically polls the database (via check_approval) for status changes. The execution context, including nodeExecId and graphExecId, persists in the database, allowing the workflow to resume exactly where it left off once approval is granted.

Can reviewers modify the payload before approving?

Yes, if the block is configured with editable: true, the PendingReviewsList component renders an edit textbox. Reviewers can modify the payload, and the updated data is sent in the PATCH request body. The execution engine then uses this edited payload when resuming the graph.

How do marketplace agent approvals differ from workflow block reviews?

While both use the HumanReview infrastructure, marketplace submissions are routed to admin interfaces in autogpt_platform/frontend/src/app/(platform)/admin/marketplace/. These submissions follow the same status lifecycle (pending → approved/rejected) but utilize specific notification templates like agent_rejected.html.jinja2 to communicate decisions to developers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}