EMQX Cloud

English

简体中文
日本語

English

简体中文
日本語

Appearance

Contact Us
Contact Us

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.
  • An MQTT client for publishing test messages (for example, MQTTX).

Step 1: Create an EMQX Agents Deployment ​

EMQX Agents is available to all users as a Public Beta. You can create an Agents deployment directly from the EMQX Cloud Console.

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

  2. On the EMQX Agents card, click + New.

    Create an EMQX Agents deployment from the project page

  3. Select the region for the Agents deployment. Google Cloud is the only supported cloud provider.

  4. [Optional] To use private connectivity with the Broker in this guide, select the Broker network under Network Association (Optional). Network association does not change the Broker address used by the connector.

  5. Click Deploy and confirm the operation.

You cannot change the network after the deployment is created. For complete field descriptions and network options, see Create an EMQX Agents Deployment.

When the deployment status changes to Running, 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. On the Available tab, find EMQX Broker and click Add.

  3. In the Add Connector panel:

    • Type: 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 on the Added tab with its address shown in the Description column.

agents_add_connector

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.

    Select the EMQX Broker connector for the chat

  3. Select Always ask from the tool approval selector in the lower-left corner. With this mode, EMQX Agents asks for confirmation before deployment and before tool actions that require approval. For details about the available modes, see Select a Tool Approval Mode.

  4. 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.

  5. [Optional] Click the Add File icon to attach a screenshot, sample payload, or UTF-8 text file that gives the LLM more context. Each chat message can include up to three attachments, and each attachment must be no larger than 2 MiB. For details, see Add Attachments.

  6. [Optional] Select the model and reasoning effort to use for this request from the selector in the lower-right corner. For details, see Select a Model and Reasoning Effort.

  7. 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 ​

After the Builder generates and validates the agent definition, Review Agent appears at the bottom of the chat.

  1. Review the generated definition. Ask follow-up questions or request changes if the trigger, threshold, alert topic, or generated skill does not match your requirements.

  2. Click Review Agent to open the review panel on the right.

  3. Review the required Agent Name, optional Description, Model and reasoning, Trigger, Instructions, and Tools. The panel initially uses the model and reasoning effort selected in the chat. Edit the available settings if needed.

    Review the temperature anomaly monitor before deployment

  4. Click Deploy Agent.

  5. In the Confirm deployment? dialog, click Confirm. This additional confirmation appears because you selected Always ask in the chat.

  6. The agent creation starts, and the agent detail page opens.

In a few minutes, you can see the agent status is Running. The four tabs (Overview, Runs, Configuration, and Skills) show the deployed agent and its workspace:

  • Configuration: The instructions, MQTT trigger, and mqtt.publish tool generated for the agent. The trigger uses topic filter factory/+/+/temperature, QoS 1, and the factory-broker connector. The publish tool is restricted to alerts/anomaly.
  • Skills: The generated skill and supporting files bundled with this deployed agent. They maintain the rolling temperature history and determine when to publish an alert. These files are separate from the deployment-level skills managed from Skills in the left navigation menu.

Review the deployed agent configuration

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:

    json
    {"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 completed run shows a Succeeded status.

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

    EventDescription
    TRIGGERThe MQTT message that started the run, including the topic.
    BUNDLE LOADEDThe agent's skills and configuration were loaded.
    CONTEXT LOADEDThe conversation context was prepared.
    TOOLS RESOLVEDThe tools available for this run were resolved.
    SYSTEM INITThe agent's instructions were applied.
    TOOL RESULTEach tool call the agent made, for example read, run_script, or mqtt.publish.
    LLM CALLThe LLM invocation, with input and output token counts.
    RESPONSEThe agent's final response for this run.
    RUN ENDThe 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.

agents_run_detail_timeline

Optional: Build an Agent with MCP Connectors ​

MCP connectors let agents and chats use external services through the Model Context Protocol (MCP).

Use this optional flow when you want to build an agent that uses an external service, such as Slack. This flow uses a separate chat because the request is different from the MQTT temperature monitor in the main tutorial.

Step 1: Add an MCP Connector ​

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

  2. On the Available tab, find Slack as an MCP connector service.

  3. Click Add on the connector card.

  4. In the Add Connector panel, enter a Name for the connector, for example ops-slack. The Type field is filled with the selected service, and no other configuration fields are required.

  5. Click Confirm.

agents_add_mcp_connector

The connector is added with an Unauthorized status, and EMQX Agents opens an authorization dialog for the selected service. Complete the external authorization flow. When authorization succeeds, the connector status changes to Authorized in the Added tab.

If you close the dialog or authorization fails, go to the Added tab and click the retry authorization action for the connector.

Step 2: Start a Chat with the MCP Connector ​

  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.

  3. In the Connectors panel, select the MCP connector you created.

    The example below uses MQTT events and Slack notifications, so select both factory-broker and your authorized Slack connector.

    Only Authorized MCP connectors can be selected. If the connector is shown but disabled, return to the Connectors page and complete or retry authorization first.

    agents_mcp_chat_connector_panel

  4. Enter the following request:

    Listen to MQTT topic /devices/#. If the temperature in the MQTT message
is above 30, please send a warning message to Slack. Channel: <channel-name>.

    Replace <channel-name> with the Slack channel you want to notify.

  5. Select a tool approval mode. For a guided deployment flow, select Always ask.

  6. [Optional] Select the model and reasoning effort to use for this request.

  7. Click the send button.

The LLM generates an agent definition that can include tools exposed by the selected MCP connector.

Step 3: Deploy the MCP Agent ​

  1. When the generated definition is ready, click Review Agent.

  2. In the review panel, review the Agent Name, Description, Model and reasoning, Trigger, Instructions, and Tools. Update the available settings if needed.

  3. Click Deploy Agent.

  4. If the chat uses Always ask, click Confirm in the Confirm deployment? dialog.

  5. Open the agent detail page and review the Configuration and Skills tabs to confirm that the generated agent uses the selected MCP connector and implements the requested behavior.

Step 4: Test the MCP Agent ​

Test the MCP agent according to the MQTT topic and Slack action described in the chat request. This test flow is different from the temperature anomaly monitor in the main tutorial.

  1. Use your MQTT client to publish a test message to a topic that matches /devices/#, for example /devices/device-001.

    json
    {"device_id": "device-001", "temperature": 31}

  2. Check the Slack channel specified in the request for the warning message.

  3. Return to EMQX Agents and open the run detail page. MCP connector calls appear as tool results in the run timeline, and the final Response event summarizes the result.

What's Next ​