# Connectors

Connectors are the tools an agent can call to act on the world. Each connector is a configured connection to an external service that exposes a typed set of actions — such as publishing an MQTT message or querying a time-series table — that agents and chats can use during a run.

EMQX Agents currently supports two connector types:

| Type | Description |
|---|---|
| **EMQX Broker** | Subscribe to MQTT topics as event triggers, and publish messages as actions. |
| **EMQX Tables** | Query and write time-series data through SQL. |

Connectors are configured at the deployment level and can be reused across multiple agents and chats.

## View Connectors

Click **Connectors** in the left menu of your deployment to open the Connectors page. The list shows all configured connectors with the following columns:

| Column | Description |
|---|---|
| **Name** | The display name assigned to the connector. |
| **Type** | The connector type: EMQX Broker or EMQX Tables. |
| **Description** | A summary of the connection, such as the host address and database name. |
| **Updated At** | When the connector was last modified. |
| **Actions** | Edit or delete the connector. |

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

## Add a Connector

1. Click **Connectors** in the left menu.
2. Click **+ Add Connector**.
3. In the **Add Connector** panel, select a connector type and fill in the required fields.
4. Click **Confirm**.

### EMQX Broker

Use this connector type to subscribe to MQTT topics and publish messages on an EMQX Broker deployment.

| Field | Required | Description |
|---|---|---|
| **Type** | Yes | Auto-filled with `EMQX Broker`. |
| **Name** | Yes | A display name for this connector, for example `factory-broker`. Must start with a letter and can contain letters, numbers, hyphens, and underscores, up to 64 characters. |
| **Address** | Yes | The broker address in `host:port` format. Always include 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** | No | The username for authenticating with the broker. Credentials are configured in **Access Control** -> **Authentication** on your EMQX Broker deployment. |
| **Password** | No | The password for authenticating with the broker. |
| **Client ID Prefix** | No | A prefix applied to the MQTT client IDs used by this connector. Useful for identifying agent connections in broker logs. |
| **Enable TLS/SSL** | No | Enable TLS for the connection. Off by default. |
| **Default QoS** | No | The default MQTT QoS level for subscriptions and publishes. Options: `0`, `1`, `2`. Default: `1`. |

### EMQX Tables

Use this connector type to query and write data in an EMQX Tables deployment.

| Field | Required | Description |
|---|---|---|
| **Type** | Yes | Auto-filled with `EMQX Tables`. |
| **Name** | Yes | A display name for this connector, for example `factory-tables`. |
| **Address** | Yes | The Tables service address in `host:port` format. The default port is `4000`. If the port is omitted, `4000` is used. Find the address in the **Connection Info** section on your EMQX Tables deployment's Overview page. |
| **Username** | No | The username for authenticating with the Tables service. Find it in the **Connection Info** section on your EMQX Tables deployment's Overview page. |
| **Password** | No | The password for authenticating with the Tables service. Find it in the **Connection Info** section on your EMQX Tables deployment's Overview page. |
| **Database Name** | No | The database to connect to. Defaults to `public`. |
| **Enable TLS/SSL** | No | Enable TLS for the connection. Off by default. |

## Edit a Connector

1. On the **Connectors** page, click the edit icon in the **Actions** column for the connector you want to update.
2. In the **Edit Connector** panel, update the fields as needed.
4. Click **Confirm**.

::: warning Important Notice
Editing a connector that is actively used by a running agent takes effect immediately. If the updated credentials or address are incorrect, the agent's next run will fail.
:::

## Delete a Connector

1. On the **Connectors** page, click the delete icon in the **Actions** column for the connector you want to remove.
2. Confirm the deletion.

::: warning Important Notice
A connector cannot be deleted while it is in use by a deployed agent. Stop or delete the agent first, then delete the connector.
:::

## Use Connectors in a Chat

When starting a chat, you can select which connectors the LLM has access to. This allows the LLM to reference the correct connector when generating an agent definition.

To select connectors for a chat session:

1. Click the connector icon in the lower-left corner of the input area. A **Connectors** panel appears listing your configured connectors.
2. Check the connectors you want to make available for this session.
3. To add a new connector, click **+** in the upper-right corner of the panel. This opens the Add Connector form without leaving the chat.

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

The selected connectors are used by the LLM to configure triggers and tools in the generated agent definition. For example, selecting an EMQX Broker connector allows the LLM to set it as the MQTT trigger source and as the target for `mqtt.publish` actions.

## Next Steps

- [Start a Chat](./chats.md)
- [Manage Agents](./agents.md)