# Agentic HIL

Agentic Hardware-in-the-Loop (Agentic HIL) is a local MCP stdio server that gives AI agents safe, policy-gated access to real embedded hardware: flashing, serial, CAN, and test-adapter stimuli/fault injection. HardCI adapters are the reference hardware.

Canonical setup request: `Install from https://github.com/hp-8472/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/hp-8472/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
```

Each firmware project keeps its own `.agentic-hil/config.yaml` — the policy for that project's target, debugger, permissions, artifact roots, com_ports, can_buses, and adapters.

MCP stdio command:

```text
agentic-hil mcp-stdio --config .agentic-hil/config.yaml
```

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,
adapter_session_start/_stop, adapter_set_value,
adapter_inject_fault, adapter_clear_fault, adapter_measure,
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/adapter 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.

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

Agent setup guide: AI_AGENT_QUICKSTART.md. Human docs: README.md, TROUBLESHOOTING.md.
