Interactivity Modes

Interactivity modes control how much human oversight an agent requires during execution.

The Three Modes

Mode	Description	Human Involvement
Autonomous	Agent runs to completion without pausing	None (notifications only)
Key Decisions	Agent pauses for high-risk actions	At risk thresholds
Conversational	Agent frequently checks in with humans	At every major step

Autonomous Mode


interactivity:
  mode: autonomous

The agent runs from start to finish without human intervention.

When to Use

Low-risk, high-volume tasks
Well-tested, predictable workflows
Tasks where speed matters more than oversight
Background processing jobs

What Still Happens

Even in autonomous mode:

All actions are logged to the audit trail
Notifications can be sent on completion or failure
Constraints (max_steps, duration) are still enforced

Example


Run Started → THINK → DECIDE → ACT → OBSERVE →
             THINK → DECIDE → ACT → OBSERVE →
             THINK → DECIDE (Complete) → Done

Key Decisions Mode


interactivity:
  mode: key_decisions
  risk_threshold: 50

The agent runs autonomously until it encounters a high-risk action, then pauses for approval.

When to Use

Standard business workflows
Tasks with a mix of routine and sensitive actions
Processes where certain actions need sign-off
Most production deployments

How Risk is Assessed

Each action is scored based on:

Impact: What systems/data does it affect?
Reversibility: Can the action be undone?
Sensitivity: Does it involve PII, financial data, etc.?
Scope: How many entities are affected?

Example Flow


Run Started → THINK → DECIDE → ACT (low risk) → OBSERVE →
             THINK → DECIDE → ACT (low risk) → OBSERVE →
             THINK → DECIDE → ACT (HIGH RISK) →

┌─────────────────────────────────────────────────────────────┐
│  🛑 APPROVAL REQUIRED                                       │
│                                                             │
│  Action: Revoke AWS Production admin access                 │
│  Risk Score: 85/100                                         │
│                                                             │
│  [✓ Approve]  [✗ Deny]  [⚡ Escalate]                       │
└─────────────────────────────────────────────────────────────┘

[User approves]

             → OBSERVE → THINK → DECIDE (Complete) → Done

Configuring Risk Thresholds

Threshold	Behavior
0-25	Execute automatically
26-50	Execute with notification
51-75	Require approval
76-100	Require approval + escalation

Conversational Mode


interactivity:
  mode: conversational
  checkpoint_interval: 3  # Pause every 3 steps

The agent frequently pauses for human input, enabling collaborative decision-making.

When to Use

Sensitive or high-stakes processes
Exploratory or research tasks
Training users on new workflows
Situations requiring human judgment throughout

Example Flow


Run Started → THINK → DECIDE → ACT → OBSERVE →
             THINK → DECIDE → ACT →

┌─────────────────────────────────────────────────────────────┐
│  📋 CHECKPOINT                                              │
│                                                             │
│  Progress so far:                                           │
│  ✓ Gathered employee information                            │
│  ✓ Assessed risk level (HIGH)                               │
│  ✓ Identified 3 knowledge gaps                              │
│                                                             │
│  Next planned actions:                                      │
│  • Revoke AWS access                                        │
│  • Transfer document ownership                              │
│  • Schedule knowledge transfer                              │
│                                                             │
│  [Continue]  [Modify Plan]  [Pause]  [Abort]                │
└─────────────────────────────────────────────────────────────┘

[User continues]

             → OBSERVE → THINK → DECIDE → ACT → ...

Decision Points

When an agent pauses (in key_decisions or conversational mode), it creates a decision point:


{
  "id": "dp_123",
  "run_id": "run_456",
  "decision_type": "approval",
  "title": "Approve access revocation",
  "context": {
    "action": "revoke_aws_access",
    "target": "marcus.chen@company.com",
    "impact": ["3 production databases", "12 EC2 instances"]
  },
  "risk_level": "high",
  "risk_score": 85,
  "status": "pending",
  "timeout_seconds": 14400,
  "created_at": "2026-01-15T10:30:00Z"
}

Decision Types

Type	Description	User Actions
Approval	Yes/no decision on an action	Approve, Deny, Escalate
Choice	Select from multiple options	Choose option
Input	Provide additional information	Enter text/data

Timeouts

Decision points can have timeouts:


interactivity:
  mode: key_decisions
  decision_timeout_seconds: 14400  # 4 hours
  timeout_action: escalate  # escalate | continue | fail

Timeout Action	Behavior
escalate	Notify manager, extend timeout
continue	Proceed with default action
fail	Abort the run

Notifications

Configure who gets notified:


interactivity:
  mode: key_decisions
  notifications:
    on_decision_required:
      - channel: slack
        target: "#hr-approvals"
      - channel: email
        target: "hr-managers@company.com"
    on_timeout:
      - channel: slack
        target: "#hr-escalations"

Choosing the Right Mode

Question	Autonomous	Key Decisions	Conversational
Is the process well-defined?	✓	✓
Are all actions low-risk?	✓
Do some actions need approval?		✓	✓
Is speed critical?	✓
Is human judgment needed throughout?			✓
Are you training/validating the agent?			✓

Best Practices

Start with Key Decisions

Most production deployments should use key_decisions mode:

Provides oversight for sensitive actions
Doesn’t slow down routine operations
Creates clear audit trail of approvals

Tune Risk Thresholds

Monitor what actions trigger approvals and adjust:

Too many approvals → Raise threshold
Missing important actions → Lower threshold

Use Conversational for Onboarding

When deploying a new agent:

Start in conversational mode
Review each checkpoint, verify behavior
Transition to key_decisions once confident
Consider autonomous only for well-tested, low-risk agents