# Connect EMQX Agents to EMQX Fleets

The EMQX Fleets connector lets an agent work with the device registry, device shadows, commands, jobs, groups, tags, saved queries, and device searches. Use this connector to automate device operations and combine fleet state with MQTT or external service workflows.

## Common Use Cases

- Find devices that match a saved query or tag.
- Read a device shadow before deciding whether to send a command.
- Update the desired shadow state for a group of devices.
- Create or inspect device jobs and their execution status.
- Combine device state with Slack, email, or ticketing notifications.

Example chat prompt:

```text
Use the production-fleets connector to find devices tagged with cold-storage. Read their shadows and list devices whose reported temperature is above 8.
```

## Prerequisites

Before adding the connector, prepare:

- The EMQX Fleets API endpoint.
- An API key and API secret.
- The Fleets deployment version and API permissions required by the workflow.
- The thing names, thing IDs, group IDs, tag names, or job IDs used by the workflow.

## Add an EMQX Fleets Connector

1. In the left navigation menu, click **Connectors**.
2. On the **Available** tab, locate **EMQX Fleets** and click **Add**.
3. Configure the connector fields.
4. Click **Confirm**.
5. On the **Added** tab, verify that the connector appears in the list.

| Field | Required | Description |
|---|---|---|
| **Type** | Yes | The selected connector type, `EMQX Fleets`. |
| **Name** | Yes | A display name, such as `production-fleets`. |
| **API Endpoint** | Yes | The Fleets API endpoint, such as `https://example.fleets.mqttce.net:8443`. |
| **API Key** | Yes | The API key used to authenticate with the Fleets API. |
| **API Secret** | Yes | The API secret used to authenticate with the Fleets API. |
| **Timeout (seconds)** | No | The request timeout. Default: `10` seconds. |
| **Verify TLS/SSL Certificate** | No | Verifies TLS certificates when connecting to the Fleets API. Enabled by default. |

## Edit an EMQX Fleets Connector

1. On the **Added** tab, click the edit icon for the EMQX Fleets connector.
2. Update any of the following fields in the **Edit Connector** panel:
   - **Name**
   - **API Endpoint**
   - **API Key**
   - **API Secret**
   - **Timeout (seconds)**
   - **Verify TLS/SSL Certificate**
3. Click **Confirm**.

The **Type** field is read-only and cannot be changed.

## Supported Operations

The connector exposes Fleets operations through the `fleets.tools` provider.

### Read Operations

- Check API health, version, and deployment overview.
- List and retrieve things, thing types, thing groups, group members, and tags.
- Read thing tags and device shadows.
- Search devices and list saved queries.
- List jobs, job executions, commands, and thing events.

### Write Operations

- Create, update, or delete supported registry resources.
- Add or remove tags.
- Update or clear a desired device shadow.
- Send a command.
- Create, update, cancel, or delete jobs and job executions.

### Approve Write Operations

Fleets write operations require explicit approval by default. Before executing a write operation:

1. Run the operation with `dry_run=true`, or call it without approval, to generate a `planned_action` without sending the request to EMQX Fleets.
2. Review the operation, target resources, and request body in `planned_action`.
3. Explicitly approve the planned operation.
4. Run the operation with `approved=true` to execute it.

When approval is required and has not been provided, the tool returns `approval_required=true` with the planned operation instead of sending the request.

::: warning Important Notice
Commands, shadow updates, registry changes, and job operations can affect devices or fleet state. Review the target devices and planned operation before approving the action.
:::

<!-- TODO: Confirm how the Console displays dry-run plans and approval requests for Fleets write operations. Add a screenshot if approval is user-visible. -->

## Permissions and Security

- Use an API key limited to the required Fleets operations and resources.
- Do not include the API key or API secret in chat prompts or agent instructions.
- Resolve thing names and thing IDs carefully because Fleets operations can require different identifiers.
- Limit the number of target devices for write operations.

## Limitations

- Available operations can depend on the Fleets deployment version and API key permissions.
- Saved queries and some global job execution routes might not be available to every deployment.
- The connector does not expose API key lifecycle, setup, certificate, listener, or device impersonation operations.

## Troubleshooting

| Symptom | Resolution |
|---|---|
| The connector cannot reach EMQX Fleets. | Verify the API endpoint, TLS verification setting, and network access. |
| The API returns an authentication or authorization error. | Verify the API key, API secret, and permissions. |
| A thing, group, or job is not found. | Verify whether the operation requires an ID or a name and resolve the resource before retrying. |
| An operation is unavailable. | Check the Fleets deployment version and API key permissions. |

## Related Links

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