Interface IHumanInteractionManager

Interface for the AgentOS Human-in-the-Loop Manager.

The HITL Manager enables structured collaboration between AI agents and human operators, ensuring human oversight for critical decisions while maintaining efficient autonomous operation.

Key capabilities:

  • Approval Requests: Seek human approval for high-risk actions
  • Clarification: Ask humans to resolve ambiguity
  • Output Review: Have humans review and edit agent outputs
  • Escalation: Transfer control when agents are uncertain
  • Checkpoints: Regular human review of ongoing work
  • Feedback Loop: Learn from human corrections

Example

const hitl = new HumanInteractionManager({
  notificationHandler: async (req) => {
    // Send to UI/Slack/email
    await notifyHuman(req);
  },
  defaultTimeoutMs: 300000, // 5 minutes
});

// Register response handler
hitl.onApprovalResponse((decision) => {
  console.log(`Action ${decision.actionId}: ${decision.approved ? 'Approved' : 'Rejected'}`);
});

// Request approval
const decision = await hitl.requestApproval({
  actionId: 'send-mass-email',
  description: 'Send promotional email to 10,000 subscribers',
  severity: 'high',
  context: { recipientCount: 10000, template: 'promo-q4' },
  reversible: false,
});
interface IHumanInteractionManager {
    requestApproval(action): Promise<ApprovalDecision>;
    submitApprovalDecision(decision): Promise<void>;
    requestClarification(request): Promise<ClarificationResponse>;
    submitClarification(response): Promise<void>;
    requestEdit(draft): Promise<EditedOutput>;
    submitEdit(edited): Promise<void>;
    escalate(context): Promise<EscalationDecision>;
    submitEscalationDecision(escalationId, decision): Promise<void>;
    checkpoint(checkpoint): Promise<CheckpointDecision>;
    submitCheckpointDecision(decision): Promise<void>;
    recordFeedback(feedback): Promise<void>;
    getFeedbackHistory(agentId, options?): Promise<HumanFeedback[]>;
    getPendingRequests(): Promise<{
        approvals: PendingAction[];
        clarifications: ClarificationRequest[];
        edits: DraftOutput[];
        escalations: EscalationContext[];
        checkpoints: WorkflowCheckpoint[];
    }>;
    cancelRequest(requestId, reason): Promise<void>;
    getStatistics(): HITLStatistics;
    setNotificationHandler(handler): void;
}

Implemented by

Methods

requestApproval submitApprovalDecision requestClarification submitClarification requestEdit submitEdit escalate submitEscalationDecision checkpoint submitCheckpointDecision recordFeedback getFeedbackHistory getPendingRequests cancelRequest getStatistics setNotificationHandler

Methods

requestApproval

  • requestApproval(action): Promise<ApprovalDecision>

  • Requests human approval before executing an action.

    Parameters

    Returns Promise<ApprovalDecision>

    Human's approval decision

    Example

    const decision = await hitl.requestApproval({
      actionId: 'delete-records',
      description: 'Delete inactive user accounts older than 2 years',
      severity: 'high',
      category: 'data_modification',
      agentId: 'cleanup-agent',
      context: { accountCount: 5000, criteria: 'inactive > 2y' },
      reversible: false,
      potentialConsequences: ['Data loss', 'User complaints'],
    });

submitApprovalDecision

requestClarification

submitClarification

requestEdit

submitEdit

escalate

submitEscalationDecision

checkpoint

submitCheckpointDecision

recordFeedback

getFeedbackHistory

  • getFeedbackHistory(agentId, options?): Promise<HumanFeedback[]>

  • Gets feedback history for an agent.

    Parameters

    • agentId: string

      Agent identifier

    • Optional options: {
          limit?: number;
          since?: Date;
          type?: "correction" | "praise" | "guidance" | "preference" | "complaint";
      }

      Query options

      • Optional limit?: number
      • Optional since?: Date
      • Optional type?: "correction" | "praise" | "guidance" | "preference" | "complaint"

    Returns Promise<HumanFeedback[]>

    Feedback history

getPendingRequests

cancelRequest

  • cancelRequest(requestId, reason): Promise<void>

  • Cancels a pending request.

    Parameters

    • requestId: string

      Request identifier

    • reason: string

      Cancellation reason

    Returns Promise<void>

getStatistics

setNotificationHandler

Settings

Member Visibility

Theme

On This Page

requestApprovalsubmitApprovalDecisionrequestClarificationsubmitClarificationrequestEditsubmitEditescalatesubmitEscalationDecisioncheckpointsubmitCheckpointDecisionrecordFeedbackgetFeedbackHistorygetPendingRequestscancelRequestgetStatisticssetNotificationHandler