Configure an Agent

The Agent Configuration stage (stage 01 in the Agent Builder) is where you give the agent its identity and the settings that apply across its whole lifecycle: who it is, what AI model it uses, what values it expects at deploy time, how the platform records its activity, and when it stops.

This page covers those cross-cutting settings. You configure the data the agent works with in the later stages. See Set Up Connections, Sense Data, Reason on Data, Act on Data, and Reflect on Agent Execution.

Identity

The Identity section names the agent and describes its role so people can recognize it in logs, dashboards, and alerts.

Field Required Description

Name

Yes

The agent’s identifier. Appears in logs, metrics, and dashboards.

Version

No

A semantic version string for the template (for example, 1.0.0).

Description

No

Free-text description that appears in the Control Plane.

Role

No

A category used to group agents by function. Choose from: Monitor, Analyst, Responder, Processor, Publisher, Alerter, Replayer, Orchestrator, Gateway, Collector, Technician, and Tester.

Job Title

No

A human-readable title (for example, "Quality Analyst") that appears in workforce views.

Parameters

Parameters are values the template declares but does not hard-code. For example, a site name, a threshold, or a recipient address. Each declared parameter appears as a field in the Set up your agent step of the deploy wizard. As a result, you can deploy the same template many times with different values.

In the Parameters section, click Add parameter and give the parameter a name. A parameter name must use lowercase letters, digits, and underscores only, and must start with a letter.

Declare a parameter for every value you want to set at deploy time. A template that relies only on raw ${ENV_VAR} references, with no declared parameters, shows no fields in the deploy wizard. The template can also fail at runtime if those values are missing.

Large Language Model (LLM) Configuration

If any stage uses natural-language reasoning, configure an AI model in the LLM Configuration section. Agents that are fully deterministic need no model. Leave this unconfigured to run with no model cost or latency.

Click Configure LLM and set the following fields:

Field Description

Provider

The model provider: OpenRouter, Anthropic, OpenAI, or Ollama. OpenRouter gives access to many models through one provider.

Model

The model to use. Available models include Claude Sonnet 4.6, Claude Sonnet 4, Claude Opus 4.7, Claude Opus 4, Claude Haiku 4.5, GPT-4o, GPT-4o Mini, Gemini 2.5 Pro, Gemini 2.0 Flash, Llama 3.3 70B, and Mistral Large.

Temperature

Sampling temperature. Lower values produce more consistent, predictable outputs.

Max tokens

The maximum number of tokens the model returns per call.

Endpoint

An optional override for the provider’s default API endpoint URL.

The provider’s API key is supplied as an environment variable (for example OPENROUTER_API_KEY, ANTHROPIC_API_KEY, or OPENAI_API_KEY). Set it in the deploy wizard or forward it from the orchestrator.

Trigger

The trigger decides when each agent cycle starts: on a fixed interval, on a cron schedule, or when an MQTT message arrives. Configure it in the Trigger section of this stage. For the trigger types and their fields, see Set a Trigger to Run an Agent Cycle.

Human Oversight

The Autonomy section sets how much independence the agent has. The options range from full autonomy to human approval for every action. For the full guide, see Set Human Oversight.

Audit Trail

An audit trail records what the agent did each cycle: what it sensed, what it decided, and what it acted on. The platform cryptographically hashes each cycle’s record and appends it to the previous cycle’s hash. Any later tampering breaks the chain and becomes detectable. Audit trails support traceability and compliance needs such as the EU AI Act, FDA 21 CFR Part 11, and ISO 9001.

The Audit Trail section carries an Orchestrated only badge: these settings apply when the agent runs under an orchestrator. Configure the following fields:

Field Description

Algorithm

The hash algorithm: Sha256, Sha3 256, or Blake2b 256.

Type

Where the platform stores records: memory (held in process memory and lost on restart, use for development), file (written to a file on disk), or postgres (written to a PostgreSQL database).

Audited stages

Which of the four stages (Sense, Reason, Actuate, Reflect) the platform records. Set each to Not set, Include, or Exclude.

Enable anchoring

Periodically snapshot the audit chain so a fixed reference point exists for later verification.

Enable redaction

Remove or mask sensitive values from recorded data before storage.

Currently, you configure the audit trail here, but there is no in-app surface to view recorded audit or decision data. The platform writes recorded data to the storage backend you configure (memory, file, or a Postgres database) for retrieval outside the HiveMQ Platform.

Termination

By default, an agent runs continuously, cycle after cycle, until you stop it. The Termination section lets you set conditions that stop it automatically. All fields are optional. If you do not set any conditions, the agent runs continuously.

Field Description

Maximum cycles

Stop after this many cycles.

Maximum errors

Stop after this many errors.

Maximum duration (ms)

Stop after this many milliseconds of run time.

Condition

Stop when this expression evaluates to true.

YAML Field Reference

The Agent Builder writes a YAML template. The fields below correspond to the sections above. The only required top-level fields are name, trigger, and stages. Everything else is optional.

Identity and Top-Level Fields

name: QualityMonitor      # Required. Shown in logs, dashboards, and alerts.
version: '1.0.0'          # Optional. Semantic version string.
description: |            # Optional. Shown in the Control Plane.
  Monitors production quality metrics and alerts on threshold violations.
role: Monitor             # Optional. Groups agents by function.
jobTitle: Quality Analyst # Optional. Shown in workforce views.

LLM Configuration

llm:
  provider: openrouter      # openrouter | anthropic | openai | ollama
  model: anthropic/claude-sonnet-4
  temperature: 0.2          # Lower = more predictable outputs.
  max_tokens: 1024          # Maximum output tokens per call.
  endpoint: https://...     # Optional. Override the provider's default endpoint.

# Or omit the model entirely for a fully deterministic agent:
llm: null

Audit Trail

audit:
  enabled: true
  algorithm: sha256         # sha256 | sha3-256 | blake2b-256
  anchor:
    enabled: true           # Periodic chain snapshots
    intervalCycles: 100     # Cycles between anchor points
  storage:
    type: postgres          # memory | file | postgres
    options:
      connectionString: ${AUDIT_DB_URL}  # Required for the postgres type

Termination

termination:
  maxCycles: 100            # Stop after 100 cycles
  maxErrors: 5              # Stop after 5 errors
  maxDurationMs: 86400000   # Stop after 24 hours
  condition: '...'          # Stop when this expression is true

For the connection, trigger, stage, and autonomy blocks, see the dedicated pages: Set Up Connections, Set a Trigger to Run an Agent Cycle, Sense Data, Reason on Data, Act on Data, Reflect on Agent Execution, and Set Human Oversight.