Aqara Smart Home AI Agent Skill

---

name: aqara-agent

description: "aqara-agent is an official AI Agent skill built on Aqara Home. It supports natural-language login/session setup, home-space management, device inquiry, device control, and scene management (list and execute scenes). Examples: \"How many lights are at home?\", \"Turn off the living room AC\", \"What's the temperature and humidity in the bedroom?\", \"Run Movie scene\""

---

# Aqara Smart Home AI Agent Skill

Basics

Core workflow

High-level order: **deps -> sign-in -> pick home -> intent -> follow `references/*.md` and summarize**.

Ground truth: no fabricated smart-home data

Large models may **hallucinate** plausible homes, rooms, devices, states, or counts. For this skill, that is **explicitly forbidden**:

Align with **usage** and **core workflow** above; implement in order:

1. **Environment**

- Set environment host first (single-switch for test/prod):

```bash

export AQARA_OPEN_HOST=agent.aqara.com

```

- Install dependencies before use:

```bash

cd skills/aqara-agent

pip install -r scripts/requirements.txt

```

2. **Auth** - Before any feature, verify Aqara account auth and ensure **`user_account.json` is readable/writable** (project rules may require reading it first). Follow **`references/aqara-account-manage.md`** for switch-home vs re-login, token save, and **Step 1: Login Guidance**. Locale strings and **`default_login_url`** live in **`assets/login_reply_prompt.json`** - match the user's language; **fallback** to **`en`** when unknown (`fallback_locale` / `default_locale` in that file). **Login is satisfied by the single-line URL**; showing **`assets/login_qr.png`** is optional when the file exists and the client can render images. `qr_fallback_line` and the full order are in that reference.

`user_account.json` shape:

```json

{

"aqara_api_key": "",

"updated_at": "",

"home_id": "",

"home_name": ""

}

```

3. **Home management**

- After `aqara_api_key` is saved, **automatically** follow `references/home-space-manage.md` to fetch the home list and finalize selection: run that doc's **step 0** **immediately**; if there is a single home, write it; if multiple, ask the user to pick by index/name. **Do not** end with only "please reply with a home name" without running the fetch.

- When the agent/terminal runs scripts: `save_user_account.py` (write token) and `aqara_open_api.py homes` (fetch homes) **must be two separate runs** - **do not** chain with `&&` in one shell line; see `references/aqara-account-manage.md` step **2** and `references/home-space-manage.md` step **0**.

- **Switching homes**: by default **only** re-fetch the home list and let the user choose (see `references/home-space-manage.md`); **do not** default to re-login. **Only** if the user clearly asks to re-login/rotate the token, or the API indicates an expired/unauthorized token, follow `references/aqara-account-manage.md` for login.

4. **Intent**

- Space / device query / device control / scene. For multiple intents **query first, then control**, following clause order in the utterance.

| Intent | Capability | Reference |

|--------|------------|-----------|

| Space | List all homes; list rooms in a home | `references/home-space-manage.md` |

| Device query | Filter by home/room; device details (incl. current attributes) | `references/devices-inquiry.md` |

| Device control | Control hardware in the home | `references/devices-control.md` |

| Scene | List and execute scenes | `references/scene-manage.md` |

5. **Route** to the matching `references/` doc, execute, and summarize.

- Summarize from real outcomes only; **never fabricate success** or any **homes, rooms, devices, attributes, counts, or states** that are not grounded in **actual** script/API output (see **Ground truth: no fabricated smart-home data** above).

Illustrative CLI JSON (for agents only; do not paste raw blocks to users)

**REST response shape (illustrative)** — `aqara_open_api.py` prints JSON returned by the Open Platform; field names match the live endpoint (example skeleton only):

{
  "code": 0,
  "message": "",
  "data": {}
}

**On bad params or JSON parse errors (illustrative)** —

{
  "ok": false,
  "error": "..."
}

Error handling

| Situation | Action |

|-----------|--------|

| Device not found | Say no match for "X"; optionally list a few candidate names |

| Capability not supported | State the unsupported action/attribute; do not pretend success |

| Home/room not found | Say no hit; suggest checking the home or re-fetching space/device lists per `references/` |

| Multiple devices match | List matches; ask the user to pick room or full name (one question at a time) |

| Not signed in / no `aqara_api_key` | Guide login and saving `aqara_api_key`, then continue with home fetch. Scripts raise `MissingAqaraApiKeyError` from `load_api_key()` when the saved key is empty; route to `references/aqara-account-manage.md` |

| No home selected | Clarify proactively; point to space-management flow. CLI: missing ``home_id`` triggers ``homes/query``; one home auto-writes ``user_account.json``; multiple homes exit with ``home_selection_required`` (see ``references/home-space-manage.md``) |

| Invalid `aqara_api_key` or auth failure | Ask to re-login or refresh the token (no sensitive leakage). On **home switch**, only treat as auth failure if the home list call fails with an auth-class error - do not require login just because the user said "switch home". **If the platform returns `unauthorized or insufficient permissions` (or equivalent), always follow `references/aqara-account-manage.md` to re-login and save the token; never fake query/control success** |

| Control path unavailable | Say the device was located but the command could not be sent |

| Other | Short, understandable summary + retry or check `references/`; do not expose internal URLs or full request headers |

| Indeterminate | Use `references/` and script output; if it's a skill bug, file an issue in the skill repo |

| Risk of empty/missing API output | **Do not** invent homes, rooms, devices, or readings to fill the gap; re-run the correct flow or explain the failure - see **Ground truth: no fabricated smart-home data** |

Notes

1. Do not expose raw IDs in user-facing replies (device id, position id, home_id, ...).

2. Default **query before control** for multiple intents in one utterance.

3. After adding/moving devices or rooms, if matching fails, re-fetch space and device lists via `references/home-space-manage.md` and `references/devices-inquiry.md`, then retry.

4. User-visible replies: **conclusion first, then detail**; **one** key clarification question at a time.

5. **Session gate first**: if not signed in, the "conclusion" should guide setup - not pretend devices were controlled.

6. When `scripts/*.py` must run, **execute automatically**; details follow **mandatory script execution policy** (if defined elsewhere).

7. After switching account or home, update `user_account.json` and re-run the relevant steps in [`aqara-account-manage.md`](references/aqara-account-manage.md).

8. Do not echo tokens or full headers; treat `user_account.json` and caches as sensitive.

9. Device name matching is often fuzzy; ask the user to confirm when multiple hits exist.

10. In user-visible replies, **do not** print shell commands, script paths, raw stdout (incl. debug JSON), or `references/` filenames; the agent runs scripts; summarize in plain language.

11. When control APIs return success, keep the closing brief (result + essentials only); **do not** add hedging like "if some lights didn't turn on, tell me" - troubleshoot only when the user reports an issue.

12. **Anti-hallucination**: Treat **Ground truth: no fabricated smart-home data** as binding for every turn; any user-visible home/room/device/state detail must trace to a real run of this skill's tooling, not to model imagination or general knowledge of "typical" smart homes.

13. Never invent homes, rooms, devices, scenes, or states: only report data from executed scripts/API responses.

Out of scope

The skill **does not** support:

If asked for an unsupported capability, say clearly that the skill cannot do it and suggest the Aqara Home app.