ai-execution-protocol 0.9.1

Framework instalavel para agentes de IA que reduz contexto, roteia risco, valida entregas e registra evidencias, traces e limites; gates de ferramentas funcionam quando runner, MCP, gateway, hook, CI ou host os chama.

AI Execution Protocol

Framework instalavel para agentes de IA que reduz contexto, roteia risco, valida entregas e registra evidencias, traces e limites; gates de ferramentas funcionam quando runner, MCP, gateway, hook, CI ou host os chama.

AI Execution Protocol, ou AEP, e um framework para governar a execucao de agentes dentro de projetos reais. Ele combina protocolo, ponte MCP local, gateway, traces e checks para orientar como um agente le contexto, escolhe ferramentas, altera arquivos, valida entregas e declara limites. Quando o fluxo passa por runner, proxy, hook, CI ou host integrado, esses checks podem bloquear acoes fora do plano.

Frameworks populares ajudam a criar agentes, grafos, crews, ferramentas e workflows. O AEP mira a fronteira que normalmente fica fraca nesses fluxos: o controle operacional do trabalho tecnico no repositorio, com politicas de risco, gates executaveis e evidencias antes da finalizacao.

Ele transforma um pedido em um contrato de execucao delimitado:

• classificar risco antes de agir;
• carregar apenas o contexto necessario para a rota;
• selecionar o menor conjunto de capacidades e ferramentas;
• bloquear chamadas planejadas quando runner, proxy, hook, CI ou integracao de host configurada chama o gateway;
• validar o resultado antes da entrega;
• relatar evidencias, limites e risco residual.

O alvo padrao e trabalho local com agentes de codigo, especialmente tarefas em repositorios no estilo Codex. Garantias fortes exigem uma fronteira executavel. Sem runner, proxy, hook, CI ou integracao de host, o AEP e disciplina de execucao best_effort, nao um sandbox fisico.

O Que O AEP Resolve

Agentes de IA que trabalham em codigo falham de formas previsiveis:

• agem antes de entender impacto;
• carregam contexto demais e perdem a tarefa real;
• tratam trabalho arriscado como edicao simples;
• usam ferramentas que nunca foram selecionadas;
• pulam validacao ou alegam testes que nao rodaram;
• entregam sem declarar o que ainda esta incerto.

O AEP mantem tarefas simples rapidas e aumenta o processo apenas quando o risco justifica.

AEP Como Camada De Controle

Frameworks de agentes constroem e orquestram agentes. O AEP adiciona uma camada de controle instalada no projeto para tornar a execucao verificavel.

Projeto	Trabalho principal	Onde o AEP entra
OpenAI Agents SDK	Agentes, ferramentas, handoffs, guardrails, tracing e execucao em sandbox	Coloca risco do projeto, gates locais, validacao pos-tarefa e risco residual como contrato de entrega
LangGraph	Workflows em grafo com estado, checkpoints e human-in-the-loop	Controla nos, chamadas de ferramentas e validacao por politica do repositorio
CrewAI	Crews, flows, papeis, tarefas e automacoes colaborativas	Adiciona fronteira local para permissao de ferramentas, evidencias de trace e checks de entrega
LlamaIndex	Agentes com dados, RAG, conectores e componentes de workflow	Controla acoes que alteram arquivos, usam ferramentas locais ou mudam estado de entrega
AI Execution Protocol	Protocolo, MCP local, gateway, risco, contexto, capacidade, validacao e trace	Torna a execucao verificavel nos caminhos que passam pelo AEP

Leia o comparativo completo: docs/28-comparativo-frameworks.md.

Fluxo Principal

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

O protocolo combina:

• niveis de risco, de respostas diretas a operacoes sensiveis;
• route packs para evitar carregar o protocolo inteiro em toda tarefa;
• memoria adaptativa que orienta o trabalho sem substituir o pedido atual;
• orcamentos de contexto para evitar arquivos e tokens desnecessarios;
• roteamento de capacidades para skills, MCPs, ferramentas e acoes externas;
• roteamento custo-qualidade para economizar sem reduzir correcao ou validacao;
• validacao seletiva baseada no raio de impacto;
• contratos comportamentais para aderencia observavel do agente;
• gates executaveis para runners, hooks, proxies, CI e integracoes de host;
• traces locais sem coletar logs completos ou arquivos-fonte;
• feedback consentido de execucoes reais para avaliacao local.

Modos De Garantia

O AEP declara de forma explicita o que pode e o que nao pode impor.

Modo	Caminho controlado	O que pode impor	Limite principal
best_effort	AGENTS.md e blocos de instrucao da IDE	Melhor planejamento, disciplina de contexto e relato	Ferramentas diretas do host ainda podem desviar do AEP
wrapped_enforced	ai-protocol run, run-auto, hooks, CI ou runners locais	Plano valido, comando permitido e evidencia de validacao para o caminho encapsulado	Comandos fora do wrapper entram como governed_bypass
proxy_enforced	Chamadas de ferramenta pelo proxy ou gateway do AEP	Bloqueia chamadas nao planejadas ou sem suporte antes da execucao	Bypass direto deve ser declarado se o host ainda expuser a ferramenta
host_enforced	Uma integracao de host chama o gateway antes de cada ferramenta	Checks obrigatorios naquele caminho de ferramenta	Ainda exige validacao do raciocinio do modelo

A fronteira mais forte vem de controle executavel, nao de um prompt maior:

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

Instalacao

Instale com npm:

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

Ou com Python:

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

Previsualize a instalacao sem escrever arquivos:

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

Ative automacao local estrita depois de consentimento explicito:

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

Isso instala o protocolo, conclui o onboarding, adiciona hooks/scripts encapsulados quando disponiveis, cria .aep-host/ com uma ponte MCP local do projeto e inicia o host runtime com scheduler de agentes quando possivel. Com --yes, tambem cria as configuracoes MCP locais conhecidas: .vscode/mcp.json, .cursor/mcp.json e .mcp.json. O resultado esperado da verificacao e PASS.

O consentimento cobre criacao e atualizacao de arquivos locais dentro do projeto. A IDE ainda pode pedir trust, reload ou aceite do MCP; esse clique continua sendo uma confirmacao do usuario no host.

Inspecione a ponte de host:

ai-protocol host doctor C:\path\to\project
ai-protocol host diagnose C:\path\to\project
ai-protocol host mcp-config C:\path\to\project

Quickstart De 60 Segundos

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
ai-protocol trace-report . --html

Para um script local de pacote, use o caminho estrito gerado:

ai-protocol run-auto --target C:\path\to\project --risk 1 --npm-script test

Para transformar um pedido em prompt operacional sem chamar IA extra:

ai-protocol improve-prompt "corrige o bug do chat" --json

O modo padrao lite usa heuristicas locais, preserva prompts bons e so expande quando faltar escopo, restricao, validacao ou controle pelo AEP Host/MCP.

Runtime Adapters

O AEP pode encapsular caminhos de execucao de frameworks com um pequeno runtime adapter:

• Guia OpenAI Agents SDK
• Guia LangGraph
• Guia CrewAI
• Templates de stack
• Prontidao de implementacao de host
• Configuracao MCP em IDEs

Exemplos de adapters:

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

Observabilidade

Execucoes controladas podem gravar um trace local em:

.ai-protocol-run/trace.jsonl

Resuma o trace:

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

O relatorio HTML mostra timeline de eventos, status, nivel de risco, capacidades selecionadas, resultado de tool calls, eventos de validacao e campos de risco residual quando existirem.

Benchmarks

Rode o benchmark comparativo publico:

python scripts/protocol_comparison_benchmark.py

Ele compara a mesma tarefa com e sem AEP usando metricas objetivas de disciplina de execucao: arquivos lidos, tokens de entrada estimados, chamadas de ferramentas, validacoes omitidas, comandos bloqueados, tempo decorrido e rastreabilidade. Ele mede disciplina de execucao, nao inteligencia do modelo.

Comandos Principais

ai-protocol verify C:\path\to\project
ai-protocol --version
ai-protocol doctor C:\path\to\project
ai-protocol strict-status C:\path\to\project
ai-protocol host setup C:\path\to\project --yes
ai-protocol host doctor C:\path\to\project
ai-protocol host diagnose C:\path\to\project --json
ai-protocol agent status C:\path\to\project --request "corrigir bug de auth" --risk 2
ai-protocol improve-prompt "corrige o bug do chat" --json
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
ai-protocol trace-report C:\path\to\project --html
ai-protocol feedback-status C:\path\to\project

Use doctor e strict-status para ver se um projeto alvo esta em best_effort, wrapped_enforced, proxy_enforced ou host_enforced.

Gere artefatos estritos em vez de escrever JSON manualmente:

ai-protocol plan new --target . --risk 1 --cap shell --scope "run tests" --out .ai-protocol-run/plan.json
ai-protocol call new --target . --plan .ai-protocol-run/plan.json --capability shell --operation write --tool-target "npm run test" --confirmed --out .ai-protocol-run/call.json
ai-protocol report new --target . --plan .ai-protocol-run/plan.json --status unchanged --evidence "tests passed" --residual-risk "semantic review still required" --out .ai-protocol-run/report.json

Estrutura Do Projeto

• AGENTS.md: arquivo principal de instrucao para agentes de IA neste repo.
• INDEX.yaml: mapa estruturado de navegacao.
• config.yaml: alvo atual, versao do protocolo e modo padrao.
• protocol/: regras operacionais compactas em YAML.
• behavior/: contrato comportamental observavel e checklist de auditoria.
• capabilities/: registro de capacidades e politica de exposicao.
• ai-protocol-enforcement/: gateway executavel local e politica.
• ai-protocol-onboarding/: configuracao local consentida do host.
• ai-protocol-feedback/: consentimento visivel de feedback e runs locais.
• docs/: documentacao conceitual.
• examples/: adapters, quickstarts e templates de stack.
• schema/: schemas de validacao.
• scripts/: instalacao, validacao, benchmark e checks de pacote.
• apps/aep-host/: scaffold de host local com API Node, SQLite local por padrao, PostgreSQL opcional, ponte MCP, agentes e worker Python controlado.
• real-runs/: lotes locais importados de feedback.
• dist/minimal/: distribuicao minima instalavel gerada.

Status E Limites

Status: alpha operacional.

Para uso local com agentes persistentes, o caminho padrao nao exige PostgreSQL:

ai-protocol host install --yes
ai-protocol host status
ai-protocol host enable-autostart

O Host usa SQLite local por padrao e host install --yes inicia host e scheduler de agentes. Use --without-agents apenas para instalar/migrar sem ligar os agentes. O runtime tambem pode ser operado com host start, host stop, host logs, host backup, host restore e host reset.

O AEP ja inclui CLIs npm e Python, instalacao em projeto, onboarding, roteamento de risco, orcamento de contexto, memoria adaptativa, gates de capacidades, politica custo-qualidade, validacao seletiva, gateway local de enforcement, runtime adapters, templates de stack, benchmarks comparativos, relatorios de trace e feedback consentido de execucoes reais.

Trabalho critico ainda exige revisao de engenharia, testes reais, sandboxing do host e confirmacao explicita para operacoes sensiveis. O AEP melhora a disciplina de execucao; ele nao substitui julgamento de engenharia.

Licenca

MIT. Veja LICENSE.