Agents

An agent is a deployed, long-running process that reacts to MQTT events and acts on your infrastructure. Each agent runs in an isolated sandbox, listens on a configured MQTT topic, and executes a run for every incoming message that matches the trigger.

Agents are created by deploying an agent definition generated from a chat session. Once deployed, an agent runs independently with no ongoing human input required.

View Agents

Click Agents in the left menu to open the Agents page. The page shows all agents in this deployment. Each agent card shows:

• Name and Description
• Status: Starting or Running
• Created At
• Total Runs

Click an agent card to open its detail page.

Create an Agent

Agents are created from a chat session, not from this page directly. To create an agent:

1. Open a chat and describe the automation you want to build.
2. Click Deploy Agent when the LLM has generated the agent definition.

The agent appears in the Agents page with a Starting status and transitions to Running in a few minutes. See Chats for the full workflow.

To create an additional agent from scratch, click + New Agent in the upper-right corner of the Agents page. This opens a new chat session.

Agent Detail Page

The agent detail page shows the full configuration and run history for an agent. It has five tabs: Overview, Runs, Trigger, Tools, and Prompt.

Overview Tab

The Overview tab shows aggregate statistics and recent run history.

Statistics:

Metric	Description
Total Runs	The total number of runs executed by this agent.
Success Rate	The percentage of runs that completed with a success status.
Total Cost	The cumulative LLM usage cost for all runs.

Recent Runs shows the last few runs with the following columns:

Column	Description
Run ID	The unique identifier for the run. Click to open the run detail page.
Status	The terminal status of the run: success, failed, timeout, or cancelled.
Started	The timestamp when the run started.
Duration	How long the run took to complete.
Tokens	The total number of LLM tokens consumed by the run.

Run Status

Status	Description
success	The agent completed the task without errors.
failed	The agent encountered an error it could not recover from.
timeout	The run exceeded the configured time limit (run_timeout_s, default 300 seconds).
cancelled	The run was cancelled before completion.

Click View all runs → to go to the Runs tab.

Agent Definition at the bottom of the tab shows the full agent definition JSON. Click to expand it.

Runs Tab

The Runs tab lists all historical runs for this agent, with the same columns as the Recent Runs table on the Overview tab.

Click a Run ID to open the run detail page.

Run Detail Page

The run detail page shows the complete record of a single execution.

Header:

Field	Description
Run ID	The unique identifier for this run.
Status	The terminal status: success, failed, timeout, or cancelled.
Started / Completed	Start and end timestamps.
Duration	Total execution time.

Token Usage:

Field	Description
Input Token	Tokens in the LLM input context for this run.
Output Token	Tokens generated by the LLM.
Cached Token	Tokens served from the LLM prompt cache.
Cost	The LLM usage cost for this run.

Timeline shows every event in the run in chronological order:

Event type	Description
TRIGGER	The MQTT message that started the run, including the topic it arrived on.
BUNDLE LOADED	The agent's skills and configuration were loaded successfully.
CONTEXT LOADED	The conversation context was prepared.
TOOLS RESOLVED	The tools available for this run were resolved and bound.
SYSTEM INIT	The agent's prompt was applied as the system instruction.
TOOL RESULT	The result of a tool call made by the agent, for example read, run_script, or mqtt.publish. A checkmark indicates the call succeeded.
LLM CALL	An LLM invocation, with the number of calls and input and output token counts.
RESPONSE	The agent's final response text for this run.
RUN END	The terminal event, with the final status.

Click any timeline event to expand it and see the full event details.

Trigger Tab

The Trigger tab shows the event source that activates this agent.

Field	Description
Kind	The trigger type. Currently mqtt.
Trigger Topic	The MQTT topic filter the agent subscribes to. Supports wildcards (+ and #).
QoS	The MQTT QoS level for the subscription.
Connector	The name of the EMQX Broker connector used for the subscription.

Tools Tab

The Tools tab lists the tools the agent can call during a run. Each tool entry shows its name and configuration. Click a tool to expand its details.

Currently available tools:

Tool	Description
mqtt.publish	Publishes a message to an MQTT topic. Restricted to the topics listed in allowed_topics.
tables.sql	Executes a SQL query against an EMQX Tables connector. Limited to max_rows results per query.

Prompt Tab

The Prompt tab shows the instructions the agent uses for every run. The LLM generated this text during the chat session that produced this agent. It describes the agent's behavior in response to each incoming MQTT event.

The prompt is read-only on this page. To change the agent's behavior, return to the originating chat, describe the changes you want, and redeploy the agent.

Edit an Agent

You can update an agent's name and description from the agent detail page.

1. On the agent detail page, click the edit icon in the upper-right corner.
2. In the Edit Agent dialog, update the Agent Name or Description.
3. Click Save.

To change an agent's trigger, tools, skills, or prompt, return to the originating chat and redeploy. See Chats.

Restart an Agent

If an agent enters a stopped or failed state, you can restart it from the agent detail page.

1. On the agent detail page, click the restart icon in the upper-right corner.
2. The agent returns to a Running state and resumes listening for trigger events.

Delete an Agent

Important Notice

Deleting an agent stops it immediately and removes all associated run history. This action cannot be undone.

1. On the agent detail page, click the delete icon in the upper-right corner.
2. Confirm the deletion.

Next Steps

• Manage Connectors
• Start a Chat