---
name: umec-gateway-agent
description: Operate and configure a UMEC Modbus gateway through its local HTTP API using safe agent-token authentication. Use when an AI agent needs to inspect gateway status, rotate or use Bearer tokens, add or update Modbus devices through documented API paths, run read/test/configure workflows, upload firmware, reboot, or perform other dangerous maintenance actions with explicit confirmation guards.
---

# UMEC Gateway Agent

## Operating Rules

Use the local gateway API through an operator-approved LAN address. Prefer Bearer token auth for repeated agent work. Use local admin username/password only to rotate or delete the agent token.

Never print passwords, bearer tokens, session cookies, or firmware secrets. Redact token values in summaries.

Treat these actions as dangerous and require explicit user approval plus the matching confirmation header:

- firmware upload: `X-Gateway-Confirm: update`
- reboot: `X-Gateway-Confirm: reboot`
- factory reset: `X-Gateway-Confirm: factory-reset`

Do not run successful dangerous actions during exploration. First inspect status and explain the intended effect.

## Quick Start

If the user has the helper tool, prefer it:

```powershell
python gateway_agent_tool.py --base-url http://192.168.1.85 --username admin --password admin session
python gateway_agent_tool.py --base-url http://192.168.1.85 --username admin --password admin rotate-token --scopes read,test,configure
```

For ongoing agent work:

```powershell
$env:GATEWAY_BASE_URL = "http://192.168.1.85"
$env:GATEWAY_AGENT_TOKEN = "<redacted-token>"
python gateway_agent_tool.py status
python gateway_agent_tool.py get /api/modbus/devices
```

## Workflow

1. Identify the target gateway URL and verify the user intended that device.
2. Check unauthenticated access only when verifying auth behavior; otherwise authenticate first.
3. Use `session` to confirm auth type and scopes.
4. Use read-only calls before configuration calls:
   - `/api/status`
   - `/api/auth/session`
   - `/api/modbus/devices`
   - `/api/modbus/state`
   - `/api/modbus/runtime`
5. For configuration, show the exact endpoint and payload summary before sending it.
6. After any write, re-read the related status/config endpoint and report the observable result.
7. For firmware upload or reboot, warn that the gateway may disconnect and poll until it returns.

## Common Tasks

Inspect gateway:

```powershell
python gateway_agent_tool.py status
python gateway_agent_tool.py get /api/recovery/status
```

Rotate an agent token:

```powershell
python gateway_agent_tool.py --username admin --password admin rotate-token --scopes read,test,configure
```

Add a Modbus device from JSON:

```powershell
python gateway_agent_tool.py add-device --json @device.json
```

Generic API update:

```powershell
python gateway_agent_tool.py put-json /api/modbus/runtime --json '{"polling_enabled":true}'
```

Firmware upload:

```powershell
python gateway_agent_tool.py upload-firmware firmware.bin --confirm update --timeout 240
```

## Reference

Read `references/api.md` when you need endpoint details, auth behavior, or safety boundaries.