Metadata-Version: 2.4
Name: ai-execution-protocol
Version: 0.10.0
Summary: 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.
Author: AI Execution Protocol
License-Expression: MIT
Project-URL: Homepage, https://github.com/rodneigk2/ai-execution-protocol
Project-URL: Repository, https://github.com/rodneigk2/ai-execution-protocol.git
Project-URL: Issues, https://github.com/rodneigk2/ai-execution-protocol/issues
Keywords: ai,agent,codex,agent-safety,context-management,protocol,risk,validation,prompt,guardrails,observability
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Dynamic: license-file

# 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 AEP nao depende de controle exclusivo da IDE para ser util. O modo normal em
hosts comuns e `wrapped_enforced`: o protocolo governa os caminhos que passam
por `ai-protocol run`, hooks, CI, proxy, MCP ou adapter, e declara ferramentas
diretas restantes como `governed_bypass`. `host_enforced` e uma prova adicional
para hosts que conseguem esconder ou rotear todas as ferramentas, nao um
pre-requisito para usar o AEP.

## 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](./docs/28-comparativo-frameworks.md).

## Fluxo Principal

```text
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 |

`wrapped_enforced` e o alvo operacional principal para hosts que nao oferecem
controle exclusivo. Nessa condicao, o AEP trabalha sobre a impossibilidade de
mandar em todas as ferramentas: ele reduz a superficie governando os caminhos
controlados, exige relato de acoes fora do wrapper e mantem
`host_direct_tool_bypass` como risco residual explicito.

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

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

## Instalacao

Instale com npm:

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

Prepare dependencias basicas do ambiente:

```powershell
ai-protocol bootstrap check
ai-protocol bootstrap plan --include-optional
ai-protocol bootstrap install --yes
```

O `bootstrap` segue o padrao de CLIs modernas: detecta Python, Node.js, npm,
Git e ripgrep, reaproveita o que ja existe e so instala pacotes do sistema com
confirmacao explicita. Dependencias opcionais como GitHub CLI e Docker entram
apenas com `--include-optional`.

Ou com Python:

```powershell
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:

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

Ative automacao local estrita depois de consentimento explicito:

```powershell
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:

```powershell
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
```

Quando o mesmo host MCP atende mais de um projeto, ative o alvo atual sem
editar a configuracao global:

```powershell
ai-protocol host activate C:\path\to\project
```

O MCP gerado tambem aceita `project_root`/`target` nas tools e valida que o
alvo contem `AGENTS.md` e `protocol/fast-path.yaml`. Se nao conseguir resolver
um projeto AEP valido, ele falha fechado em vez de executar no repositorio
errado.

## Quickstart De 60 Segundos

```powershell
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:

```powershell
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:

```powershell
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.

## Baseline inspirado no Hermes Agent

O AEP v0.10.0 incorpora um baseline operacional inspirado no Hermes Agent, mas
mantem a diferenca central do AEP: tudo entra com gate, auditoria e limite
explicito.

- `bootstrap`: detecta e prepara dependencias basicas do ambiente.
- `memory`: registra memoria candidate-first antes de aprovar conhecimento.
- `skill`: audita skills sem conceder ferramentas automaticamente.
- `board`: cria um Kanban local para tarefas persistentes de agentes.
- `mcp`: lista e audita catalogo de servidores MCP por risco.
- `model`: escolhe tier de modelo por risco e tarefa.
- `sandbox`: planeja backend local, Docker, WSL ou SSH sem substituir gates.
- `monitor`: registra checks recorrentes locais.
- `lsp`: roda diagnosticos semanticos minimos por arquivo.
- `guard`: verifica segredos e politica de rede para tarefas sensiveis.

Esses comandos sao o baseline integrado. Eles nao prometem autonomia irrestrita
nem isolamento fisico quando o host nao fornece essa fronteira.

## Runtime Adapters

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

- [Guia OpenAI Agents SDK](./docs/29-use-com-openai-agents-sdk.md)
- [Guia LangGraph](./docs/30-use-com-langgraph.md)
- [Guia CrewAI](./docs/31-use-com-crewai.md)
- [Templates de stack](./docs/34-stack-templates.md)
- [Prontidao de implementacao de host](./docs/35-host-implementation-readiness.md)
- [Configuracao MCP em IDEs](./docs/36-configuracao-mcp-ides.md)

Exemplos de adapters:

- [examples/openai_agents_adapter.py](./examples/openai_agents_adapter.py)
- [examples/langgraph_adapter.py](./examples/langgraph_adapter.py)
- [examples/crewai_adapter.py](./examples/crewai_adapter.py)
- [examples/adapter_quickstart_smoke.py](./examples/adapter_quickstart_smoke.py)

## Observabilidade

Execucoes controladas podem gravar um trace local em:

```text
.ai-protocol-run/trace.jsonl
```

Resuma o trace:

```powershell
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:

```powershell
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

```powershell
ai-protocol verify C:\path\to\project
ai-protocol --version
ai-protocol bootstrap check
ai-protocol memory status C:\path\to\project
ai-protocol board list C:\path\to\project
ai-protocol skill list C:\path\to\project
ai-protocol mcp catalog C:\path\to\project
ai-protocol model route --task "publicar pacote" --risk 3
ai-protocol sandbox plan --backend docker --risk 3
ai-protocol monitor list C:\path\to\project
ai-protocol lsp check C:\path\to\project --file package.json
ai-protocol guard network --task "publish pacote" --risk 3
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 host activate C:\path\to\project
ai-protocol agent status C:\path\to\project --request "corrigir bug de auth" --risk 2
ai-protocol codex profile plan --target C:\path\to\project --preset coding
ai-protocol codex profile auto --target C:\path\to\project --task "corrigir testes" --yes
ai-protocol codex profile apply --target C:\path\to\project --preset coding --yes
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`.

Use `codex profile` para preparar `.codex/config.toml` por projeto com skills
ligadas ou desligadas por preset. O comando escreve apenas um bloco gerenciado,
faz backup antes de alterar e exige reiniciar o Codex para a sessao carregar a
nova configuracao. Isso reduz contexto; permissoes reais continuam dependendo
de host, gateway, sandbox e politicas de ferramenta.
Use `codex profile auto --task "<pedido>" --yes` para escolher automaticamente
entre `coding`, `docs`, `data` e `design` antes de iniciar ou reiniciar a
sessao do Codex.

Gere artefatos estritos em vez de escrever JSON manualmente:

```powershell
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:

```powershell
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](./LICENSE).
