aqara-agent（阿卡拉 Agent）

Aqara Smart Home AI Agent Skill

Basics

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_firmware_query, post_device_firmware_upgrade, post_device_log, post_execute_scene, post_scene_detail_query, post_create_scene, post_scene_snapshot, post_scene_execution_log, post_device_related_automation_query, post_automation_execution_log, post_automation_switch, post_create_automation, post_energy_consumption_statistic. Forbidden call names not present on AqaraOpenAPI unless a reference adds them.
• post_create_automation and raw_config (non-negotiable): Every call Must send non-empty raw_config in the HTTP body (automation-create.md). Forbidden to send only auxiliary_config or only root-level supplemental conditions / actions without non-empty raw_config.
• post_create_automation first round vs follow-up: First call: non-empty raw_config only; auxiliary_config Must be empty (omit the argument or pass {}). If the response needs config-list matching, use LLMConfigReference as the only source for Step 03 -> auxiliary_config (step-03-parse-config-prompt.md). Second and later calls: Must resend the same non-empty raw_config and attach auxiliary_config (Step 3 supplement). scripts/aqara_open_api.py shallow-merges raw_config and auxiliary_config into one JSON when both are passed.
• Optional env: AQARA_OPEN_HTTP_TIMEOUT (default 60), AQARA_OPEN_API_URL (overrides disk). Optional disk: assets/user_account.json keys aqara_open_api_url or open_api_url (full base, no trailing slash required) when env is unset — requests use {base}/{path} (e.g. homes/query).

Skill Package Layout

Relative to the skill root directory (Cursor project: .cursor/skills/aqara-agent/; other layouts: skills/aqara-agent/). Normative: this file + references/*.md + references/scene-workflow/*.md where scene applies + references/automation-workflow/*.md where automation applies (includes recommend.md for recommend-style automation -> example NL -> create) + references/automation-create-workflow/* for post_create_automation (see references/automation-create.md). Optional README.md (human index only) when present in a pack; Forbidden treat it as overriding SKILL.md.

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

cd .cursor/skills/aqara-agent   # Cursor project layout (repo root)
# cd skills/aqara-agent         # upstream pack layout
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 -> show the complete home list + remind user to choose one, then user picks). Forbidden reply only "send home name" without running fetch or without listing all homes when many.
• 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, show the complete list, remind user to pick one, then persist (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, device control, device configuration, scene, automation, energy. Multiple intents: Must query before control or configuration, in utterance order.

Recommend automation (automation path): If the user wants situational ideas and has not given one create-ready rule sentence, Must run automation-workflow/recommend.md steps 0-5 (scope gate in §0: if neither position nor device, get_rooms + position list only — no examples same turn; else get_rooms, scoped get_home_devices, get_home_scenes, mandatory post_device_status, optional post_device_base_info, optional get_home_automations). Forbidden post_automation_recommend_query and platform "template name" strings as data. User-facing reply: success vs error format and id redaction -> that doc §5 (§5.2: localized lead-in line matching the user's input language + numbered lines 1. through 10. (digit + ASCII period only) on success; on error, detail only, no home/device/position/scene/automation ids). After the user selects or rewrites one example line, Must continue with automation-create.md and post_create_automation (non-empty raw_config on every call; LLMConfigReference handling per that doc and step-03).

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, recommend.md for recommend-then-create, plus automation-create.md and references/automation-create-workflow/* for post_create_automation).

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