Oversight

Oversight is the mechanism by which cognitive agents involve humans in their decision-making. When an agent encounters a high-stakes action, low-confidence situation, or policy-required checkpoint, it can pause and request human approval before proceeding.

Why oversight matters

Autonomous agents are powerful, but not all decisions should be fully automated. Common scenarios where human oversight is needed:

• High-stakes actions: Deploying to production, deleting data, sending notifications to customers
• Low-confidence decisions: Agent’s beliefs have low confidence, or the evidence ratio is weak
• Policy requirements: Compliance rules require human approval for certain categories of actions
• Novel situations: The agent has never encountered this combination of conditions before

How oversight works

The HITL (Human-in-the-Loop) flow

Agent BDI Cycle
      │
      ▼
 1. Agent forms intention to act
      │
      ▼
 2. Action requires oversight?  ──No──▶  Execute directly
      │
     Yes
      │
      ▼
 3. Agent emits hitl_request event
    (pauses execution of this action)
      │
      ▼
 4. Human reviews the request
    - Sees: action sort, features, confidence
    - Decides: approve / reject / modify
      │
      ▼
 5. Human provides feedback
      │
      ▼
 6. Agent proceeds (or abandons) based on feedback

Detecting HITL requests via WebSocket

When an agent needs human approval, it emits a hitl_request event through the WebSocket connection:

const subscription = client.cognitive.subscribeToEvents(agentId, {
  onEvent(event) {
    if (event.type === 'hitl_request') {
      console.log('Human review requested:');
      console.log(`  Action: ${event.action_sort}`);
      console.log(`  Confidence: ${event.confidence}`);
      // Present this to a human for review
    }
  },
});

The hitl_request event includes:

Field	Type	Description
action_sort	string	The sort name of the action requiring approval
confidence	number	The agent’s confidence in this action (0.0 to 1.0)
agent_id	string	Which agent is requesting oversight
timestamp	string	When the request was made

Providing human feedback

After reviewing the agent’s request, provide feedback using the feedback endpoint:

const feedback = await client.cognitive.provideFeedback({
  agent_id: agentId,
  result_id: goalId,
  rating: 1,            // +1 approve, 0 neutral, -1 reject
  correction: 'Approved, but lower the scaling factor to 2x instead of 4x',
  preference: 'Always prefer gradual scaling over aggressive scaling',
});

The feedback has three effects:

1. Immediate: The agent proceeds (or abandons) the action based on the rating
2. Learning: The agent may learn new rules from the feedback (feedback.learned_rule_id)
3. Policy: Preferences shape future behavior (feedback.updated_rules)

Detecting impasses

When an agent gets stuck — it can’t proceed and can’t resolve the situation on its own — it emits an impasse_detected event:

subscription = client.cognitive.subscribeToEvents(agentId, {
  onEvent(event) {
    if (event.type === 'impasse_detected') {
      console.log(`Agent stuck on goal: ${event.blocked_goal}`);
      console.log(`Impasse type: ${event.impasse_type}`);
      console.log(`Recovery suggestions: ${event.recovery_suggestions.join(', ')}`);
      // Human needs to intervene — add new beliefs, modify goals, or provide guidance
    }
  },
});

Building an oversight workflow

Here’s a complete pattern for building a human-in-the-loop system:

import { ReasoningLayerClient } from '@kortexya/reasoninglayer';

const client = new ReasoningLayerClient({
  baseUrl: 'https://platform.ovh.reasoninglayer.ai',
  tenantId: 'my-tenant-uuid',
  auth: { mode: 'cookie' },
});

// 1. Create an agent
const agent = await client.cognitive.createAgent({
  name: 'deployment-agent',
  config: {
    belief_confidence_threshold: 0.7,
    enable_learning: true,
    max_goals_per_cycle: 3,
  },
});

// 2. Subscribe to events
const subscription = client.cognitive.subscribeToEvents(agent.agent_id, {
  onEvent(event) {
    switch (event.type) {
      case 'hitl_request':
        // Queue for human review (e.g., send to Slack, dashboard, etc.)
        handleHumanReviewRequest(event);
        break;

      case 'impasse_detected':
        // Alert the team that the agent needs help
        alertTeam(event);
        break;

      case 'goal_completed':
        if (event.success) {
          console.log(`Goal achieved: ${event.goal_id}`);
        } else {
          console.log(`Goal failed: ${event.goal_id}`);
        }
        break;
    }
  },
});

// 3. Run BDI cycles (the agent will emit hitl_request when needed)
const result = await client.cognitive.runCycle({
  agent_id: agent.agent_id,
});

// 4. When the human approves/rejects, provide feedback
async function handleHumanDecision(goalId: string, approved: boolean, note: string) {
  await client.cognitive.provideFeedback({
    agent_id: agent.agent_id,
    result_id: goalId,
    rating: approved ? 1 : -1,
    correction: note,
  });
}

Oversight and agent confidence

The agent’s belief_confidence_threshold configuration controls how certain the agent needs to be before acting autonomously vs. requesting human review:

const agent = await client.cognitive.createAgent({
  name: 'cautious-agent',
  config: {
    // Agent will request human review for any action with confidence below 0.8
    belief_confidence_threshold: 0.8,
  },
});

• High threshold (0.8-0.9): Agent requests human review frequently — safer but slower
• Low threshold (0.3-0.5): Agent acts autonomously more often — faster but riskier
• Threshold of 1.0: Agent always requests review (fully supervised)
• Threshold of 0.0: Agent never requests review (fully autonomous)

Key takeaways

1. Oversight is built into the agent architecture — it’s not an afterthought but a core mechanism
2. HITL requests are real-time events — subscribe via WebSocket to receive them immediately
3. Feedback has lasting effects — the agent learns from human corrections and adjusts future behavior
4. Confidence thresholds control autonomy — tune how much the agent does on its own vs. asks for help
5. Impasse detection catches stuck states — the agent knows when it can’t proceed and asks for help