Assign an Agent to a Device

By default, every device runs the agent that was baked into its firmware (for example, Friend for voice-chat boards). To make a device run your agent, you scan a QR generated from the Admin Dashboard.

Before you start

• The agent must already exist in the Admin Dashboard.
• The device must be paired and connected to Wi-Fi (see Install and Pair a Device).
• You must own the device in the ESP RainMaker Home app (whoever paired it does).

Steps

1. Open the agent in the Admin Dashboard

Go to Your AI Agents in the dashboard, find the agent, click Share.

2. Scan the QR with your phone's camera

The Share dialog shows a QR code. Open your phone's default camera app (or Google Lens on Android) and point it at the QR.

Use the camera app, not the in-app scanner. The QR contains a deep link (https://...) that the operating system routes to the ESP RainMaker Home app. The in-app QR scanner is for adding new devices, not assigning agents.

The OS shows a banner — "Open in ESP RainMaker Home" or similar. Tap it.

3. Pick the device

ESP RainMaker Home opens and asks which of your devices should switch to this agent. Pick one and confirm.

4. The device updates

The app pushes the new agent ID to the device. The device fetches the agent's config from the platform and starts using it. Total time: a few seconds.

You'll hear / see the next conversation pick up the new agent.

Reverting to the default agent

Each device's firmware has a default agent ID compiled in (e.g., friend, matter_controller). To revert:

• Easiest: scan the device's own original QR again from the Admin Dashboard if the default agent is in your account, or
• Factory reset the device (see Install and Pair). After reprovisioning, it's back on its compiled-in default agent.

Common gotchas

Symptom	Cause
Camera scans the QR but does nothing	You're not signed in to the app. Sign in first, then re-scan.
The deep link opens a web browser	The app isn't installed. Install ESP RainMaker Home, then re-scan.
App shows no devices to pick	None of your devices are reachable. Check device power and Wi-Fi.
Agent assigned but device still using the old one	Open a new conversation. In-flight conversations may continue on the previous agent.

A note on capabilities

If the agent you're assigning expects voice (has a Speech Model configured) but the device is text-only — or vice versa — the device picks up only what it can do. For best results, match agent type to device type:

Device type	Agent should have
Voice chat board	A Speech Model configured
Display-only board	Text Model only is fine
Matter Controller board	Matter-aware tools (get_device_list, control_device)