Agentic HIL provides policy-gated MCP tools for embedded hardware-in-the-loop testing on real devices. The Python package exposes bounded MCP capabilities for probing, flashing, resetting, artifact validation, and serial/CAN stimulus and feedback, enabling automated testing workflows against actual hardware.

🛠️ Key Features

Policy-gated MCP tools for real hardware-in-the-loop
Probing, flashing, and resetting of target devices
Artifact validation, serial and CAN stimulus/feedback
Test adapters and MCP skill integration
Open-source tooling tailored for embedded testing

🚀 Use Cases

Automated firmware development cycles with real hardware
Stimulus/feedback loops for embedded AI agents
Hardware-in-the-loop testing on devices using OpenOCD, STLink
MCP-based testing workflows for embedded firmware

⚡ Developer Benefits

Bound MCP tooling inside a Python package
Clear readme excerpt guiding setup and usage
Reusable test adapters and MCP skills for automation

⚠️ Limitations

Grounded strictly in provided data; no additional features outside readme excerpt and topics
Specific experimental details and configuration options are not described in the source excerpt

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.

code

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

text

Install from https://github.com/agentic-hil/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:

bash

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

bash

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

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

bash

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:

code

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:

json

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

Agentic HIL releases are published to the preview official MCP Registry as io.github.agentic-hil/agentic-hil, pointing to the same public PyPI package and mcp-stdio command. The registry is a discovery channel, not a substitute for project setup or policy review. The host-independent manual path remains supported:

bash

uv tool install agentic-hil
agentic-hil init
agentic-hil doctor
agentic-hil mcp-config --output .mcp.json

Registry installation never grants additional hardware access. Every action is still constrained by the project-local .agentic-hil/config.yaml; review SECURITY.md before enabling unattended hardware access.

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:

yaml

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:

python

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

text

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

bash

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.

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

Agentic HIL

Install

Why

MCP Entry

Configuration

MCP Tools

Test Adapters

Safety Model

pytest Plugin

Common Commands

Platform Support

Development

Security

License

Install