Aqara Smart Home AI Agent Skill

Basics

• - Aqara Open Host (default): agent.aqara.com (override via AQARA_OPEN_HOST)
• Skill root: skills/aqara-agent/ (in-repo skill)
• Python wrapper for the Aqara Open API: scripts/aqara_open_api.py — calls the API surface directly.

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:

• - Sources of truth only: Homes, rooms, device names/IDs (for internal use), capabilities, live attributes (temperature, brightness, switch state, online/offline, etc.), lists, counts, logs, and control outcomes must come only from executed skill scripts and real Aqara API responses—or from user-supplied input the skill is designed to accept (e.g. pasted aqara_api_key). If the corresponding inquiry or control flow has not been run successfully, do not present any of that information as factual.
• Never invent or “plausible-fill”: Example or demo-style device/home lists; guessed room layouts; assumed device counts; synthetic attribute values; fabricated success after errors, timeouts, skipped steps, or missing auth; JSON or prose that mimics API output without a real response.
• When data is missing: State clearly that it could not be retrieved (and why, e.g. not signed in, API error), then follow auth/retry/references/—never substitute imagined content to make the answer feel complete.

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

1. 1. Environment

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

CODEBLOCK0

• - Install dependencies before use:

CODEBLOCK1

1. 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 §1 login layout. 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 URL / QR / “stop after qr_fallback_line” rules: see Canonical login above.

INLINECODE15 shape:

CODEBLOCK2S

1. 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.

1. 4. Intent

• - Space / device query / device control; 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	INLINECODE25
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 |

1. 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).

Wrapper shape (illustrative) — CLI scripts may print JSON with call_tool output under result for troubleshooting (fields as actually returned):

CODEBLOCK3

On bad params or JSON parse errors (illustrative):

CODEBLOCK4

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 | | No home selected | Clarify proactively; point to space-management flow | | 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. 1. Do not expose raw IDs in user-facing replies (device id, position id, homeid, …).
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 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.
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:

• - Video / cameras — live view, playback
• Door locks — unlock, lock/unlock smart locks (security-sensitive)
• Automations — list or create automations
• Energy — power usage / billing
• Weather — forecasts

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