Deploy an Agent

Deployment takes a saved agent template and runs it as a live agent inside an orchestrator on one of your networks. Every deployment starts from a template. Before you deploy, build or clone the template you want. See Create an Agent.

The deploy wizard is adaptive. It asks where you want the agent to run. The wizard only shows the orchestrator-enrollment step when the orchestrator you pick is not yet connected. You can start the wizard from the Deploy button on the Templates tab, or from Deploy agent in the Agent Builder.

Step 1: Choose How to Deploy

The first step asks, How would you like to deploy?

  • Deploy on the network: Provision and run the agent on a managed orchestrator on a HiveMQ network. This production path provides managed, monitored orchestration with an uptime service-level agreement (SLA). The rest of this page follows this path.

  • Download the agent: Run the agent locally instead, without a network. Use this when you just want to try the agent on your own machine. See Test an Agent Locally.

Select Deploy on the network and choose Continue.

Step 2: Choose Where to Deploy

Pick the network and orchestrator that run the agent. Both are required.

  • Network: Choose Select existing and pick a network from the dropdown, or click Create a new network. See Create a Network.

  • Orchestrator: Choose Select existing and select an orchestrator, or click Create a new orchestrator. The orchestrator dropdown becomes available after you select a network.

When you select an existing orchestrator, the wizard shows its Type, Status, and Communication. If the status of the orchestrator is Pending enrollment, the wizard adds the Connect your orchestrator step to the flow. That step helps you enroll the orchestrator.

To move to the next step, click Continue.

Step 3: Connect Your Orchestrator (When Needed)

This step appears only when the orchestrator you chose is not yet enrolled. If you picked an already-running orchestrator, the wizard skips straight to Set up your agent.

To enroll the orchestrator, complete the following steps:

  1. Click Copy command to copy the Docker enrollment command from the wizard.

  2. Run the command on the host where you want the orchestrator to run. The enrollment token is short-lived. The wizard shows a token-expiry countdown and a Regenerate token button if the token expires before you finish.

  3. Wait for the orchestrator to connect. While it connects, the wizard shows Waiting for first heartbeat… and Next stays disabled. As soon as the orchestrator checks in, Next becomes available.

For what the enrollment command does and how the orchestrator registers, see Deploy an Orchestrator.

Step 4: Set Up Your Agent

The final step configures this specific deployment.

  • Agent name: Pre-filled from the template. This name is the human-friendly label for the deployment. Change it if you are running more than one agent from the same template.

  • Sandbox Mode: Toggle to run the agent against synthetic data. Actuations still fire, with a sandbox disclosure attached. See Train Your Agent (Sandbox).

  • Template parameters: Any parameters the template declares appear here as fields to fill in. A template that declares no parameters shows no fields.

To continue, click Deploy agent.

After You Deploy

The wizard closes to the Deployed Agents tab and a confirmation toast appears. The new agent shows in the table and, against a running orchestrator, progresses from Pending to Running within seconds. Open the agent to watch its live metrics and log stream.

If the template needs values that you did not supply (for example, a template that references raw ${ENV_VAR} values with no declared parameters), the agent transitions to Failed / Unhealthy. A red banner that reads This agent reported issues appears on the detail header, with the failing log line (for example, "Missing required environment variables"). Declare the values the template needs as template parameters, or provide them as network tools, so they can be supplied at deploy time. See Provide Tools for Agents in a Network.

The Deployed-Agent Detail View

Click any row in the Deployed Agents table to open the agent. The header shows the agent name, its role, and its status fields (Status, State, Started, Last seen). Three tabs give you the detail:

  • Overview: Metric cards (Uptime, Total Cycles, Success Rate, Avg Cycle) and reference links to the agent’s template, network, and orchestrator, plus a list of the agent’s connections.

  • Configuration: A read-only view of the agent’s full resolved configuration.

  • Logs: A live log stream. When the agent is idle between cycles it shows "Waiting for next cycle event…".

For ongoing health monitoring across all your agents, see Monitor Agent Health.

Stop, Start, and Delete an Agent

The detail header has a Stop / Start action that tracks the state of the agent, and a delete action at the bottom of the page.

  • Stop acts immediately, with no confirmation dialog. The status changes to Stopped and the button becomes Start.

  • Start sets the status back to Pending. The agent resumes from there.

  • Delete always confirms. The bottom action reads Stop & delete agent while the agent is running and Delete agent while it is stopped. The confirmation warns that the action cannot be undone and that it permanently removes the agent from its orchestrator.

Agent Status Reference

The status badges on the agent and the Status filter on the Deployed Agents tab use the same vocabulary.

Status What it means

Pending

Queued for the orchestrator to pick up.

Deploying

The orchestrator provisions the agent.

Starting

The agent process starts.

Running

Active. Cycles through the Sense → Reason → Actuate → Reflect loop.

Idle

Up but between cycles. Waits on its trigger.

Paused

A user deliberately suspended the agent, so it does not execute cycles.

Stopping

The agent received a stop request and winds down.

Stopped

Halted and not running. You can start it again.

Stale

No recent check-in. The orchestrator for this agent has gone silent, so the last-known status can be out of date.

Removing

The agent is marked for deletion and removed from the orchestrator.

Failed

The agent reported an error or did not run. Check the red banner and the Logs tab.

Error

The agent reported an error during a cycle. Check the Logs tab.

Next Steps