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: Request an EMQX Agents Deployment

EMQX Agents is currently in beta. Deployments are provisioned by the EMQX team after you submit a support ticket.

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

2. On the EMQX Agents card, click Join Beta.

   

3. In the Support Tickets page that opens, click + New to create a ticket.

4. A ticket form opens with the subject and description pre-filled. Edit them if needed, then click Confirm to submit.

The EMQX team will provision a deployment for your project and notify you. Once the deployment is ready, click it 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.