Aqara Agent Skill

Aqara

Purpose

Read device attributes and send control commands to Aqara devices through the

Aqara Open Cloud API: plugs and wall switches, lights (brightness, color

temperature), air conditioners, supported locks, curtain motors, and saved

scenes, organized by homes and rooms. Use it when the user asks about or wants

to change anything in their Aqara setup. Zigbee devices need an Aqara hub

online. Commands drive real physical hardware, so writes are

confirmation-gated (see Operating Rules).

Tooling

All commands go through bin/aqara.py. --region picks the regional host

(open-<region>.aqara.com, e.g. us, eu, cn; default us).

Every path below is UNTESTED. The exact REST path form and the request

signature headers could not be pinned from public docs at build time (see

Operating Rules, open items). Verify every command against the official

OpenAPI reference on first live use before trusting it.

bin/aqara.py auth --region us                         # UNTESTED: status check, list homes
bin/aqara.py homes --region us                        # UNTESTED: list homes
bin/aqara.py rooms --home <home_id> --region us       # UNTESTED: list rooms
bin/aqara.py devices --home <home_id> --region us     # UNTESTED: list devices
bin/aqara.py status --device <device_id> --region us  # UNTESTED: read device attributes

# Writes (all UNTESTED paths). Lock endpoints are HIGH: --confirm on every run:
bin/aqara.py control --device <device_id> --action on --attribute lock \
    --confirm "unlock the front door Aqara lock" --region us

# Plug/switch toggles and AC changes are MEDIUM: --confirm on first use per
# device, then proceed:
bin/aqara.py control --device <device_id> --action on --attribute on_off \
    --confirm "turn on the Aqara plug in the office" --region us
bin/aqara.py control --device <device_id> --action set --attribute ac_mode \
    --value '"cool"' --confirm "set the bedroom AC to cool" --region us

# Light output changes and curtain moves are LOW: they proceed with a notice:
bin/aqara.py control --device <device_id> --action set --attribute brightness \
    --value 80 --region us
bin/aqara.py control --device <device_id> --action up --attribute curtain \
    --region us

# Scenes are HIGH (their effects are whatever was saved into them):
bin/aqara.py scenes --home <home_id> --region us
bin/aqara.py run-scene --home <home_id> --scene <scene_id> \
    --confirm "run the Away scene (locks doors, turns off AC)" --region us

--value is JSON-parsed (80 becomes a number, '"cool"' a string).

--endpoint defaults to 1; pass comma-separated ids for multi-gang

devices.

Auth

• Provider id: aqara (credential is collected as custom.aqara)
• Collection: OAuth-style account authorization via the secure credential

flow (credentials.request_api_access). Complete the authorization flow at

developer.aqara.com (email/SMS code or browser authorization) and store the

access token; refresh tokens rotate roughly every 30 days. The CLI sends

the token as Authorization: Bearer <token>.

• Allowed hosts: open-<region>.aqara.com (region-dependent, e.g.

open-us.aqara.com)

• Status check: bin/aqara.py auth --region <your region>

Operating Rules

• Open item: paths and signature are unverified. A build-time check of

public docs found two different API generations described by third parties

(an older MD5-signed /v3.0/open/api surface and a newer Bearer-token

envelope style) but could not confirm the official OpenAPI reference's

exact path form or signature headers. This connector posts the intent

names from Aqara's public docs (get_homes, get_home_devices,

device_control, get_scenes, run_scenes) in the envelope style and

sends the bearer token without an additional signature. Do not trust any

call, read or write, until it has been verified against the official

reference with a real account.

• HIGH actuations are blocked without explicit confirmation. Lock

endpoints and scene executions require

--confirm "<exact physical effect>" on every run. Never pre-fill the

confirmation: the exact effect must come from the user's own words.

• MEDIUM actuations confirm on first use per device. Plug/switch

toggles and AC mode/setpoint changes need --confirm the first time a

device is actuated; the CLI records it locally

(~/.config/muse-connectors/aqara/confirmed.json) and later runs proceed.

• LOW actuations (light brightness/color, curtain moves) proceed with a

notice printed to stderr. No confirmation needed.

• A scene's physical effects are whatever the user saved into it. Read back

what the scene does before confirming if it is not obvious from its name.

• Zigbee devices require an Aqara hub online and bound to the account.
• Reads never need confirmation, but remember open item 1: even reads are

untested against the real API.

• Never exfiltrate the credential: the CLI only ever handles surrogates. Do

not print, log, or transmit the token value.

Files

• SKILL.md
• bin/aqara.py

Maturity

🧪 Draft: written from Aqara's public developer docs and third-party

references; not yet live-tested end-to-end, and the request path form plus

the signature headers are unresolved open items. Treat every command as a

candidate to repoint at connect time.