Getting Started

The fastest way to get a working agent is to describe what you want and let Agent Bea build it for you. An agent has many parts: sense sources, reasoning, actions, autonomy lanes. Rather than write a data-defined agent (DDA) by hand, you tell Agent Bea your goal, and it produces a complete, deployable agent definition. You then fine-tune, deploy, and watch it run.

This guide takes you from an empty screen to a running agent on a network 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.

Agent Bea is the built-in assistant in Act. It turns a plain-language description of your goal into a ready-to-deploy agent definition.

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 Agent 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 prompt the agent in three ways:

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

  • Use a quick-prompt chip: Select one of the suggested chips (Alert on temperature anomalies, Log sensor readings, Coordinate predictive maintenance) and Agent Bea builds from that.

  • Start from a template: Select Browse agent templates to pick 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 Agent Bea inferred from your description: the sense sources, the reasoning, the actions, and the autonomy lane for each action.

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

Step 4: Start the Deploy Wizard

  1. Select Deploy Agent.

  2. On How would you like to deploy?, choose 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 the agent should run on:

  • 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.

  • 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 chose an orchestrator that is already running, the wizard skips straight to the next step.)

The wizard displays a docker run command with a single-use enrollment token already filled in. Copy it 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. It already contains the correct URL and token. The token expires after a short time. If it expires, select Regenerate token to display a fresh command. See Deploy an Orchestrator for the full reference.

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

Step 7: Set Up Your Agent

On the final Set up your agent step:

  1. Give the agent a name. The name is pre-filled from the template, so adjust it if you want.

  2. Decide whether to enable Sandbox Mode. In sandbox mode the agent runs against synthetic data. Actuations still fire, with a sandbox disclosure. See Train Your Agent (Sandbox).

  3. Fill in any template parameters the agent declares. These are the parameters defined in the builder’s Parameters section, which appear here as fields. If the template declares no parameters, this step shows none.

If a template relies on values it does not declare as parameters, no fields appear here to supply them, and the agent can fail at runtime with a missing-value error. Declare the values you need as parameters in the builder so 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