Skip to main content

Interface: IHumanInteractionManager

Defined in: packages/agentos/src/core/hitl/IHumanInteractionManager.ts:413

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,
});

Methods​

cancelRequest()​

cancelRequest(requestId, reason): Promise<void>

Defined in: packages/agentos/src/core/hitl/IHumanInteractionManager.ts:574

Cancels a pending request.

Parameters​

requestId​

string

Request identifier

reason​

string

Cancellation reason

Returns​

Promise<void>

checkpoint()​

checkpoint(checkpoint): Promise<CheckpointDecision>

Defined in: packages/agentos/src/core/hitl/IHumanInteractionManager.ts:515

Creates a checkpoint for human review during long-running tasks.

Parameters​

checkpoint​

WorkflowCheckpoint

The checkpoint state

Returns​

Promise<CheckpointDecision>

Human's checkpoint decision

escalate()​

escalate(context): Promise<EscalationDecision>

Defined in: packages/agentos/src/core/hitl/IHumanInteractionManager.ts:495

Escalates a situation to human control.

Parameters​

context​

EscalationContext

Escalation context

Returns​

Promise<EscalationDecision>

Human's decision on how to proceed

getFeedbackHistory()​

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

Defined in: packages/agentos/src/core/hitl/IHumanInteractionManager.ts:542

Gets feedback history for an agent.

Parameters​

agentId​

string

Agent identifier

options?​

Query options

limit?​

number

since?​

Date

type?​

"preference" | "correction" | "praise" | "guidance" | "complaint"

Returns​

Promise<HumanFeedback[]>

Feedback history

getPendingRequests()​

getPendingRequests(): Promise<{ approvals: PendingAction[]; checkpoints: WorkflowCheckpoint[]; clarifications: ClarificationRequest[]; edits: DraftOutput[]; escalations: EscalationContext[]; }>

Defined in: packages/agentos/src/core/hitl/IHumanInteractionManager.ts:560

Gets all pending requests awaiting human response.

Returns​

Promise<{ approvals: PendingAction[]; checkpoints: WorkflowCheckpoint[]; clarifications: ClarificationRequest[]; edits: DraftOutput[]; escalations: EscalationContext[]; }>

Pending requests by type

getStatistics()​

getStatistics(): HITLStatistics

Defined in: packages/agentos/src/core/hitl/IHumanInteractionManager.ts:585

Gets HITL interaction statistics.

Returns​

HITLStatistics

Current statistics

recordFeedback()​

recordFeedback(feedback): Promise<void>

Defined in: packages/agentos/src/core/hitl/IHumanInteractionManager.ts:533

Records human feedback for agent improvement.

Parameters​

feedback​

HumanFeedback

The feedback to record

Returns​

Promise<void>

requestApproval()​

requestApproval(action): Promise<ApprovalDecision>

Defined in: packages/agentos/src/core/hitl/IHumanInteractionManager.ts:438

Requests human approval before executing an action.

Parameters​

action​

PendingAction

The action requiring approval

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'],
});

requestClarification()​

requestClarification(request): Promise<ClarificationResponse>

Defined in: packages/agentos/src/core/hitl/IHumanInteractionManager.ts:457

Requests clarification from a human for ambiguous situations.

Parameters​

request​

ClarificationRequest

The clarification request

Returns​

Promise<ClarificationResponse>

Human's clarification response

requestEdit()​

requestEdit(draft): Promise<EditedOutput>

Defined in: packages/agentos/src/core/hitl/IHumanInteractionManager.ts:476

Requests human review and potential editing of agent output.

Parameters​

draft​

DraftOutput

The draft output to review

Returns​

Promise<EditedOutput>

Edited output (may be unchanged)

setNotificationHandler()​

setNotificationHandler(handler): void

Defined in: packages/agentos/src/core/hitl/IHumanInteractionManager.ts:592

Sets the notification handler for outgoing requests.

Parameters​

handler​

HITLNotificationHandler

Handler function

Returns​

void

submitApprovalDecision()​

submitApprovalDecision(decision): Promise<void>

Defined in: packages/agentos/src/core/hitl/IHumanInteractionManager.ts:445

Submits an approval decision (typically called by UI/webhook handler).

Parameters​

decision​

ApprovalDecision

The approval decision

Returns​

Promise<void>

submitCheckpointDecision()​

submitCheckpointDecision(decision): Promise<void>

Defined in: packages/agentos/src/core/hitl/IHumanInteractionManager.ts:522

Submits a checkpoint decision.

Parameters​

decision​

CheckpointDecision

The checkpoint decision

Returns​

Promise<void>

submitClarification()​

submitClarification(response): Promise<void>

Defined in: packages/agentos/src/core/hitl/IHumanInteractionManager.ts:464

Submits a clarification response.

Parameters​

response​

ClarificationResponse

The clarification response

Returns​

Promise<void>

submitEdit()​

submitEdit(edited): Promise<void>

Defined in: packages/agentos/src/core/hitl/IHumanInteractionManager.ts:483

Submits an edited output.

Parameters​

edited​

EditedOutput

The edited output

Returns​

Promise<void>

submitEscalationDecision()​

submitEscalationDecision(escalationId, decision): Promise<void>

Defined in: packages/agentos/src/core/hitl/IHumanInteractionManager.ts:503

Submits an escalation decision.

Parameters​

escalationId​

string

The escalation identifier

decision​

EscalationDecision

The human's decision

Returns​

Promise<void>