LoopIn

Human-in-the-loop Interrupt-API für KI-Agenten.

LoopIn ermöglicht es KI-Agenten, an kritischen Entscheidungspunkten zu pausieren, eine menschliche Überprüfung anzufordern und die Ausführung basierend auf der Entscheidung des Menschen fortzusetzen. Keine Agenten mehr, die allein Entscheidungen mit hohem Risiko treffen.

Warum LoopIn?

Autonome Agenten sind leistungsstark – bis sie auf eine Entscheidung stoßen, die sie nicht ohne einen Menschen treffen sollten. LoopIn bietet jedem Agenten eine sichere Ausfahrt:

1. Agent erreicht einen Entscheidungspunkt → ruft POST /interrupts auf

2. LoopIn benachrichtigt den Menschen → per Webhook oder einer direkten Überprüfungs-URL

3. Mensch genehmigt oder lehnt ab → über die Überprüfungsseite oder POST /interrupts/:id/decide

4. Agent fragt die Entscheidung ab → GET /interrupts/:id

5. Agent fährt fort → unter Verwendung der Entscheidung (und aller geänderten Parameter, die der Mensch bereitgestellt hat)

Related MCP server: final-approval

Endpunkte

POST /interrupts

Erstellt eine neue Unterbrechungsanfrage.

Anfrage:

{
  "agentId": "agent-payments-v2",
  "userId": "user-123",
  "action": "Transfer $4,200 to vendor account ending in 9821",
  "context": {
    "vendor": "Acme Supplies",
    "amount": 4200,
    "currency": "USD",
    "invoiceId": "INV-2024-0892",
    "accountLast4": "9821"
  },
  "urgency": "high",
  "expiresIn": 1800,
  "callbackUrl": "https://my-agent.example.com/webhooks/loopin"
}

Antwort:

{
  "interruptId": "3f4e2a1b-...",
  "status": "pending",
  "expiresAt": "2024-04-12T14:30:00Z",
  "reviewUrl": "http://localhost:3002/review/3f4e2a1b-..."
}

GET /interrupts/:interruptId

Fragt den aktuellen Status und die Entscheidung ab.

Antwort (ausstehend):

{
  "interruptId": "3f4e2a1b-...",
  "status": "pending",
  "action": "Transfer $4,200 to vendor account ending in 9821",
  "context": { ... },
  "urgency": "high",
  "createdAt": "2024-04-12T13:00:00Z",
  "expiresAt": "2024-04-12T14:30:00Z",
  "reviewUrl": "http://localhost:3002/review/3f4e2a1b-..."
}

Antwort (abgeschlossen):

{
  "interruptId": "3f4e2a1b-...",
  "status": "approved",
  "decision": "approved",
  "decidedAt": "2024-04-12T13:07:22Z",
  "reason": "Invoice verified, proceed."
}

POST /interrupts/:interruptId/decide

Übermittelt eine menschliche Entscheidung.

Anfrage:

{
  "decision": "approved",
  "reason": "Invoice verified, proceed.",
  "modifiedParams": { "amount": 4200 }
}

Antwort:

{
  "interruptId": "3f4e2a1b-...",
  "status": "resolved",
  "decision": "approved",
  "decidedAt": "2024-04-12T13:07:22Z"
}

GET /interrupts/pending/:userId

Listet alle ausstehenden Unterbrechungen auf, die auf die Überprüfung durch einen Benutzer warten.

Antwort:

[
  {
    "interruptId": "3f4e2a1b-...",
    "action": "Transfer $4,200 to vendor...",
    "urgency": "high",
    "createdAt": "...",
    "expiresAt": "...",
    "reviewUrl": "..."
  }
]

DELETE /interrupts/:interruptId

Bricht eine ausstehende Unterbrechung ab (der Agent benötigt die Entscheidung nicht mehr).

GET /analytics/:userId

Nutzungsstatistiken.

Antwort:

{
  "userId": "user-123",
  "totalInterrupts": 47,
  "approvalRate": 0.83,
  "avgResponseTimeMs": 142000,
  "byStatus": { "approved": 39, "rejected": 8 },
  "byUrgency": { "high": 12, "medium": 28, "low": 7 },
  "topActionTypes": [
    { "action": "Send payment", "count": 18 },
    { "action": "Delete records", "count": 9 }
  ]
}

Überprüfungsseite

Jede Unterbrechung erhält eine für Menschen lesbare Überprüfungs-URL:

GET /review/:interruptId

Diese rendert eine HTML-Seite, die Folgendes anzeigt:

• Was der Agent tun möchte

• Alle Kontextdaten (formatiertes JSON)

• Dringlichkeits-Badge

• Genehmigen / Ablehnen-Schaltflächen

• Optionales Textfeld für Begründungen

Teilen Sie diese URL mit jedem, der die Anfrage überprüfen muss. Standardmäßig ist kein Login erforderlich.

MCP-Tools

Der LoopIn MCP-Server stellt alle 6 Tools für die Verwendung mit jedem MCP-kompatiblen KI-Client (Claude Desktop, Cursor usw.) bereit:

MCP-Server-Einrichtung (stdio)

{
  "mcpServers": {
    "loopin": {
      "command": "npx",
      "args": ["-y", "@colossal-api/loopin-mcp"],
      "env": {
        "LOOPIN_API_URL": "https://your-loopin-instance.railway.app",
        "LOOPIN_API_KEY": "your-key"
      }
    }
  }
}

Nutzungsmuster für Agenten

1. Agent reaches a decision point
   → POST /interrupts { agentId, userId, action, context, urgency }
   ← { interruptId, reviewUrl }

2. Agent saves interruptId and pauses
   → (optionally: notify human via other channels with reviewUrl)

3. Agent polls until resolved
   → GET /interrupts/:interruptId
   ← { status: "pending" }   ← keep polling
   ← { status: "approved", decision, modifiedParams }  ← resume

4. Agent resumes execution
   → use modifiedParams if provided, otherwise proceed as planned

Nutzungsmuster für Menschen

Option A — Überprüfungs-URL (am einfachsten)

1. Erhalten Sie die reviewUrl vom Agenten (per E-Mail, Slack usw.)

2. Öffnen Sie die URL in einem beliebigen Browser

3. Überprüfen Sie den Kontext, klicken Sie auf Genehmigen oder Ablehnen, fügen Sie optional eine Begründung hinzu

4. Fertig — der Agent erhält die Entscheidung bei seiner nächsten Abfrage

Option B — Ausstehende auflisten (Dashboard)

1. GET /interrupts/pending/:userId — alle offenen Anfragen anzeigen

2. Öffnen Sie einzelne reviewUrls oder rufen Sie POST /interrupts/:id/decide direkt auf

Umgebungsvariablen

Colossal API-Portfolio

LoopIn ist Teil der Colossal API Suite von Infrastruktur-APIs für KI-Agenten:

• SubRadar — Abonnementerkennung und -kündigung

• MeetSync — Kalenderverhandlung und Terminplanung

• LoopIn — Human-in-the-loop Unterbrechung und Genehmigung

Alle Produkte teilen die gleiche Designphilosophie: einfache REST-APIs mit MCP-Server-Wrappern, damit Agenten sie nativ nutzen können.