Quick Start: Build and Deploy Your First Agent

This guide walks you through creating a complete event-driven agent using EMQX Agents. You will build a temperature anomaly monitor that watches MQTT messages from factory devices, evaluates each reading against a rolling average, and publishes an alert when a device's average temperature exceeds a threshold.

By the end of this guide, you will have:

• A running EMQX Agents deployment connected to your EMQX Broker
• A connector configured for your broker
• A deployed agent that reacts to live MQTT events

Prerequisites

• An EMQX Cloud account with an active project.
• An EMQX Broker deployment in the Running state. The broker must be in the same project and region as your EMQX Agents deployment.
• An MQTT client for publishing test messages (for example, MQTTX).

Step 1: Create an EMQX Agents Deployment

1. Log in to the EMQX Cloud Console and open your project.

2. Click + New on the EMQX Agents card.

3. On the New Deployment page:

   • The Starter plan is selected by default.
   • Under Cloud Provider & Region, select the same provider and region as your EMQX Broker deployment.
   • Under Network Association, select the network shared with your Broker deployment from the dropdown. This enables private connectivity between the agent and your broker.

   TIP

   If no network appears in the dropdown, the selected region does not have an existing EMQX Broker or EMQX Tables deployment. Create one first, then return to this step.

4. Optionally enter a Deployment Name.

5. Click Deploy, then click Confirm in the confirmation dialog.

The deployment takes a moment to initialize. Once it is ready, click the deployment to open it.

Step 2: Add a Connector

Before the agent can subscribe to MQTT topics or publish messages, you need to configure a connector that points to your EMQX Broker.

1. In your EMQX Agents deployment, click Connectors in the left menu.

2. Click + Add Connector.

3. In the Add Connector panel:

   • Type: Automatically filled with EMQX Broker.
   • Name: Enter a name, for example factory-broker.
   • Address: Enter your broker's address in host:port format, always including the port number, for example broker.example.com:1883 for unencrypted MQTT or broker.example.com:8883 for TLS. Find the address in the MQTT Connection Information section on your EMQX Broker deployment's Overview page.
   • Username and Password: Enter the credentials configured in Access Control -> Authentication on your EMQX Broker deployment.
   • Client ID Prefix: Leave blank. The system generates client IDs automatically.
   • Leave Enable TLS/SSL off and Default QoS at 1 for this guide.

4. Click Confirm.

The connector appears in the list with its address shown in the Description column.

Step 3: Start a Chat and Describe the Agent

Agents are built through conversation. You describe what you want, and the LLM generates the agent definition.

1. Click Chats in the left menu, then click + New Chat.

2. Click the connector icon in the lower-left corner of the input area. A Connectors panel appears listing your configured connectors. Check factory-broker to make it available for this session.

   

3. In the input field, describe what you want the agent to do. For this guide, enter:

   I want to monitor MQTT temperature events on the topic factory/+/+/temperature.
   Each message payload is JSON, for example: {"device_id": "dev-0042", "temp": 95.4}
   The agent should track the last 3 readings per device. If the rolling average
   exceeds 70, publish an alert to alerts/anomaly.

4. Select your preferred thinking mode from the dropdown in the lower-right corner, then click the send button.

The LLM processes your request. It generates the agent's instructions, writes a skill for maintaining the rolling temperature history, and assembles a complete agent definition with the MQTT trigger and publish tool configured.

Step 4: Deploy the Agent

Once the LLM has finished generating the agent definition, a Deploy Agent button appears at the bottom of the chat.

1. Click Deploy Agent.

2. A dialog appears with a pre-filled Agent Name and Description. Edit them if needed, then click Deploy Agent.

   

3. The agent creation starts immediately. You are taken to the agent detail page.

In a few minutes, you can see the agent status is Running. The five tabs (Overview, Runs, Trigger, Tools, and Prompt) show the full configuration generated from your chat:

• Trigger: Kind mqtt, topic factory/+/+/temperature, QoS 1, connected to your factory-broker connector.
• Tools: mqtt.publish, restricted to the alerts/anomaly topic.
• Prompt: The instructions the LLM wrote specifically for this agent, describing its behavior for each incoming event.

Step 5: Test the Agent

Publish a series of test messages to trigger the agent and verify it works.

1. Open your MQTT client and connect to the same EMQX Broker using the same credentials.

2. Publish several messages to a topic that matches factory/+/+/temperature, for example factory/plant-a/line-3/temperature. Use a JSON payload:

   {"device_id": "dev-0022", "temp": 75.1}

   Publish the message at least three times with temperatures above 70, for example 75.1, 78.3, and 80.0. This gives the agent enough readings to compute a rolling average that exceeds the threshold.

3. Return to the EMQX Agents deployment and go to the Runs tab of your agent.

   Each published message that matched the trigger topic created one run. Each run shows a success status.

4. Click a run ID to open the run detail page. The Timeline shows the sequence of events for that execution:

   Event	Description
   TRIGGER	The MQTT message that started the run, including the topic.
   BUNDLE LOADED	The agent's skills and configuration were loaded.
   CONTEXT LOADED	The conversation context was prepared.
   TOOLS RESOLVED	The tools available for this run were resolved.
   SYSTEM INIT	The agent's prompt was applied.
   TOOL RESULT	Each tool call the agent made, for example read, run_script, or mqtt.publish.
   LLM CALL	The LLM invocation, with input and output token counts.
   RESPONSE	The agent's final response for this run.
   RUN END	The terminal status of the run.

   When the rolling average threshold was exceeded, the mqtt.publish tool result appears in the timeline, and the Response event confirms the alert was published.

What's Next

• Add an EMQX Tables connector to query or write time-series data from within an agent.
• Review and manage your agents to monitor run history, inspect timelines, and redeploy with updated behavior.
• Update your connectors to change credentials or add connections to additional brokers.