# 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](https://mqttx.app/)).

## Step 1: Create an EMQX Agents Deployment

![agents_project_home](./_assets/agents_project_home.png)

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.

![agents_add_connector](./_assets/agents_add_connector.png)

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

   ![agents_select_connector](./_assets/agents_select_connector.png)

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.

![agents_chat_response](./_assets/agents_chat_response.png)

1. Click **Deploy Agent**.

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

   ![deploy_agent](./_assets/deploy_agent.png)

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.

![agents_agent_detail](./_assets/agents_agent_detail.png)

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

![agents_run_detail_timeline](./_assets/agents_run_detail_timeline.png)

## What's Next

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