ai-execution-protocol 0.7.4

Protocolo instalavel para orientar agentes de IA em tarefas tecnicas: classifica risco, reduz contexto, controla ferramentas quando configurado e exige validacao antes da entrega.

AI Execution Protocol

Protocolo instalavel para orientar agentes de IA em tarefas tecnicas: classifica risco, reduz contexto, controla ferramentas quando configurado e exige validacao antes da entrega.

AI Execution Protocol ajuda agentes de IA a trabalharem como operadores de engenharia controlados, nao como seguidores livres de prompt. Ele transforma um pedido em um contrato de execucao delimitado: classificar risco, carregar apenas o contexto necessario, selecionar as capacidades minimas, bloquear uso de ferramentas antes da execucao quando houver suporte, validar o resultado e relatar evidencias com risco residual.

O projeto e otimizado para Codex em repositorios locais. Hoje ele instala regras operacionais, scripts de verificacao e checks locais para tornar tarefas com IA mais previsiveis. Algumas garantias dependem de hooks, CI ou runners configurados; sem isso, o protocolo atua como disciplina de execucao best_effort.

Ele nao e um produto de seguranca e nao controla magicamente ferramentas que rodam por fora do caminho configurado. Garantias fortes exigem que o comando, hook, job de CI, runner ou gateway local chame os checks executaveis.

O Que Ele Resolve

Agentes de IA costumam falhar de formas previsiveis:

• agem antes de entender o impacto;
• abrem contexto demais e perdem o alvo real;
• tratam trabalho arriscado como uma edicao simples;
• usam ferramentas que nunca foram planejadas;
• pulam validacao ou afirmam testes que nao rodaram;
• entregam sem explicar o que ainda esta incerto.

AI Execution Protocol da ao agente um sistema operacional compacto para esses momentos. Tarefas simples continuam rapidas. Tarefas arriscadas exigem mapeamento, confirmacao, disciplina de ferramentas, validacao e um relatorio claro de entrega.

Fluxo Central

entender -> classificar risco -> mapear impacto -> executar -> validar -> relatar

O protocolo atual combina:

• niveis de risco, de respostas diretas ate operacoes sensiveis;
• route packs para carregar pouco contexto, especifico da tarefa;
• memoria adaptativa que orienta, mas nao sobrepoe o pedido atual;
• orcamentos de contexto para evitar arquivos e tokens desnecessarios;
• regras de economia de prompt para melhorar pedidos sem verbosidade;
• roteamento de capacidades para skills, MCPs, ferramentas e acoes externas;
• roteamento de inteligencia proporcional ao esforco necessario;
• validacao seletiva baseada no raio de impacto;
• contratos comportamentais para aderencia observavel do agente;
• gates executaveis para runners, hooks, proxies e integracoes de host;
• feedback de execucoes reais com consentimento para avaliacao local.

Niveis De Garantia

AI Execution Protocol e explicito sobre o que consegue ou nao impor.

Nivel	O Que Controla O Agente	O Que Pode Impor	Limite Principal
best_effort	AGENTS.md e arquivos de instrucao da IDE	Melhor planejamento, disciplina de contexto e relato	Ferramentas diretas do host ainda podem desviar do protocolo
wrapped_enforced	ai-protocol run, run-auto, hooks, CI ou runners locais	Plano valido, comando permitido e evidencia de validacao	Comandos fora do wrapper nao sao cobertos
proxy_enforced	Chamadas de ferramenta via gateway/proxy	Bloqueia ferramentas nao planejadas ou sem suporte	O host precisa esconder acesso direto as ferramentas
host_integrated	Uma integracao propria chama o gateway antes de ferramentas	Checks obrigatorios antes de ferramenta naquele caminho	Fora dessa integracao, ainda precisa de validacao e julgamento humano

O controle mais forte vem de fronteiras executaveis, nao de um prompt mais longo:

instrucoes -> runner/hooks -> gateway local -> integracao propria

Onde Roda Hoje

O uso principal hoje e em repositorios locais com agentes de coding, especialmente Codex.

Na pratica, o projeto entrega:

• arquivos de instrucao para orientar a IA dentro do projeto;
• YAMLs curtos para classificar risco, escolher contexto e validar entrega;
• CLI npm/Python para instalar, verificar e diagnosticar o protocolo;
• hooks, runners e gateway local opcionais para checks mais fortes;
• feedback local de execucoes reais somente com consentimento explicito.

O protocolo nao promete suporte completo a IDEs, chats ou frameworks externos. Esses caminhos existem como exemplos e pontos de extensao, mas a promessa publica atual e disciplinar a execucao da IA no projeto instalado.

Exemplos de integracao ficam em:

• examples/openai_agents_adapter.py
• examples/langgraph_adapter.py
• examples/crewai_adapter.py

Instalacao

Instale a partir de um pacote publicado e inicialize o projeto alvo:

npm install -g ai-execution-protocol
ai-protocol init C:\path\to\project
ai-protocol verify C:\path\to\project

Ou instale com Python:

python -m pip install --upgrade ai-execution-protocol
ai-protocol install C:\path\to\project
ai-protocol verify C:\path\to\project

Preveja a instalacao sem alterar arquivos:

ai-protocol install C:\path\to\project --dry-run

Ative a automacao local strict depois do consentimento:

ai-protocol setup-local C:\path\to\project --yes --real-tests accept

O resultado esperado da verificacao e PASS.

Demo De Cinco Minutos

ai-protocol e2e-demo
ai-protocol explain gateway
ai-protocol init-example C:\tmp\aep-example
cd C:\tmp\aep-example
ai-protocol install .
ai-protocol workflow run workflow.yaml
ai-protocol workflow report

Execucoes controladas podem gravar um trace local em .ai-protocol-run/trace.jsonl. Resuma sem coletar logs completos:

ai-protocol trace-report C:\path\to\project

Comandos Principais

ai-protocol verify C:\path\to\project
ai-protocol doctor C:\path\to\project
ai-protocol strict-status C:\path\to\project
ai-protocol preflight C:\path\to\project --plan plan.json
ai-protocol check-call C:\path\to\project --input call.json
ai-protocol proxy-call C:\path\to\project --input proxy-call.json
ai-protocol run-checks C:\path\to\project --plan plan.json --report report.json
ai-protocol run --target C:\path\to\project --plan plan.json --call call.json --report report.json --npm-script test
ai-protocol run-auto --target C:\path\to\project --risk 1 --npm-script test

Use doctor para inspecionar estado de instalacao, cobertura strict, onboarding, feedback consentido, scripts protegidos de pacote e hooks.

Feedback De Execucoes Reais Com Consentimento

Projetos instalados incluem uma pasta visivel ai-protocol-feedback/. No primeiro contato, o usuario pode escolher de forma independente se quer:

• reforcar arquivos locais de instrucao do host;
• permitir coleta local de feedback de execucoes reais.

Quando aceito, o coletor armazena resumos sanitizados de tarefas tecnicas elegiveis. Ele nao coleta arquivos fonte, diffs brutos, arquivos .env, credenciais, dados de clientes, logs completos ou uploads remotos. Se uma raiz local do framework estiver configurada, lotes validados podem ser importados em real-runs/received/ como received_unreviewed.

Nenhum feedback e coletado antes do consentimento explicito. Publicacao ou envio pela internet exige uma acao separada e um consentimento separado.

Estrutura Do Projeto

• AGENTS.md: arquivo principal de instrucao para agentes de IA neste repo.
• INDEX.yaml: mapa estruturado para navegacao rapida.
• config.yaml: alvo atual, versao do protocolo e modo de operacao.
• canonical-state.yaml: fonte compacta do estado do projeto.
• context-map.yaml: aliases de dominio e arquivos candidatos.
• protocol/: regras operacionais curtas em YAML.
• behavior/: contrato comportamental observavel e checklist de auditoria.
• capabilities/: registro de skills, MCPs e ferramentas opcionais.
• ai-protocol-enforcement/: gateway executavel local e politica.
• ai-protocol-onboarding/: configuracao local consentida do host.
• ai-protocol-feedback/: consentimento visivel e execucoes locais.
• docs/: documentacao conceitual.
• examples/: exemplos de adaptadores e workflows.
• schema/: schemas de validacao.
• scripts/: checks de instalacao, validacao, benchmark e release.
• real-runs/: templates e lotes importados de feedback local.
• dist/minimal/: pacote minimo gerado para instalacao.

Status E Limites

Status: alpha operacional.

O pacote ja inclui CLIs npm e Python, instalacao em projetos, onboarding, roteamento de risco, orcamento de contexto, memoria adaptativa, gates de capacidades, politica de custo-qualidade, validacao seletiva, enforcement local, hooks de runtime adapter, exemplos de frameworks e feedback de execucoes reais com consentimento.

Tarefas criticas ainda exigem revisao tecnica, testes reais, sandboxing do host e confirmacao explicita para operacoes sensiveis. O protocolo melhora a disciplina de execucao; ele nao substitui julgamento de engenharia.

Documentacao

Use docs/ para explicacoes conceituais e protocol/ para regras operacionais compactas. Comece por:

• docs/00-visao-geral.md
• docs/12-instalacao-em-outro-projeto.md
• docs/25-testes-reais-com-consentimento.md
• docs/26-enforcement-gateway.md
• docs/27-runtime-adapter.md

Suporte

Abra bugs e pedidos de feature no GitHub:

https://github.com/rodneigk2/ai-execution-protocol/issues

Licenca

Distribuido sob a licenca MIT. Veja LICENSE.