Deploy an Agent

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

The deploy wizard adapts to your setup. The wizard asks where you want the agent to run. If the orchestrator that you select is not yet connected, the wizard adds an enrollment step. You can start the wizard from the Deploy button on the Agent 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 option to try the agent on your own machine. See Test an Agent Locally.

Select Deploy on the network and click Continue.

Step 2: Choose Where to Deploy

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

  • Network: Click Select existing and select a network from the dropdown list, or click Create a new network. See Create a Network.

  • Orchestrator: Click Select existing and select an orchestrator, or click Create a new orchestrator. The orchestrator dropdown list 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.

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 selected an orchestrator that is already running, the wizard skips 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 details about the enrollment command and the registration process, see Deploy an Orchestrator.

Step 4: Set Up Your Agent

The final step configures this specific deployment.

  • Agent name: The agent template prefills the name. This name is the human-friendly label for the deployment. Change it if you run more than one agent from the same template.

  • Sandbox Mode: Toggle to run the agent against synthetic data. The agent still executes real actions and labels them with a sandbox disclosure. See Train Your Agent (Sandbox).

  • Template parameters: Any parameters the agent 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, and the Deployed Agents tab opens with a confirmation message. The new agent appears in the table. On a running orchestrator, the agent progresses from Pending to Running within seconds. Open the agent to watch its live metrics and log stream.

If the agent template needs values that you did not supply (for example, raw ${ENV_VAR} references 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 that the agent template needs as template parameters, or provide the values as network tools, so that you supply them 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 show the details:

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

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

  • Logs: A live log stream. When the agent is between cycles, the Logs tab 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 toggles 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 on the next orchestrator check-in.

  • Delete always asks for a confirmation. The bottom action reads Stop & delete agent while the agent is running and Delete agent while the agent is stopped. The confirmation warns that you cannot undo the action and that the action 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 Description

Pending

The agent waits for the orchestrator to pick it up.

Deploying

The orchestrator provisions the agent.

Starting

The agent process starts.

Running

The agent is active and through Sense → Reason → Actuate → Reflect loop.

Idle

The agent is running, but is between cycles and waits on its trigger.

Paused

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

Stopping

The agent received a stop request and shuts down.

Stopped

The agent is halted and not running. You can start the agent again.

Stale

The orchestrator for this agent stopped its check-ins, 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 did not reach a running state, or reported a fatal error. Check the red banner and the Logs tab.

Error

The agent reported an error during a cycle and continues to run. Check the Logs tab.

Next Steps