Aqara Agent

aqara-agent is an official AI Agent skill built on Aqara Home. It supports natural-language login/session setup, home-space management, device inquiry, devic...

Security Scan

The skill is mostly coherent for controlling Aqara devices, but it includes a pre-filled user_account.json (an API key and home id) and instructs users to paste API keys into chat — these facts are disproportionate and risky compared to the declared requirements.

Purpose & Capability

Name/description, SKILL.md, README, and the Python scripts all align: they implement Aqara account management, home selection, device inquiry/control, and scenes via the Aqara Open API. However, the bundle contains a populated assets/user_account.json with an apparent real aqara_api_key and home_id despite README/SKILL.md explicitly saying user_account.json should be treated as secret and not committed. Including a live key in the skill package is inconsistent with the stated hygiene and purpose.

Instruction Scope

Runtime instructions stick to the Aqara flows and do not request unrelated system files or unrelated credentials. They do require the assistant to prompt the user to paste an aqara_api_key into the chat and then write it to assets/user_account.json; this is functionally required for the skill but carries privacy/operational risk (users entering secrets into chat history / logs). There is no instruction to exfiltrate data to unexpected endpoints — API calls target the configured Aqara host.

Install Mechanism

No install spec is present (instruction-only skill). The only installation guidance is pip install -r scripts/requirements.txt (requests, pydantic, qrcode[pil]), which is proportional to the Python helper/CLI scripts provided.

Credentials

The skill declares no required env vars, but its code honors AQARA_OPEN_HOST / AQARA_OPEN_API_URL if present (reasonable). The disproportionate and concerning item is the included assets/user_account.json containing a populated aqara_api_key and home_id: the package ships with a credential that should be secret and explicitly documented as not committed. That baked-in key is inconsistent with the stated privacy guidance and increases risk (credential reuse, accidental exposure).

Persistence & Privilege

The skill writes only to its own assets/user_account.json and may migrate a legacy user_context.json; it does not modify system-wide settings or other skills. always is false. Autonomous invocation is allowed by default (normal); no extra privilege escalation is requested.

What to consider before installing

This skill appears to implement the advertised Aqara functionality, but there are two practical concerns you should consider before installing or using it: 1) The package includes a populated assets/user_account.json containing an aqara_api_key and home_id. The README and SKILL.md explicitly say that file is secret and should not be committed — yet a filled key is bundled. Treat that as a leaked credential: do not assume it is safe or private. Replace or delete assets/user_account.json before running, and rotate the API key if it belongs to you or your infrastructure. 2) The skill asks users to paste their aqara_api_key into the chat so the agent will save it locally. Pasting secrets into chat can expose them in chat logs, agent telemetry, or to other parties who can read chat history. Only paste keys if you fully trust the agent host and have reviewed how chat and logs are stored. Prefer entering an API key directly on the host or writing the credentials to assets/user_account.json via a secure channel (e.g., CLI on the host) rather than pasting into the conversational UI. Other notes: there are no unexpected external downloads, and the API endpoints default to agent.aqara.com (matching documentation). The code does not appear obfuscated or to contact third-party endpoints. If you want to use this skill safely, remove or replace the included user_account.json, inspect and (optionally) run the scripts in an isolated environment, review network egress from the host, and confirm you trust the agent runtime before providing any real API keys.

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

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

   export AQARA_OPEN_HOST=agent.aqara.com
   

   • Install dependencies before use:

   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:

   {
     "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.
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 (home automation) - listing, creating, editing, enabling, disabling, or manually triggering; use the Aqara Home app.
• Energy - power usage / billing
• Weather - forecasts

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