ai-execution-protocol 0.7.3

Portable execution protocol for AI coding agents: plan first, limit context, gate tools, validate changes, and report evidence.

AI Execution Protocol

Portable execution protocol for AI coding agents: plan first, limit context, gate tools, validate changes, and report evidence.

AI Execution Protocol is an installable control layer for projects that use AI coding agents. It turns a technical request into a bounded execution contract: classify risk, open only the context that matters, justify tool use before it happens, validate the result, and report what changed, what was not validated, and what still needs human judgment.

It is not another agent framework, and it does not promise total control over a host by itself. It can run as best-effort project instructions, then become stricter when a host, runner, hook, CI job, or local gateway calls its executable checks.

The current target is Codex. The protocol is optimized for Codex now, while the structure remains portable to other AI agents and automation hosts.

Objective

Reduce common AI execution failures: acting before impact is understood, loading too much context, treating sensitive work as low risk, using unplanned tools, skipping validation, or delivering without evidence.

The framework helps the agent:

• understand the intent before acting;
• classify task risk;
• find the right domain before opening large files;
• read only the context needed for the task;
• map impact before changing files;
• request confirmation for sensitive actions;
• choose tools and reasoning effort in proportion to risk;
• reduce cost without weakening context, safety, or required validation;
• validate the result before delivery;
• explain limits and residual risk.

Core idea

Entender -> classificar risco -> mapear impacto -> executar -> validar -> entregar

The protocol does not turn every task into a heavy process. The rule is proportionality: simple tasks should stay fast; critical tasks require more mapping, confirmation, and evidence.

Desde a v0.4.0, o framework combina contrato comportamental, memoria adaptativa, orcamento de contexto, validacao seletiva e roteamento de capacidades:

pedido -> risco -> memoria relevante -> contexto limitado -> acao -> validacao

O contrato comportamental transforma regras em comportamento observavel:

tarefa -> comportamento esperado -> avaliacao -> evidencia

Memoria orienta, o pedido atual autoriza e arquivos verificados definem a realidade. Inferencias ficam candidatas ate acumularem evidencia, e conteudo sensivel e bloqueado.

Skills, MCPs e ferramentas opcionais seguem outro limite:

resultado necessario -> capacidade minima -> permissao -> validacao

Risco maior restringe permissoes. Ele nao aumenta automaticamente a quantidade de ferramentas.

A partir da v0.6.0, hosts que conseguem chamar um gate local tambem podem usar uma politica executavel:

plano -> ai-protocol-enforcement/gateway.py -> ferramenta

Sem essa chamada pelo host, o modo continua best_effort. Com ela, chamadas de ferramenta fora do plano podem ser bloqueadas fora do modelo.

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

instrucao -> runner/hooks -> gateway/proxy -> host proprio

AGENTS.md e regras de IDE orientam o host. ai-protocol run, run-auto, hooks e CI controlam comandos que passam por eles. Gateway/proxy controla tools e MCPs quando o host nao expoe bypass direto. Controle total de runtime exige host proprio ou integracao equivalente.

Use ai-protocol doctor <projeto> para diagnosticar instalacao, strict mode, onboarding, testes reais, scripts protegidos e hooks.

Execucoes controladas geram trace local em .ai-protocol-run/trace.jsonl. Use ai-protocol trace-report <projeto> para resumir preflight, chamadas, comandos, validacao e falhas sem coletar logs completos.

Hosts que suportam tools customizadas podem usar ai-protocol proxy-call para executar uma chamada local somente depois de check-call aprovar o plano.

A partir da v0.7.0, integracoes com hosts e frameworks de agentes podem usar o runtime adapter como contrato publico: start_task -> validate_plan -> check/proxy tool -> trace -> finish_task -> run_checks. Isso permite acoplar o protocolo a Agents SDK, LangGraph, CrewAI ou hosts proprios sem carregar toda a documentacao a cada tarefa.

Exemplos opcionais: examples/openai_agents_adapter.py, examples/langgraph_adapter.py e examples/crewai_adapter.py.

A v0.4.0 tambem adicionou gate e orcamento de inteligencia:

risco -> complexidade -> capacidade planejada -> inteligencia suficiente

O framework marca como falha o uso de skill, MCP ou ferramenta fora do plano. Troca real de modelo depende do host, mas a politica de escolha fica explicita.

A v0.6.1 adicionou uma politica explicita de custo e qualidade:

risco -> barra de qualidade -> contexto minimo -> inteligencia suficiente -> validacao

Economia so e aceita quando a barra de qualidade, seguranca, escopo e validacao continuam preservados.

O Prompt melhorado da IA tambem segue essa regra: deve ser curto, mas em tarefa tecnica precisa indicar acao, alvo, limite de escopo, sucesso esperado e validacao.

Quando risco, rota ou capacidade opcional importam, o PM pode adicionar Abrir: e Usar: com poucas entradas indispensaveis. Isso orienta execucao sem listar catalogo de arquivos, skills ou MCPs.

Status

Operational alpha under active development.

The project already includes npm/PyPI packages, local onboarding, risk routing, memory, context budgeting, selective validation, tool gating, local enforcement, a runtime adapter, examples for agent frameworks, and consent-based real-run feedback.

Even so, the protocol is not a security guarantee and does not replace human review. Critical tasks still require technical judgment, real validation, host sandboxing, and explicit confirmation for sensitive actions.

Estrutura

• AGENTS.md: instrucao principal para agentes no projeto.
• INDEX.yaml: mapa estruturado para navegacao rapida.
• canonical-state.yaml: estado atual resumido e ordem de verdade.
• context-map.yaml: dominios, aliases e arquivos candidatos.
• config.yaml: configuracao do alvo atual e versao do protocolo.
• decisions/: decisoes importantes com status.
• memory/: preferencias, estado e padroes duraveis validados.
• candidate-memory/: inferencias ainda nao autoritativas.
• capabilities/: registro pequeno de skills, MCPs e ferramentas conhecidas.
• ai-protocol-enforcement/: gateway local e politica executavel.
• behavior/: contrato comportamental observavel introduzido na v0.4.0.
• dataset/: sementes de exemplos para fine-tuning futuro.
• docs/: explicacoes conceituais em Markdown.
• protocol/: regras operacionais curtas em YAML.
• protocol/cost-quality-policy.yaml: economia sem perda da barra de qualidade.
• protocol/runtime-adapter.yaml: contrato para hosts e frameworks.
• protocol/route-packs.yaml: resumos compactos para reduzir leitura por rota.
• cases/: casos estruturados para testar o comportamento da IA.
• examples/: exemplos humanos de uso do framework.
• schema/: contratos para manter os YAML padronizados.
• eval/: rubrica e exemplos de avaliacao.
• scripts/: automacoes de instalacao, validacao e avaliacao.
• responses/: exemplos de respostas para avaliacao.
• benchmarks/: comparacoes, incluindo public-protocol-comparison.md.
• docs/28-comparativo-frameworks.md: comparacao com Agents SDK, LangGraph e CrewAI.
• model-runs/: respostas reais por modelo para comparacao.
• real-runs/: templates ou registros de execucoes reais auditaveis.
• dist/minimal/: pacote minimo gerado para instalar em outros projetos.

Como usar como agente

O host carrega AGENTS.md. Depois disso:

1. Leia INDEX.yaml.
2. Confirme alvo e versao em config.yaml.
3. Leia protocol/fast-path.yaml.
4. Use protocol/router.yaml para escolher o menor contexto suficiente.
5. Consulte protocol/route-packs.yaml antes dos YAML completos.
6. Leia canonical-state.yaml e context-map.yaml so quando importarem.
7. Abra arquivos completos apenas quando o resumo compacto nao bastar.
8. Execute, valide e entregue com evidencia.
9. Atualize memoria apenas quando surgir um fato duravel e seguro.
10. Carregue apenas capacidades necessarias para resultado e validacao.

Regra de seguranca:

A IA pode expandir contexto.
A IA nao pode expandir escopo.

Aliases, mapas e decisoes ajudam a navegar. Eles nao substituem verificacao no codigo ou nos arquivos atuais antes de alterar comportamento.

Documentacao

Use docs/ para entender conceitos, limites e comportamento do framework. Use protocol/ quando quiser consultar as regras operacionais aplicadas pela IA. O indice em docs/README.md organiza os assuntos disponiveis.

Instalacao em outro projeto

Com pacote publicado:

ai-protocol init .
ai-protocol install .
ai-protocol verify .

Com setup local consentido:

ai-protocol setup-local C:\caminho\projeto --yes --real-tests accept

Previa sem alterar arquivos:

ai-protocol install . --dry-run

Instalacao a partir deste checkout:

.\install.ps1 C:\caminho\projeto -Force
npm run install-protocol -- C:\caminho\projeto
python scripts/install_protocol.py --target C:\caminho\projeto --force
python scripts/verify_install.py --target C:\caminho\projeto

O final esperado da verificacao e PASS.

No primeiro contato apos a instalacao, a IA mostra um onboarding curto. O usuario escolhe separadamente se permite reforcar regras locais do host e se participa dos testes reais. Quando autorizado, a propria IA aplica a escolha; o usuario nao precisa executar comandos adicionais. O AGENTS.md base ja faz parte da instalacao; o aceite adiciona reforcos para os demais hosts suportados. O setup precisa retornar ONBOARDING_VERIFY:PASS antes de continuar.

Depois do onboarding, a IA le apenas o estado curto. Checks de compliance, reparo, feedback e integracao com IDEs sao condicionais para evitar custo recorrente de contexto.

Modo strict com bloqueio executavel:

ai-protocol strict-status C:\caminho\projeto
ai-protocol preflight C:\caminho\projeto --plan plan.json
ai-protocol check-call C:\caminho\projeto --input call.json
ai-protocol run-checks C:\caminho\projeto --plan plan.json --report report.json
ai-protocol run --target C:\caminho\projeto --plan plan.json --call call.json --report report.json --npm-script test
ai-protocol run-auto --target C:\caminho\projeto --risk 1 --npm-script test

Atualizacao pelos pacotes publicados:

npm install -g ai-execution-protocol@latest
python -m pip install --upgrade ai-execution-protocol
ai-protocol install C:\caminho\projeto
ai-protocol verify C:\caminho\projeto

Detalhes de runner, hooks, IDEs, feedback consentido, plan.json e report.json ficam nos docs e nos arquivos operacionais em protocol/.

Testes reais consentidos

A instalacao cria ai-protocol-feedback/, uma pasta visivel para consentimento e registros locais. No primeiro contato, o onboarding oferece uma escolha independente para testes reais. Depois do aceite, a IA registra os resumos e, quando houver framework local configurado, sincroniza com real-runs/received/. Nada e coletado antes da confirmacao e nao existe upload remoto.

Em estado normal, essa camada le apenas consent.json. O aviso completo e o protocolo detalhado sao condicionais, evitando custo recorrente de contexto.

Consulte docs/25-testes-reais-com-consentimento.md.

Suporte

Encontrou um bug? Abra uma issue no GitHub: https://github.com/rodneigk2/ai-execution-protocol/issues

Feature request: comente em uma issue existente ou crie uma nova com a tag [FEATURE].

Licenca

Distribuido sob a licenca MIT. Veja LICENSE.