Documentation Index#

Fetch the complete documentation index at: https://docs.ag-ui.com/llms.txt Use this file to discover all available pages before exploring further.

Native support for human-in-the-loop pauses and interrupts

Interrupt-Aware Run Lifecycle Proposal#

Summary#

Problem Statement#

Agents often need to pause execution to request human approval, gather additional input, or confirm potentially risky actions. Currently, there’s no standardized way to handle these interruptions across different agent frameworks.

Motivation#

Support human-in-the-loop pauses (and related mechanisms) natively in AG-UI and CopilotKit. This enables compatibility with various framework interrupts, workflow suspend/resume, and other framework-specific pause mechanisms.

Status#

• Status: Draft
• Author(s): Markus Ecker (mail@mme.xyz)

Overview#

This proposal introduces a standardized interrupt/resume pattern:

sequenceDiagram
  participant Agent
  participant Client as Client App

  Agent-->>Client: RUN_FINISHED { outcome: "interrupt", interrupt:{ id, reason, payload }}
  Client-->>Agent: RunAgentInput.resume { threadId, interruptId, payload }
  Agent-->>Client: RUN_FINISHED { outcome: "success", result }

Detailed Specification#

Updates to RUN_FINISHED Event#

type RunFinishedOutcome = "success" | "interrupt"

type RunFinished = {
  type: "RUN_FINISHED"

  // ... existing fields

  outcome?: RunFinishedOutcome // optional for back-compat (see rules below)

  // Present when outcome === "success" (or when outcome omitted and interrupt is absent)
  result?: any

  // Present when outcome === "interrupt" (or when outcome omitted and interrupt is present)
  interrupt?: {
    id?: string // id can be set when needed
    reason?: string // e.g. "human_approval" | "upload_required" | "policy_hold"
    payload?: any // arbitrary JSON for UI (forms, proposals, diffs, etc.)
  }
}

When a run finishes with outcome == "interrupt", the agent indicates that on the next run, a value needs to be provided to continue.

Updates to RunAgentInput#

type RunAgentInput = {
  // ... existing fields

  // NEW: resume channel for continuing a suspension
  resume?: {
    interruptId?: string // echo back if one was provided
    payload?: any // arbitrary JSON: approvals, edits, files-as-refs, etc.
  }
}

Contract Rules#

• Resume requests must use the same threadId
• When given in the interrupt, the interruptId must be provided via RunAgentInput
• Agents should handle missing or invalid resume payloads gracefully

Implementation Examples#

Minimal Interrupt/Resume#

Agent sends interrupt:

{
  "type": "RUN_FINISHED",
  "threadId": "t1",
  "runId": "r1",
  "outcome": "interrupt",
  "interrupt": {
    "id": "int-abc123",
    "reason": "human_approval",
    "payload": {
      "proposal": {
        "tool": "sendEmail",
        "args": { "to": "a@b.com", "subject": "Hi", "body": "…" }
      }
    }
  }
}

User responds:

{
  "threadId": "t1",
  "runId": "r2",
  "resume": {
    "interruptId": "int-abc123",
    "payload": { "approved": true }
  }
}

Complex Approval Flow#

Agent requests approval with context:

{
  "type": "RUN_FINISHED",
  "threadId": "thread-456",
  "runId": "run-789",
  "outcome": "interrupt",
  "interrupt": {
    "id": "approval-001",
    "reason": "database_modification",
    "payload": {
      "action": "DELETE",
      "table": "users",
      "affectedRows": 42,
      "query": "DELETE FROM users WHERE last_login < '2023-01-01'",
      "rollbackPlan": "Restore from backup snapshot-2025-01-23",
      "riskLevel": "high"
    }
  }
}

User approves with modifications:

{
  "threadId": "thread-456",
  "runId": "run-790",
  "resume": {
    "interruptId": "approval-001",
    "payload": {
      "approved": true,
      "modifications": {
        "batchSize": 10,
        "dryRun": true
      }
    }
  }
}

Use Cases#

Human Approval#

Agents pause before executing sensitive operations (sending emails, making purchases, deleting data).

Information Gathering#

Agent requests additional context or files from the user mid-execution.

Policy Enforcement#

Automatic pauses triggered by organizational policies or compliance requirements.

Multi-Step Wizards#

Complex workflows where each step requires user confirmation or input.

Error Recovery#

Agent pauses when encountering an error, allowing user to provide guidance.

Implementation Considerations#

Client SDK Changes#

TypeScript SDK:

• Extended RunFinishedEvent type with outcome and interrupt fields
• Updated RunAgentInput with resume field
• Helper methods for interrupt handling

Python SDK:

• Extended RunFinishedEvent class
• Updated RunAgentInput with resume support
• Interrupt state management utilities

Framework Integration#

Planning Frameworks:

• Map framework interrupts to AG-UI interrupt events
• Handle resume payloads in execution continuation

Workflow Systems:

• Convert workflow suspensions to AG-UI interrupts
• Resume workflow execution with provided payload

Custom Frameworks:

• Provide interrupt/resume adapter interface
• Documentation for integration patterns

UI Considerations#

• Standard components for common interrupt reasons
• Customizable interrupt UI based on payload
• Clear indication of pending interrupts
• History of interrupt/resume actions

Testing Strategy#

• Unit tests for interrupt/resume serialization
• Integration tests with multiple frameworks
• E2E tests demonstrating various interrupt scenarios
• State consistency tests across interrupt boundaries
• Performance tests for rapid interrupt/resume cycles

References#

• AG-UI Events Documentation
• AG-UI State Management