# Use EMQX Agents Templates

EMQX Agents provides built-in templates for common MQTT automation scenarios. You can use a template as provided or customize its instructions before starting a chat and deploying an agent.

::: tip

Built-in templates are read-only. You cannot create, directly edit, or delete them. You can customize the instructions only when using a template.

When you customize the instructions while using a template, the changes apply only to the new chat and workspace. The original template remains unchanged.

:::

## Prerequisites

Before using a template:

- Obtain access to a running EMQX Agents deployment.
- Add and authorize the connectors required by the behavior you want to build. For more information, see [Connectors](./connectors.md).

## Browse Templates

In the left navigation menu of your EMQX Agents deployment, click **Templates**. The Templates page shows the built-in templates available to the deployment. Each template card provides a name, a short description, and icons for the services used by the template.

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

Click a template card to open its detail page. Review the following information before using the template:

- **Instructions**: The behavior that the agent performs for each matching event.
- **Trigger**: The event source and trigger configuration, such as an MQTT topic filter and QoS level.
- **Tools**: The tools and service integrations available to the agent.

## Use and Customize a Template

1. On the template detail page, click **Use Template**.
2. In the **Use Template** panel, review **Instructions for new chat**.
3. [Optional] Click the edit icon and customize the instructions for the agent you want to build.
4. Enter the required variables, if the template defines any.
5. Select the required connectors. The available fields depend on the services used by the template, such as EMQX Broker, EMQX Tables, or Slack.
6. Click **Start Chat**.

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

EMQX Agents creates a new chat and workspace from the template. The new workspace uses the instructions, variables, and connectors submitted for this template-based chat. The original template is not changed.

## Customize Template Behavior

When you customize the template instructions, EMQX Agents updates the agent configuration and supporting content in the new chat to match the requested behavior. These changes do not affect the original template.

If the customized behavior no longer requires a variable or connector, EMQX Agents removes that requirement. If a required variable or connector is missing, the Builder asks you to provide it in the chat.

For example, if you change a template from sending Slack notifications to publishing MQTT messages, the new chat no longer requires the Slack channel or Slack connector. If an EMQX Broker connector or target topic is missing, the Builder asks you to provide it.

## Validate and Deploy the Agent

EMQX Agents validates the generated agent definition before enabling deployment. If required information is missing, the Builder asks you to provide it in the chat.

After validation succeeds:

1. Review the generated agent behavior.
2. Click **Deploy Agent**.
3. In the **Deploy Agent** dialog, review or edit the generated **Agent Name** and **Description**.
4. Click **Deploy Agent**.
5. Verify that the agent appears on the **Agents** page and reaches the **Running** status.

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

## Next Steps

- [Refine the Agent in a Chat](./chats.md#refine-the-agent-definition)
- [Manage Agents](./agents.md)
- [Manage Connectors](./connectors.md)