Get Started

The fastest way to a working agent is to describe what you want to Bea, the AI assistant of the HiveMQ Platform. An agent has many parts: sense sources, reasoning, actions, autonomy lanes. Rather than write a data-defined agent (DDA) by hand, tell Bea your goal. Bea turns your plain-language description into a complete, ready-to-deploy agent definition. You then fine-tune the definition, deploy it, and watch the agent run.

This guide takes you from an empty screen to a running agent on a network that you control.

Before You Start

  • You have Docker installed and running on the machine where the agent will run. The deployment wizard gives you a command to start the orchestrator that hosts your agent.

Step 1: Open Act and Start a New Agent

  1. Open the Act tab.

  2. Click Create Agent.

Step 2: Describe What You Want to Achieve

The Create Agent dialog opens so you can describe what you want and let Bea draft the agent template for you. Tell Bea your goal in your own words. For example, "Watch my factory’s temperature topic and alert me when a reading goes above 35 °C, but ask me before stopping the line."

You can start the agent definition in three ways:

  • Describe your goal: Type your goal into the Ask Bea field and send it. Bea defines the agent for you.

  • Use a quick-prompt chip: Select one of the suggested chips, such as Alert on temperature anomalies, Log sensor readings, or Coordinate predictive maintenance. Bea builds the agent from the prompt of the chip.

  • Start from a template: Select Browse agent templates to select a predefined template from the Marketplace. This path has one extra step: clone the template into the builder before you continue. For complete details, see Start from a Marketplace Template.

Step 3: Review the Prefilled Agent Definition

The agent definition opens in the builder, prefilled with everything Bea inferred from your description: the sense sources, the reasoning, the actions, and the autonomy lane for each action.

If you want, fine-tune the stages. Adjust a threshold, change a topic, or move an action to a stricter autonomy lane. You can also refine the stages later. For information about what each stage does, see Configure an Agent.

Step 4: Start the Deploy Wizard

  1. Click Deploy Agent.

  2. On How would you like to deploy?, select Deploy on the network (recommended).

    You can download the agent and run it locally for quick testing, but you lose visibility of the agent in the HiveMQ Platform. Local agents do not appear in your fleet, health monitoring, or feedback views. For instructions, see Test an Agent Locally.

Step 5: Choose Where to Deploy

In the deploy wizard, select or create the network and orchestrator that run the agent:

  • A network groups your orchestrators and shared resources, such as databases, APIs, and the agent bus. If you do not have a network, use the wizard to create one. See Create a Network.

  • An orchestrator is the software that runs and manages your agents on your own infrastructure as Docker containers. Select an existing orchestrator, or use the wizard to create a new one.

The deploy wizard guides you through the process to create either a network or an orchestrator if you don’t already have one.

Step 6: Connect Your Orchestrator

If you selected an orchestrator that is not yet enrolled, the deploy wizard adds a Connect your orchestrator step. If you selected an orchestrator that is already running, the wizard skips to the next step.

The wizard displays a docker run command with a single-use enrollment token already filled in. Copy the command and run it on the machine where you want the agent to run:

docker run -d \
  --name hivemq-agentic-orchestrator \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v hivemq-agentic-orch-state:/var/lib/hivemq-agentic \
  -e CONTROL_PLANE_URL=<shown-by-wizard> \
  -e HIVEMQ_AGENTIC_REGISTRATION_TOKEN=<shown-by-wizard> \
  ghcr.io/hivemq/hivemq-agentic-orch-docker:latest \
  orchestrator

Copy the exact command from the wizard. The command already contains the correct URL and token. The token expires after a short time. If it expires, click Regenerate token to display a new command. For the full reference, see Deploy an Orchestrator.

The wizard waits for the first heartbeat of the orchestrator. Within a few seconds, the wizard confirms the connection, and you can continue.

Step 7: Set Up Your Agent

On the final Set up your agent step, complete the following fields:

  1. Enter a name for the agent. The template prefills the name. Adjust the name if needed.

  2. Decide whether to enable Sandbox Mode. In Sandbox Mode, the agent runs against synthetic data. The agent still executes real actions and labels them with a sandbox disclosure. See Train Your Agent (Sandbox).

  3. Enter any template parameters the agent declares. These are the parameters that you defined in the builder’s Parameters section as a field. If the template declares no parameters, this step shows no fields.

If a template relies on values that it does not declare as parameters, no fields appear for them. The agent can fail at runtime with a missing-value error. Declare the values you need as parameters in the builder so that the wizard prompts for them.

Step 8: Deploy

Click Deploy Agent. The orchestrator picks up the agent on its next check-in and starts it.

Track progress in the Deployed Agents tab under Act. The agent status changes from Pending to Running. Open a running agent to watch each cycle, check its health, and respond to any feedback requests it raises.

Next Steps