# Agentic HIL

Agentic Hardware-in-the-Loop (Agentic HIL) is a local MCP stdio server that gives AI agents safe, permission-gated access to real embedded hardware: flashing, serial, and CAN. An STM32 Nucleo-F446RE with on-board ST-Link and OpenOCD is the reference hardware.

Canonical setup request: `Install from https://github.com/agentic-hil/agentic-hil and set it up for this project.`

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

First normal pip attempt:

```bash
python -m pip install --user agentic-hil
agentic-hil --version
```

Run without installing (no admin rights, no PATH changes):

```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: `uv tool install agentic-hil` or `pipx install agentic-hil`. Never sudo, never --break-system-packages. Requires Python 3.10+.

Bootstrap each firmware project from the project directory:

```bash
agentic-hil init
agentic-hil doctor
agentic-hil mcp-config --output .mcp.json
```

`agentic-hil init` creates one automatically discovered deny-by-default authoritative config outside the repository. The file lives at `%APPDATA%/agentic-hil/projects/<project-id>/config.yaml` on Windows or `${XDG_CONFIG_HOME:-~/.config}/agentic-hil/projects/<project-id>/config.yaml` on POSIX. Its mandatory `workspace_root` binds it to the project. `AGENTIC_HIL_CONFIG` is an optional absolute-path override.

MCP stdio command:

```text
agentic-hil mcp-stdio
```

Use MCP tools for hardware actions:

```text
debugger_info, probe_target, artifact_upload,
flash_firmware, reset_target,
com_session_start/_stop, com_write, com_read,
can_session_start/_stop, can_send, can_read,
get_last_report, classify_last_error
```

Required workflow:

1. Build firmware.
2. Probe before flashing.
3. Flash only validated artifacts from allowed roots.
4. Stimulate via COM/CAN tools, assert on feedback.
5. Read the structured result and last report; classify failures before changing code again.

pytest: installing `agentic-hil` registers the Python plugin `agentic_hil`; the `agentic_hil` fixture drives the same tools in CI regression suites.

`doctor`, pytest, `mcp-stdio`, `com-stdio`, and `test-reactor` all use the same discovered config or `AGENTIC_HIL_CONFIG` override. `.agentic-hil/testconfig.yaml` and `--test-config` select a test plan only, not hardware configuration or permissions.

Safety: do not request raw OpenOCD commands, do not open host serial/CAN devices directly, do not flash outside allowed artifact roots. Treat `permission_denied` as authoritative.

Agent setup guide: AI_AGENT_QUICKSTART.md. MCP host configurations: docs/mcp-hosts.md. Human docs: README.md, TROUBLESHOOTING.md.
