Agentic HIL

Agentic HIL

Seu agente de IA escreve o firmware, grava-o na placa sobre sua mesa, aciona UART e CAN contra ela, lê o que o hardware realmente fez e corrige o que errou; a execução na placa real é o que decide se o trabalho está concluído, e você revisa o pull request com as evidências dessa execução nele.

https://github.com/user-attachments/assets/8d39ba93-beeb-484e-b9e9-d9ce79538523

Nada nessa execução é encenado. Um único reinício após a linha de instalação, em um projeto de firmware recém-criado, a primeira frase faz o agente montar a bancada sozinho e a segunda faz a placa dizer Hello World e provar que disse: a configuração é criada via MCP com as permissões reportadas em voz alta, o firmware é escrito na hora, flash_firmware e com_read passam pelo portão, os doze bytes voltam do fio, e o plano que ele fixa é executado uma vez em verde e uma vez contra uma expectativa errada, porque um teste que não pode falhar não prova nada. O que permanece no projeto depois é o plano como um arquivo revisável e o relatório da própria execução: lease liberado, estado seguro confirmado, nada em quarentena.

Instalação

Linux / macOS (qualquer shell):

curl -LsSf https://agentic-hil.github.io/install.sh | sh

Windows, no PowerShell:

irm https://agentic-hil.github.io/install.ps1 | iex

O comando vai para o diretório bin do usuário do gerenciador de pacotes que o instalou, e o instalador pergunta a esse gerenciador onde ele foi parar em vez de assumir: uv tool dir --bin para uma instalação via uv, e o próprio interpretador selecionado para uma instalação via pip --user. Quando esse diretório não está no seu PATH ainda, o instalador o coloca lá e avisa: uma linha em cada arquivo de inicialização que seu shell lê, ou no Windows o diretório na frente do seu próprio Path. Abra um novo shell e o comando está lá. Passe --no-path (-NoPath no PowerShell) para manter essa edição só para você, e o instalador imprime a linha exata em vez disso.

Uma linha instala o pacote local ao usuário e registra a habilidade do agente e o servidor MCP para cada CLI de agente que encontrar no seu PATH. Nunca são necessários direitos de administrador, e ele não toca em nada dentro de nenhum repositório. Se não encontrar nenhuma CLI de claude, codex ou opencode lá, ele avisa e não escreve nada de nenhum agente: instale a CLI do agente e depois execute agentic-hil agent-install --agent <claude-code|codex|opencode> você mesmo, que é a linha que o instalador imprime para esse caso. Então reinicie seu agente uma vez, e após esse único reinício seu agente configura este projeto sozinho, na primeira pergunta de hardware que você fizer a ele.

A linha acima e a rota com soma de verificação em instalação executam o mesmo instalador, e em uma máquina sem nada aqui ainda ambos instalam a mesma coisa, o release do PyPI: o script resolve agentic-hil[can] contra o índice de pacotes e não carrega nenhuma branch ou referência git, e --version <x.y.z> fixa exatamente um release. Em uma nova execução, ele repara o que já está instalado em vez de forçar o release público por cima: uma instalação que reporta uma versão .devN (um checkout editável deste repositório) é mantida intocada, e uma ferramenta gerenciada por uv instalada de um caminho, URL ou referência git é atualizada da mesma fonte registrada em vez de trocada para o índice. O que a rota com soma de verificação adiciona é o próprio script, lido antes de executar: install.sh e seu install.sh.sha256 vêm do mesmo release, um é verificado contra o outro, e o arquivo que executa é o arquivo que você verificou.

O starter STM32 é o caminho mais curto para ver isso acontecer em hardware: três passos em uma Nucleo-F446RE, com o firmware, os planos de teste e um defeito plantado já no lugar.

O Claude Code também pode pegar a habilidade do marketplace de plugins: /plugin marketplace add agentic-hil/agentic-hil, depois /plugin install agentic-hil@agentic-hil. O plugin carrega a habilidade e nada mais; o próprio servidor MCP ainda vem da linha de instalação acima, que registra um caminho absoluto de executável verificado fora do seu repositório.

Instalação tem todos os outros caminhos: a grafia cmd.exe, a execução de reparo (a mesma linha de novo, que reinstala no lugar quando o próprio agentic-hil upgrade falha), essa rota com soma de verificação completa, registrar um agente em vez de todos, acionar seu próprio gerenciador de pacotes, setup para uma bancada já conectada, os extras opcionais, atualização e todas as plataformas e backends de depurador. TROUBLESHOOTING.md cobre o que fazer quando algo não inicia.

Um primeiro comando que não precisa de placa, em um clone deste repositório: agentic-hil check-plan examples/nucleo-f446re_demo/testconfig.yaml responde All 1 test plan(s) load through the reactor's loader. e sai com código 0, sem ter carregado nenhuma configuração e sem tocar em nenhum hardware.

Agentic Hardware-in-the-Loop (Agentic HIL) é um pacote Python que permite a um agente de codificação desenvolver firmware na placa real. Ele expõe ferramentas MCP limitadas para sondagem, gravação, reset, validação de artefatos, estímulo/feedback serial e CAN, relatórios e logs, tudo sem dar ao agente acesso arbitrário ao host ou ao depurador. A execução na placa é o portão: o trabalho está concluído quando o hardware se comportou, e o relatório que essa execução escreve é a evidência que um revisor lê. O que ele suporta é a sonda de depuração com seu backend em vez de uma placa, ST-Link via OpenOCD ou a CLI do STM32CubeProgrammer e sondas CMSIS-DAP via pyOCD, então qualquer placa atrás de tal sonda executa o mesmo software. Cada projeto tem exatamente uma configuração autoritativa armazenada fora do repositório, fora do alcance das ferramentas de arquivo do próprio agente.

Por quê

Um build verde não é suficiente no desenvolvimento embarcado: o firmware tem que se comportar corretamente na placa real, então a execução nessa placa é o portão que o trabalho tem que passar antes de ser concluído. Ferramentas clássicas automatizam etapas únicas (gravar aqui, ler um log ali), mas no momento em que o hardware real tem que responder, um humano volta ao loop, que é o que impede um agente de desenvolver firmware até esse portão. Entregar a um agente um shell de depurador bruto ou acesso serial direto não é seguro nem reproduzível, e deixa um revisor sem nada para ler.

O Agentic HIL fecha a lacuna com um portão pequeno e auditável:

Toda ação de hardware é validada contra a configuração autoritativa selecionada, executada com timeouts, registrada em .agentic-hil/logs/ e respondida com um resultado JSON estruturado (ok, error_type, summary, likely_causes, report_path, log_path) que um agente pode usar e um revisor pode ler depois. O que o agente pode fazer é por dispositivo e por permissão, e buscar uma saída de emergência do depurador é o que tira a gravação dele.

O que ele aciona

A unidade que ele aciona é a sonda com seu backend, não uma placa: três backends de depurador (OpenOCD, pyOCD e a CLI do STM32CubeProgrammer), além de portas seriais e CAN (PCAN, SocketCAN ou uma ponte personalizada; várias execuções podem compartilhar um barramento), em Linux, macOS e Windows, Python 3.10 ou mais novo, tudo testado em CI. O exemplo trabalhado em examples/nucleo-f446re_demo/ executa o loop inteiro em um ST Nucleo-F446RE, a placa na qual este repositório prova o caminho em vez do limite do que roda; instalação tem cada backend e plataforma em detalhe.

O reator de teste

Um plano é como o portão é escrito, e um plano YAML aciona a bancada inteira: gravar, reset, escrever, ler com um comparador (texto exato, um padrão ou uma faixa numérica sobre um valor capturado), atrasos e sessões que se fecham sozinhas. Planos nomeiam dispositivos lógicos; a configuração da bancada os vincula ao hardware real, então o mesmo plano roda inalterado em toda máquina que tenha um. Uma etapa com falha aborta a execução, e a bancada se recupera sozinha: reap, reset em halt, sonda, tudo atestado no resultado da execução. Como os planos funcionam.

Segurança por construção

Um dispositivo não existe nesta bancada até que sua configuração o declare, e uma chamada nomeando qualquer outro é recusada antes que um driver seja aberto: unknown_device onde uma execução o declara, e com_port_not_configured ou can_bus_not_configured onde uma ferramenta de porta ou de barramento o nomeia, cada uma dessas duas nomeando os que a configuração declara. Em um dispositivo que ela declara, uma configuração gerada concede toda permissão que tem uma ferramenta por trás e mantém allow_raw_debugger_commands e allow_mass_erase falsos, o par interligado que recusa gravação enquanto qualquer um for verdadeiro, falso por construção quando o MCP project_config_create gera sem configuração carregada, e o padrão agentic-hil init escreve a menos que seu agentic-hil.config.example.yaml abra um; um project_config_create regenerando uma bancada existente carrega as permissões carregadas de volta, incluindo qualquer interligação, com base no nome da entrada e não em se uma sonda foi encontrada antes, então um par que um operador abriu em um placeholder nomeado dut sobrevive à própria chamada que primeiro vincula uma sonda a ele, e apenas uma entrada lógica cujo nome a configuração carregada não carregava volta falso. agentic-hil revoke <key> retira qualquer concessão única e agentic-hil grant <key> a reabre, do seu próprio shell; via MCP, um agente estreita sua própria autoridade e nunca a amplia. Toda ação de hardware é validada, alugada em toda a máquina e escrita em uma cadeia de auditoria SHA-256. A configuração autoritativa vive fora do espaço de trabalho, onde o agente não pode editá-la. A aplicação fica na ferramenta em vez do host do agente de propósito: o sistema de permissões de um host julga strings de shell e difere por host, enquanto as permissões da bancada julgam a própria ação de hardware e viajam com a bancada, então a CLI, pytest, CI e o reator de teste todos passam pelo mesmo portão. Uma execução com falha ainda devolve a bancada: ela aborta com seu veredito, a ação de recuperação reseta e relê o alvo, e a quarentena permanente é mantida para o único estado que nenhum contato posterior pode reconstruir, uma trilha de auditoria quebrada. O modelo de segurança é a versão curta, o design de segurança é a longa.

Início rápido: uma execução real

O exemplo trabalhado é um projeto de firmware próprio. Conecte a placa, faça o build e aponte o Agentic HIL para ela a partir desse diretório:

cd examples/nucleo-f446re_demo
cmake --preset Debug && cmake --build --preset Debug   # → build/Debug/nucleo-f446re_demo.elf
agentic-hil setup --agent claude-code                  # or: codex / opencode
agentic-hil doctor

doctor verifica a configuração contra a bancada conectada e nomeia o que encontra (uma toolchain ausente, uma sonda inacessível, um tipo de alvo que este host não consegue resolver) antes que qualquer coisa seja gravada. Se a placa chegou depois que setup rodou, agentic-hil adopt-hardware preenche o serial da sonda, o executável do backend e o dispositivo COM que ele deixou sem definir (--dry-run mostra o plano primeiro). Em um host com OpenOCD e sem STM32CubeProgrammer, a sonda é lida do inventário USB serial do próprio host, então um ST-Link conectado sozinho se vincula sem ninguém redigitar seu serial; --probe-id <serial> nomeia a placa onde uma segunda sonda que não publica porta COM virtual está conectada ao lado dela.

Com o host MCP iniciado a partir desse diretório, o agente aciona quatro chamadas:

flash_firmware     {"image_path": "build/Debug/nucleo-f446re_demo.elf"}
com_session_start  {"port_id": "dut_uart"}
reset_target       {"mode": "run"}
com_read           {"port_id": "dut_uart", "wait_timeout_s": 5}
→ feedback contains "Hello World"

O mesmo loop roda headless como uma regressão pytest: pytest tests/ nesse diretório grava o ELF, reseta o alvo e afirma o banner de boot na UART. examples/nucleo-f446re_demo/ percorre ambos, e docs/testing.md cobre escrever a execução como um plano YAML revisável em vez disso.

Onde a profundidade vive

Se você quiser	Leia
instalar, atualizar, adicionar CAN ou pyOCD, ou consultar um comando	docs/installation.md
o que a configuração autoritativa declara e quem pode alterá-la	docs/configuration.md
a superfície completa das ferramentas MCP e como uma execução é composta a partir dela	docs/mcp-tools.md
registrar o servidor em um host MCP específico	docs/mcp-hosts.md
escrever testes de hardware (planos YAML ou pytest)	docs/testing.md
por que é seguro deixar um agente sozinho com a bancada	docs/safety-model.md e docs/security-design.md
uma falha diagnosticada	TROUBLESHOOTING.md
apontar seu agente para este repositório	AI_AGENT_QUICKSTART.md e AGENTS.md

Nomes: a distribuição Python/alvo de instalação, comando CLI, URL do repositório e nome do servidor MCP usam agentic-hil. Imports Python, nomes de plugins pytest, fixtures e exemplos Python usam agentic_hil.

Desenvolvimento

python -m pip install -e '.[dev]'
ruff check src tests evals tools
pytest
python -m build
twine check dist/*

O pacote está configurado para publicação no PyPI por meio de publicação confiável do GitHub em .github/workflows/workflow.yml. Diretrizes de contribuição: CONTRIBUTING.md.

Segurança

Bypasses de política são tratados como vulnerabilidades; consulte SECURITY.md.

Suporte

Linux, macOS e Windows são suportados igualmente; o que é suportado é a sonda de depuração com o backend por trás dela (ST-Link via OpenOCD ou a CLI do STM32CubeProgrammer, sondas CMSIS-DAP via pyOCD), em vez de qualquer lista de placas, e as questões são respondidas em até 24 horas em dias úteis, relatórios de segurança em até sete dias: docs/support.md é toda a promessa, incluindo o que não é prometido. Pergunte em Discussions Q&A, mostre uma execução em Show and tell e coloque uma primeira execução em sua própria bancada, verde ou vermelha, em o relatório da primeira execução.

Licença

Apache-2.0. Consulte LICENSE.