Metadata-Version: 2.4
Name: ai-execution-protocol
Version: 0.8.2
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 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 nao sao cobertos |
| `proxy_enforced` | Chamadas de ferramenta pelo proxy ou gateway do AEP | Bloqueia chamadas nao planejadas ou sem suporte antes da execucao | O host precisa esconder bypass direto de ferramentas |
| `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:

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

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 e cria `.aep-host/` com uma ponte MCP local do
projeto. 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 mcp-config C:\path\to\project
```

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

## 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 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 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:

```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, schema PostgreSQL,
  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.

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).
