AI Intervention Agent

AI Intervention Agent

Intervención en tiempo real para agentes MCP: pausa, corrige el rumbo, reanuda.

English | 简体中文

¿Alguna vez tu agente de IA se ha desviado con confianza en la dirección equivocada a mitad de tarea? AI Intervention Agent te ofrece una interfaz web para pausar al agente en momentos clave, revisar lo que está a punto de hacer, escribir una corrección de rumbo, adjuntar capturas de pantalla y reanudar, todo a través de la herramienta interactive_feedback de MCP, sin terminar la conversación.

Funciona con Cursor, VS Code, Claude Code, Augment, Windsurf, Trae y más.

Inicio rápido

Apunta tu herramienta de IA al servidor MCP mediante uvx (instala y ejecuta automáticamente la última versión):

{
  "mcpServers": {
    "ai-intervention-agent": {
      "command": "uvx",
      "args": ["ai-intervention-agent"],
      "timeout": 600,
      "autoApprove": ["interactive_feedback"]
    }
  }
}

Luego añade el fragmento de prompt a continuación a las reglas de tu agente / prompt del sistema, para que el agente te consulte a través de interactive_feedback en lugar de completar tareas en silencio.

- Only ask me through the MCP `ai-intervention-agent` tool; do not ask directly in chat or ask for end-of-task confirmation in chat.
- If a tool call fails, keep asking again through `ai-intervention-agent` instead of making assumptions, until the tool call succeeds.

ai-intervention-agent usage details:

- If requirements are unclear, use `ai-intervention-agent` to ask for clarification with predefined options.
- If there are multiple approaches, use `ai-intervention-agent` to ask instead of deciding unilaterally.
- If a plan/strategy needs to change, use `ai-intervention-agent` to ask instead of deciding unilaterally.
- Before finishing a request, always ask for feedback via `ai-intervention-agent`.
- Do not end the conversation/request unless the user explicitly allows it via `ai-intervention-agent`.

pip install ai-intervention-agent

{
  "mcpServers": {
    "ai-intervention-agent": {
      "command": "ai-intervention-agent",
      "args": [],
      "timeout": 600,
      "autoApprove": ["interactive_feedback"]
    }
  }
}

Please configure my IDE / AI tool to use the `ai-intervention-agent` MCP server:

1. Locate the correct MCP config file for my current IDE
   (e.g. `.cursor/mcp.json` or `~/.cursor/mcp.json` for Cursor,
    `~/.claude.json` for Claude Code,
    `.vscode/mcp.json` for VS Code).
2. Add this entry under `mcpServers`:
   - command: `uvx`
   - args: `["ai-intervention-agent"]`
   - timeout: 600
   - autoApprove: `["interactive_feedback"]`
3. Append the project's recommended prompt rules
   (the "Prompt snippet (copy/paste)" block in this README)
   to my agent rules / system prompt, so the agent always asks me
   through `interactive_feedback` instead of ending tasks silently.
4. Verify by listing MCP servers and confirming `ai-intervention-agent` is loaded.

[!NOTE] interactive_feedback es una herramienta de larga duración; algunos clientes imponen un tiempo de espera estricto. La interfaz web incluye una cuenta regresiva + reenvío automático (feedback.frontend_countdown, por defecto 240s, rango 0 o [10, 3600]) para mantener las sesiones activas; el valor predeterminado se mantiene por debajo del límite común de 300s.

Capturas de pantalla

_{Página de comentarios · cambio automático entre oscuro/claro · pestañas de múltiples tareas con cuentas regresivas independientes}

Características clave

• Intervención en tiempo real — el agente se pausa y espera tu entrada mediante interactive_feedback
• Interfaz web — Markdown, resaltado de código y renderizado matemático incluidos
• Pestañas de múltiples tareas — solicitudes concurrentes con cuentas regresivas independientes, autoguardado de borradores por tarea y reenvío automático que mantiene sesiones largas activas (tu texto escrito y opciones marcadas se envían en cero, nunca un prompt vacío)
• Retención al escribir — la cuenta regresiva se extiende automáticamente mientras escribes y nunca se dispara a mitad de entrada (tanto en la página web como en la extensión de VS Code)
• Ergonomía del bucle del agente — chips de contexto header_label por tarea, sugerencias feedback_placeholder y metadatos de ingeniería de bucle (loop_id, loop_phase, success_criteria)
• Notificaciones — web / sonido / sistema / Bark (push iOS), además de carga de sonido de notificación personalizado
• Compatibilidad SSH / LAN — funciona detrás de reenvío de puertos; mDNS publica una URL <host>.local cuando es compatible
• i18n — interfaz web + extensión de VS Code disponibles en en / zh-CN / zh-TW
• PWA, consciente de modo offline, accesible WCAG 2.1 AA — instalable desde el navegador, con contraste / enfoque / movimiento reducido auditados y bloqueados por pruebas invariantes
• Instalación estable — construido sobre Flask 3.x con dependencias conservadoras; inmune al cambio disruptivo de Starlette 1.0 que rompió varios servidores de comentarios MCP a principios de 2026

Descripción general de la arquitectura

AIIA se ejecuta como un único proceso de Python que conecta tres superficies: un servidor MCP stdio que expone interactive_feedback, un servidor web Flask con un bus de eventos SSE y una cola de tareas persistente que alimenta la pila de notificaciones. El diagrama de componentes, los diagramas de secuencia de interacción y recuperación de fallos, la tabla de parámetros MCP del lado del agente y el catálogo de invariantes de tiempo de ejecución se encuentran en docs/architecture.md.

Extensión de VS Code (opcional)

Incorpora el panel de interacción en la barra lateral de VS Code para que nunca cambies al navegador.

• Instalación: Open VSX, VS Code Marketplace, o descarga el VSIX desde GitHub Releases
• Configuración clave: ai-intervention-agent.serverUrl — debe coincidir con tu URL de la interfaz web (p. ej., http://localhost:8080; cambia el puerto mediante web_ui.port en config.toml.default)
• Más: ai-intervention-agent.logLevel, notificaciones nativas de macOS (activadas por defecto, alterna en el panel de Configuración de Notificaciones de la barra lateral) — lista completa de configuraciones y el modelo de seguridad del ejecutor de AppleScript en packages/vscode/README.md

Configuración

En la primera ejecución, config.toml se crea a partir de config.toml.default en el directorio de configuración de usuario de tu sistema operativo — la referencia TOML completa está en docs/configuration.md:

Para uvx, Docker, systemd o entornos de ejecución remotos SSH donde editar el archivo es incómodo, la mayoría de las configuraciones web_ui más utilizadas se pueden sobrescribir mediante variables de entorno al inicio (los valores no válidos registran un WARNING y vuelven a un valor seguro; superficie completa en docs/configuration.md#environment-variable-overrides):

export AI_INTERVENTION_AGENT_WEB_UI_HOST=0.0.0.0      # default 127.0.0.1
export AI_INTERVENTION_AGENT_WEB_UI_PORT=8181         # default 8080, range [1, 65535]
export AI_INTERVENTION_AGENT_WEB_UI_LANGUAGE=en       # auto / en / zh-CN / zh-TW
uvx ai-intervention-agent

Inspección CLI: --version, --help y --print-config (vuelca la configuración combinada efectiva como JSON compatible con jq, con campos tipo secreto redactados — responde "¿mi puerto viene de env o de config.toml?" en una sola canalización).

En iPhone, la configuración más fluida envuelve la interfaz web en una automatización de Shortcuts y apunta los toques de notificación de Bark hacia ella — guía paso a paso en docs/configuration.md#recommended-iphone-setup-shortcuts--bark.

Documentación

• Índice de documentación (por audiencia): docs/README.md · docs/README.zh-CN.md
• Arquitectura (diagramas + flujo de trabajo del agente): docs/architecture.md
• Referencia de herramientas MCP: docs/mcp_tools.md · docs/mcp_tools.zh-CN.md
• Documentación de API: docs/api/index.md · docs/api.zh-CN/index.md
• Solución de problemas / FAQ: docs/troubleshooting.md · docs/troubleshooting.zh-CN.md
• Notas de versión: CHANGELOG.md · Listado del marketplace de VS Code: packages/vscode/CHANGELOG.md
• Contribución: CONTRIBUTING.md · CODE_OF_CONDUCT.md · índice de scripts: scripts/README.md · guía i18n: docs/i18n.md
• Runbook de recuperación de versiones: docs/release-recovery.md · docs/release-recovery.zh-CN.md
• DeepWiki Q&A — preguntas y respuestas aumentadas por IA sobre el repositorio:

Proyectos relacionados

Dónde se sitúa AIIA en el espectro: AIIA apunta al extremo operativamente profundo — interfaz web + extensión de VS Code compartiendo un backend, observabilidad de nivel producción (punto final Prometheus /metrics + un panel de Grafana de referencia), i18n bilingüe + documentación, disciplina estricta de pruebas invariantes (más de 8,200 pruebas + más de 1,050 subpruebas en 40 ciclos de auditoría) y una canalización de versiones de 5 trabajos. ¿Quieres la opción más pequeña? La bifurcación de poliva. ¿Una aplicación de escritorio? mcp-feedback-enhanced. ¿Interfaz de voz / multi-pestaña? Relay o la bifurcación de Node.js. ¿Integración operativa de pila completa? AIIA.

Llamadas de brecha de funciones (las contribuciones son bienvenidas): entrada de voz a texto, ventana nativa siempre al frente, monitoreo de uso de Cursor, interfaz de fusión de sesiones multi-pestaña.

Los recuentos de estrellas son instantáneas aproximadas (última revisión 2026-06); consulta cada upstream para números actuales. Envía un PR si deseas que se liste otro proyecto relacionado.

Agradecimientos

La herencia de este proyecto se remonta a Fábio Ferreira (2024) y Pau Oliva (2025), cuyos noopstudios/interactive-feedback-mcp y poliva/interactive-feedback-mcp originales sembraron la superficie de la herramienta interactive_feedback de MCP. Sus avisos de derechos de autor se conservan en LICENSE según los términos de la licencia MIT. La línea v1.5.x es una reescritura sustancial — interfaz web, extensión de VS Code, i18n, pila de notificaciones, canalización CI/CD — propiedad y mantenida por @xiadengma (editor de PyPI / Open VSX / VS Code Marketplace).

Licencia

Licencia MIT