agentic-hil 0.2.2

Agentic Hardware-in-the-Loop (Agentic HIL) tools for AI-assisted embedded firmware loops

Agentic HIL

Your AI agent can develop firmware on its own — because Agentic Hardware-in-the-Loop (Agentic HIL) closes the loop with real hardware.

+--> build --> flash --> stimulate --> observe --+
|                                                |
+<-------------- diagnose & fix -----------------+

  your agent, unattended -- you review the pull request

Agentic HIL is a Python package that exposes bounded MCP tools for probing, flashing, resetting, artifact validation, serial and CAN stimulus/feedback, test adapters, reports, and logs — without giving an agent arbitrary host or debugger access. A project-local policy file (.agentic-hil/config.yaml) defines exactly which devices, actions, paths, and limits are allowed. That policy gate is what makes unattended hardware access workable in the first place.

HardCI adapters are the reference hardware for Agentic HIL: physical pytest fixtures for sensor simulation, loads, and fault injection.

Names: the Python distribution/install target, CLI command, repository URL, MCP server name, and docs prose use agentic-hil. Python imports, pytest plugin names, fixtures, and Python examples use agentic_hil.

Install

The easiest path: copy/paste this prompt to your AI agent:

Install from https://github.com/hp-8472/agentic-hil and set it up for this project.

Agents follow AI_AGENT_QUICKSTART.md — everything installs user-local, no admin rights required, ever.

If you want to install it yourself anyway, install the Python package with pip and then use the agentic-hil command:

pip install agentic-hil
agentic-hil --version

If that fails because Python is externally managed, agentic-hil is not on PATH, or the package is unavailable through that interpreter, use the uv/pipx paths below instead. Never use pip install --break-system-packages.

Without installing anything (no PATH changes; needs uv or pipx):

uvx --from agentic-hil agentic-hil --version
uvx --from git+https://github.com/hp-8472/agentic-hil agentic-hil --version

Alternative isolated user-local install (recommended when the MCP client needs a stable command on PATH):

uv tool install agentic-hil      # or: pipx install agentic-hil
agentic-hil init
agentic-hil doctor
agentic-hil mcp-config --output .mcp.json

For direct PEAK/SocketCAN access install the CAN extra: uv tool install 'agentic-hil[can]'. See TROUBLESHOOTING.md when something does not start.

Why

A green build is not enough in embedded development: firmware has to behave correctly on the real board. Classic tools automate single steps — flash here, read a log there — but the moment real hardware has to respond, a human is back in the loop. Handing an agent a raw debugger shell or direct serial access instead is neither safe nor reproducible. Agentic HIL closes the gap with a small, auditable gate:

AI agent / CI  ──MCP (stdio)──▶  Agentic HIL  ──policy check──▶  OpenOCD / pyOCD / STM32CubeProgrammer
                                    │                        serial ports (pyserial)
                                    │                        CAN (PEAK / SocketCAN / bridge)
                                    ▼
                       structured results, reports, logs

Every hardware action is validated against the project policy, executed with timeouts, logged to .agentic-hil/logs/, and answered with a structured JSON result (ok, error_type, summary, likely_causes, report_path, log_path) that an agent can act on.

MCP Entry

Project-local .mcp.json:

{
  "mcpServers": {
    "agentic-hil": {
      "command": "agentic-hil",
      "args": ["mcp-stdio", "--config", ".agentic-hil/config.yaml"]
    }
  }
}

Configuration

agentic-hil init writes a starter .agentic-hil/config.yaml. The file is the policy — it names the target, the debugger backend, allowed artifact roots, named serial ports and CAN buses, and per-action permissions:

target:
  name: "sensor-board"
  controller: "stm32f4"

debugger:
  type: "openocd"            # or "pyocd" (most Cortex-M targets), or "stlink" (STM32CubeProgrammer CLI)
  interface_cfg: "interface/stlink.cfg"
  target_cfg: "target/stm32f4x.cfg"
  timeout_s: 60

artifacts:
  allowed_roots: ["build"]   # firmware may only be flashed from here
  allowed_extensions: [".elf", ".hex", ".bin"]

com_ports:
  dut_uart:
    device: "/dev/ttyACM0"
    baudrate: 115200

can_buses:
  dut_can:
    adapter: "socketcan"     # or "peak", or "process" for a custom bridge
    channel: "can0"
    bitrate: 500000

adapters:
  ntc_sim:                   # sensor/actuator/fault-simulation bridge
    executable: "examples/adapters/sim_ntc_adapter.py"
    channels: ["temperature", "resistance"]
    faults: ["open", "short_to_gnd", "short_to_vcc"]

permissions:
  allow_flash: true
  allow_com_write: true
  allow_can_write: true
  allow_adapter_write: true
  allow_raw_debugger_commands: false
  allow_mass_erase: false

The MCP server reloads and validates this policy before every tool call, so configuration changes take effect without restarting the client. Invalid edits fail closed instead of continuing with the previously loaded policy.

Export the full JSON schema with agentic-hil schema --output agentic-hil-config.schema.json.

MCP Tools

Group	Tools	Notes
Debugger	debugger_info, probe_target, reset_target	OpenOCD, pyOCD, or STM32CubeProgrammer CLI
Firmware	flash_firmware, artifact_upload	artifacts are validated (path, extension, format, SHA-256) before flashing; post-flash reset requires reset_after_flash: true
Serial	com_ports_list, com_session_start, com_session_stop, com_write, com_read	named ports only, buffered background reader
CAN	can_buses_list, can_session_start, can_session_stop, can_send, can_read	PEAK, SocketCAN, or a process bridge
Test adapters	adapters_list, adapter_session_start, adapter_session_stop, adapter_set_value, adapter_inject_fault, adapter_clear_fault, adapter_measure	sensor/actuator/fault simulation via the adapter bridge protocol
Diagnostics	get_last_report, classify_last_error	structured error classification with likely causes
Debug sessions	debug_* (start/stop/status, breakpoints, continue/halt, symbol info, memory dump)	typed GDB/MI sessions via the OpenOCD backend's gdbserver; unexpected breakpoints and target exceptions are returned as structured stop reasons; symbol allowlist and dump-size limits come from the debug: policy section

A typical loop: build firmware → flash_firmware with reset_after_flash: true when a fresh boot is required → com_session_start → stimulate via com_write/can_send/adapter_set_value → assert on com_read/can_read/adapter_measure → on failure, classify_last_error.

Test Adapters

Real-world firmware bugs show up under electrical conditions that standard lab tools cannot reproduce on demand: an open or shorted sensor, a drifting NTC, a missing load, a bouncing contact. The adapters: section connects Agentic HIL to test adapters that simulate exactly these states — physical adapter hardware or pure-software simulators, both speaking the same JSON bridge protocol.

Example diagnosis loop with the bundled NTC simulator (examples/adapters/sim_ntc_adapter.py): flash the firmware, set the simulated sensor to 25 °C and assert nominal behavior, inject an open fault and assert the firmware reports the sensor failure, clear the fault and assert recovery — every step automated, reproducible, and policy-gated.

Safety Model

• The agent never gets a shell, a raw debugger, or a device path — only the named, configured resources.
• Firmware artifacts must live under artifacts.allowed_roots, match an allowed extension, pass format plausibility checks, and are hashed before flashing. Path traversal is rejected.
• Permission switches gate high-risk action classes; permission_denied results are authoritative and agents are instructed to stop (see AGENTS.md).
• Deliberate interlock: flashing is refused while allow_raw_debugger_commands or allow_mass_erase is enabled — validated flashing and unrestricted debugger access are mutually exclusive policies.
• Serial/CAN writes are size-capped (max_write_bytes, max_frame_data_bytes); reads are buffer-capped. Debugger calls run with timeouts and TCP servers disabled (OpenOCD gdb_port/tcl_port/telnet_port disabled); only a typed debug session opens a gdb_port, bound to localhost on an ephemeral port for exactly that session, and it is torn down with the session.
• Test adapter channels and fault names are explicit allowlists — Agentic HIL rejects anything not named in the config before it reaches the adapter bridge.
• All actions log to .agentic-hil/logs/ and write a structured report to .agentic-hil/reports/.

pytest Plugin

Installing agentic-hil registers the agentic_hil pytest plugin, so CI regression suites can drive the same policy-gated tools without an MCP client:

def test_open_sensor_diagnosis(agentic_hil):
    started = agentic_hil.call("adapter_session_start", {"adapter_id": "ntc_sim"})
    assert started["ok"] is True
    injected = agentic_hil.call("adapter_inject_fault", {"adapter_id": "ntc_sim", "fault": "open"})
    assert injected["ok"] is True
    # ...assert the firmware's reaction via com_read...

The agentic_hil fixture loads .agentic-hil/config.yaml relative to the pytest rootdir (override with --agentic-hil-config or the agentic_hil_config ini option). Tests are skipped when no configuration file exists, but an existing invalid configuration fails loudly — a config typo must not silently disable the hardware suite in CI. Adapter, COM, and CAN sessions opened during a test are stopped afterwards so stimulus state cannot leak between tests. See examples/pytest/ for a full diagnosis-loop example, and examples/nucleo-f446re_demo/ for the complete loop on real hardware: a bare-metal STM32 firmware that is built, flashed, reset, and asserted on via its UART boot banner.

Common Commands

agentic-hil init
agentic-hil doctor
agentic-hil com-ports
agentic-hil mcp-config --output .mcp.json
agentic-hil mcp-stdio --config .agentic-hil/config.yaml
agentic-hil com-stdio --config .agentic-hil/config.yaml --port dut_uart
agentic-hil schema --output agentic-hil-config.schema.json
agentic-hil skill-install --agent opencode

Platform Support

Linux, macOS, and Windows (CI-tested on Python 3.10–3.13). Debugger backends: OpenOCD, pyOCD (agentic-hil[pyocd] — covers most ARM Cortex-M targets via CMSIS packs and CMSIS-DAP/ST-Link/J-Link probes, set debugger.target_type), and STM32CubeProgrammer CLI (auto-discovered on Windows). Direct CAN requires agentic-hil[can] (python-can); any other adapter can be attached through the process bridge protocol.

Development

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

The package is configured for PyPI publishing through GitHub trusted publishing in .github/workflows/workflow.yml.

Security

Policy bypasses are treated as vulnerabilities — see SECURITY.md.

License

Apache-2.0 — see LICENSE.