Aqara Smart Home AI Agent Skill

Basics

• Host (default): agent.aqara.com - override with AQARA_OPEN_HOST. Skill root: skills/aqara-agent/. Wrapper: scripts/aqara_open_api.py (AqaraOpenAPI -> Open Platform REST, including energy).

aqara_open_api.py CLI

• Invocation: python3 scripts/aqara_open_api.py <method_name> [json_body].
• Must: first argument equals the exact public method name on AqaraOpenAPI (see bash examples in references/*.md). Forbidden: aliases or shortened names unless a reference documents an equivalent.
• Dispatch: get_* -> no JSON body; post_* -> JSON object (optional, default {}).
• Energy: post_energy_consumption_statistic - route from device_ids only (non-empty -> device API; else position). Fields and NL mapping: references/energy-statistic.md.
• Methods (ground list): get_homes, get_rooms, get_home_devices, get_home_scenes, get_home_automations, post_current_outdoor_weather, post_device_base_info, post_device_status, post_device_control, post_device_log, post_execute_scene, post_scene_detail_query, post_create_scene, post_scene_snapshot, post_scene_execution_log, post_automation_detail_query, post_automation_execution_log, post_automation_switch, post_energy_consumption_statistic. Forbidden call names not present on AqaraOpenAPI unless a reference adds them.
• Optional env: AQARA_OPEN_HTTP_TIMEOUT (default 60), AQARA_OPEN_API_URL.

Skill Package Layout

Relative to skills/aqara-agent/. Normative: this file + references/*.md + references/scene-workflow/*.md where scene applies + references/automation-workflow/*.md where automation applies. README.md is a human index only.

Core Workflow

deps -> sign-in -> pick home -> intent -> references/*.md -> summarize

Ground Truth (Binding)

Forbidden stating or implying as factual: homes, rooms, devices, capabilities, attributes, counts, logs, or control outcomes, except from executed skill scripts + real API responses or skill-accepted user input (e.g. pasted aqara_api_key). If that flow has not succeeded, Forbidden any factual claim about those entities.

Forbidden demo-style lists, guessed layouts, synthetic values, fake success after errors/timeouts/missing auth, or prose/JSON mimicking API output without a real response.

Must state missing data and cause (e.g. not signed in, API error), then auth/retry/references/. Forbidden imagined padding.

Execute in order:

1. Environment

export AQARA_OPEN_HOST=agent.aqara.com   # test; omit or set prod host as required

cd skills/aqara-agent
pip install -r scripts/requirements.txt

2. Auth

• Must confirm user_account.json readable/writable before features; host/project rules may require reading it first.
• Must follow references/aqara-account-manage.md (switch-home vs re-login, token save, Step 1 login copy).
• Must read assets/login_reply_prompt.json on every login guidance turn. Must set the user-facing login link to the exact official_open_login_url string (login_url_policy). Forbidden invent Open Platform / sns-auth / client_id / redirect_uri URLs from memory.
• Locale from JSON for the user's language; unknown -> en (fallback_locale / default_locale). Must deliver the single-line login URL per references/aqara-account-manage.md.

user_account.json:

{
  "aqara_api_key": "",
  "updated_at": "",
  "home_id": "",
  "home_name": ""
}

3. Home Management

• Must after saving aqara_api_key run references/home-space-manage.md step 0 immediately (fetch homes; one home -> write; many -> user picks). Forbidden reply only "send home name" without running fetch.
• Must run save_user_account.py and aqara_open_api.py get_homes as two separate invocations. Forbidden && on one shell line (aqara-account-manage.md step 2, home-space-manage.md step 0).
• Switch home: Must re-fetch homes and let the user choose (home-space-manage.md). Forbidden default to re-login. Must use aqara-account-manage.md login only if the user demands re-login/token rotation or the API signals expired/unauthorized.

4. Intent

Categories: space, device query, control, scene, automation, energy. Multiple intents: Must query before control, in utterance order.

5. Route and Summarize

Must open the matching references/ doc, run scripts, summarize from actual output only. Forbidden fabricate success or any home/room/device/state not in script/API output (Ground truth).

Illustrative CLI JSON (Agents Only)

Forbidden paste these raw blocks to end users.

REST shape (skeleton):

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

Error Handling

Notes

1. Forbidden raw IDs in user text (device, position, home_id, ...). Exception: automation_id allowed if server desensitized virtual ID.
2. After layout changes, if match fails: Must re-fetch space + devices (references/home-space-manage.md, references/devices-inquiry.md), retry.
3. User replies: Must conclusion first, then detail; Must <= one clarification question.
4. Session gate: unsigned -> Must end on setup; Forbidden imply control ran.
5. Must run scripts/*.py automatically when required (stricter host policy wins).
6. Account/home change: Must update user_account.json and re-run references/aqara-account-manage.md.
7. Forbidden echo tokens/headers; Must treat user_account.json and caches as sensitive.
8. Multiple fuzzy name hits: Must user confirm.
9. User-visible: Forbidden shell, paths, raw stdout, debug JSON, references/ filenames; Must plain summary.
10. Control OK: Must brief close; Forbidden preemptive hedging; fix only after user reports failure.

Out of Scope

Fully unsupported (no API in this skill; point users to Aqara Home app when relevant):

• Cameras - live view / playback.
• Locks - unlock / lock-unlock.
• Shortcuts (e.g. Siri lists) - Must point to Aqara Home app.
• Weather - general forecasts and Q&A; exception: post_current_outdoor_weather only in recommend.md step 7 Leaving home before control - see weather-forecast.md; Forbidden for Create scene, snapshot, run catalog scene, logs, or any other flow.
• Entertainment - beyond devices-control.md.

Limited to documented workflows (no app-only or undocumented features):

• Scenes - only procedures in scene-manage.md and references/scene-workflow/*.md (e.g. list.md, execute.md, recommend.md, create.md, snapshot.md, execution-log.md, failure-response.md, appendices.md).
• Automations - only procedures in automation-manage.md and references/automation-workflow/*.md (list.md, toggle.md, execution-log.md, failure-response.md).

When the user asks outside the above: Must say unsupported (or not yet); Must direct to Aqara Home app if the app covers it.