LoopIn

API de interrupción con intervención humana para agentes de IA.

LoopIn permite que los agentes de IA se pausen en puntos de decisión críticos, soliciten una revisión humana y reanuden la ejecución basándose en la decisión del humano. Se acabó el que los agentes tomen decisiones de alto riesgo por su cuenta.

¿Por qué LoopIn?

Los agentes autónomos son potentes, hasta que llegan a una decisión que no deberían tomar sin un humano. LoopIn ofrece a cada agente una vía de escape segura:

1. El agente llega a un punto de decisión → llama a POST /interrupts

2. LoopIn notifica al humano → mediante un webhook o una URL de revisión directa

3. El humano aprueba o rechaza → a través de la página de revisión o POST /interrupts/:id/decide

4. El agente consulta la decisión → GET /interrupts/:id

5. El agente se reanuda → utilizando la decisión (y cualquier parámetro modificado que el humano haya proporcionado)

Related MCP server: final-approval

Endpoints

POST /interrupts

Crea una nueva solicitud de interrupción.

Solicitud:

{
  "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"
}

Respuesta:

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

GET /interrupts/:interruptId

Consulta el estado actual y la decisión.

Respuesta (pendiente):

{
  "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-..."
}

Respuesta (resuelta):

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

POST /interrupts/:interruptId/decide

Envía una decisión humana.

Solicitud:

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

Respuesta:

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

GET /interrupts/pending/:userId

Enumera todas las interrupciones pendientes que esperan la revisión de un usuario.

Respuesta:

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

DELETE /interrupts/:interruptId

Cancela una interrupción pendiente (el agente ya no necesita la decisión).

GET /analytics/:userId

Estadísticas de uso.

Respuesta:

{
  "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 }
  ]
}

Página de revisión

Cada interrupción obtiene una URL de revisión legible por humanos:

GET /review/:interruptId

Esto genera una página HTML que muestra:

• Lo que el agente quiere hacer

• Todos los datos de contexto (JSON formateado)

• Etiqueta de urgencia

• Botones de Aprobar / Rechazar

• Campo de texto opcional para el motivo

Comparte esta URL con quien necesite revisar la solicitud. Por defecto, no se requiere inicio de sesión.

Herramientas MCP

El servidor MCP de LoopIn expone las 6 herramientas para su uso con cualquier cliente de IA compatible con MCP (Claude Desktop, Cursor, etc.):

Configuración del servidor MCP (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"
      }
    }
  }
}

Patrón de uso del agente

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

Patrón de uso humano

Opción A — URL de revisión (la más sencilla)

1. Recibe la reviewUrl del agente (por correo electrónico, Slack, etc.)

2. Abre la URL en cualquier navegador

3. Revisa el contexto, haz clic en Aprobar o Rechazar, añade un motivo opcional

4. Listo: el agente recibe la decisión en su próxima consulta

Opción B — Listar pendientes (panel de control)

1. GET /interrupts/pending/:userId — ver todas las solicitudes abiertas

2. Abre las reviewUrl individuales o llama directamente a POST /interrupts/:id/decide

Variables de entorno

Portafolio de API Colossal

LoopIn es parte del conjunto de API de infraestructura Colossal API para agentes de IA:

• SubRadar — Detección y cancelación de suscripciones

• MeetSync — Negociación y programación de reuniones

• LoopIn — Interrupción y aprobación con intervención humana

Todos los productos comparten la misma filosofía de diseño: API REST sencillas con envoltorios de servidor MCP para que los agentes puedan utilizarlas de forma nativa.