AI Intervention Agent

AI Intervention Agent

Intervenção do usuário em tempo real para agentes MCP — pausar, corrigir o rumo, retomar.

English | 简体中文

Já teve seu agente de IA seguindo confiantemente na direção errada no meio da tarefa? O AI Intervention Agent oferece uma interface web para pausar o agente em momentos-chave, revisar o que ele está prestes a fazer, digitar uma correção de rumo, anexar capturas de tela e retomar — tudo por meio da ferramenta interactive_feedback do MCP, sem encerrar a conversa.

Funciona com Cursor, VS Code, Claude Code, Augment, Windsurf, Trae e outros.

Início rápido

Aponte sua ferramenta de IA para o servidor MCP via uvx (instala e executa a versão mais recente automaticamente):

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

Em seguida, adicione o trecho de prompt abaixo às regras do seu agente / prompt de sistema, para que o agente pergunte a você por meio de interactive_feedback em vez de concluir tarefas silenciosamente.

- 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 é uma ferramenta de longa duração; alguns clientes impõem um tempo limite rígido de solicitação. A interface web inclui uma contagem regressiva + reenvio automático (feedback.frontend_countdown, padrão 240s, intervalo 0 ou [10, 3600]) para manter as sessões ativas — o padrão permanece abaixo do tempo limite rígido comum de 300s.

Capturas de tela

_{Página de feedback · alterna automaticamente entre claro/escuro · abas de múltiplas tarefas com contagens regressivas independentes}

Principais recursos

• Intervenção em tempo real — o agente pausa e aguarda sua entrada via interactive_feedback
• Interface web — Markdown, realce de código e renderização matemática prontos para uso
• Abas de múltiplas tarefas — solicitações concorrentes com contagens regressivas independentes, salvamento automático de rascunho por tarefa e reenvio automático que mantém sessões longas ativas (seu texto digitado e opções marcadas são enviados em zero, nunca um prompt vazio)
• Segurar ao digitar — a contagem regressiva se estende automaticamente enquanto você digita e nunca dispara no meio da entrada (tanto na página web quanto na extensão do VS Code)
• Ergonomia do loop do agente — chips de contexto header_label por tarefa, dicas de feedback_placeholder e metadados de engenharia de loop (loop_id, loop_phase, success_criteria)
• Notificações — web / som / sistema / Bark (push iOS), além de upload de som de notificação personalizado
• Compatível com SSH / LAN — funciona atrás de encaminhamento de porta; mDNS publica uma URL <host>.local quando suportado
• i18n — interface web + extensão VS Code disponíveis em en / zh-CN / zh-TW
• PWA, ciente de offline, acessível WCAG 2.1 AA — instalável a partir do navegador, com contraste / foco / movimento reduzido auditados e travados por testes invariantes
• Instalação estável — construído em Flask 3.x com pinos de dependência conservadores; imune à mudança de quebra do Starlette 1.0 que quebrou vários servidores de feedback MCP no início de 2026

Visão geral da arquitetura

AIIA é executado como um único processo Python que conecta três superfícies: um servidor MCP stdio expondo interactive_feedback, um servidor web Flask com um barramento de eventos SSE e uma fila de tarefas persistente alimentando a pilha de notificações. O diagrama de componentes, os diagramas de sequência de interação e recuperação de falhas, a tabela de parâmetros MCP do lado do agente e o catálogo de invariantes de tempo de execução estão em docs/architecture.md.

Extensão VS Code (opcional)

Insere o painel de interação na barra lateral do VS Code para que você nunca precise alternar para o navegador.

• Instalação: Open VSX, VS Code Marketplace ou baixe o VSIX de GitHub Releases
• Configuração principal: ai-intervention-agent.serverUrl — deve corresponder à URL da sua interface web (ex.: http://localhost:8080; altere a porta via web_ui.port em config.toml.default)
• Mais: ai-intervention-agent.logLevel, notificações nativas do macOS (ativadas por padrão, alternáveis no painel de Configurações de Notificação da barra lateral) — lista completa de configurações e o modelo de segurança do executor AppleScript em packages/vscode/README.md

Configuração

Na primeira execução, config.toml é criado a partir de config.toml.default no diretório de configuração do usuário do seu sistema operacional — a referência TOML completa está em docs/configuration.md:

Para uvx, Docker, systemd ou ambientes de execução SSH remotos onde editar o arquivo é complicado, as configurações web_ui mais usadas podem ser substituídas por variáveis de ambiente na inicialização (valores inválidos registram um WARNING e retornam com segurança; superfície completa em 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

Inspeção via CLI: --version, --help e --print-config (despeja a configuração mesclada efetiva como JSON compatível com jq, com campos semelhantes a segredos ocultos — responde "minha porta vem do ambiente ou do config.toml?" em um único pipeline).

No iPhone, a configuração mais suave envolve a interface web em uma automação de Atalhos e aponta os toques de notificação do Bark para ela — guia passo a passo em docs/configuration.md#recommended-iphone-setup-shortcuts--bark.

Documentação

• Índice de documentação (por público): docs/README.md · docs/README.zh-CN.md
• Arquitetura (diagramas + fluxo de trabalho do agente): docs/architecture.md
• Referência da ferramenta MCP: docs/mcp_tools.md · docs/mcp_tools.zh-CN.md
• Documentação da API: docs/api/index.md · docs/api.zh-CN/index.md
• Solução de problemas / FAQ: docs/troubleshooting.md · docs/troubleshooting.zh-CN.md
• Notas de versão: CHANGELOG.md · Listagem do marketplace VS Code: packages/vscode/CHANGELOG.md
• Contribuição: CONTRIBUTING.md · CODE_OF_CONDUCT.md · Índice de scripts: scripts/README.md · Guia de i18n: docs/i18n.md
• Runbook de recuperação de versão: docs/release-recovery.md · docs/release-recovery.zh-CN.md
• DeepWiki Q&A — Perguntas e respostas aprimoradas por IA sobre o repositório:

Projetos relacionados

Onde AIIA se posiciona no espectro: AIIA visa o extremo operacionalmente profundo — interface web + extensão VS Code compartilhando um único backend, observabilidade de nível de produção (endpoint Prometheus /metrics + um painel Grafana de referência), i18n bilíngue + documentação, disciplina rigorosa de testes invariantes (mais de 8.200 testes + mais de 1.050 subtestes em 40 ciclos de auditoria) e um pipeline de lançamento com 5 trabalhos. Quer a menor opção plug-and-play? A bifurcação do poliva. Um aplicativo desktop? mcp-feedback-enhanced. Interface de voz / múltiplas abas? Relay ou a bifurcação Node.js. Integração operacional full-stack? AIIA.

Chamadas de lacunas de recursos (contribuições bem-vindas): entrada de conversão de fala em texto, janela nativa sempre no topo, monitoramento de uso do Cursor, interface de mesclagem de sessões em múltiplas abas.

As contagens de estrelas são instantâneos aproximados (última revisão em 2026-06); verifique cada upstream para números atuais. Envie um PR se quiser que outro projeto relacionado seja listado.

Agradecimentos

A herança deste projeto remonta a Fábio Ferreira (2024) e Pau Oliva (2025), cujos noopstudios/interactive-feedback-mcp e poliva/interactive-feedback-mcp originais semearam a superfície da ferramenta interactive_feedback do MCP. Seus avisos de direitos autorais são preservados em LICENSE de acordo com os termos da licença MIT. A linha v1.5.x é uma reescrita substancial — interface web, extensão VS Code, i18n, pilha de notificações, pipeline CI/CD — de propriedade e mantida por @xiadengma (publicador PyPI / Open VSX / VS Code Marketplace).

Licença

Licença MIT