Configure an Agent

The Agent Configuration stage (stage 01 in the Agent Builder) is where you set the identity of the agent and the settings that apply across its whole lifecycle:

  • The name, role, and description of the agent.

  • The AI model that the agent uses.

  • The values that the agent expects at deploy time.

  • How the platform records the activity of the agent.

  • When the agent stops.

This page covers these 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 that people can recognize the agent in logs, dashboards, and alerts.

Field Required Description

Name

Yes

The identifier of the agent. The name appears in logs, metrics, and dashboards.

Version

No

A semantic version string for the template. For example, 1.0.0.

Description

No

An optional free-text description that appears in the Control Plane.

Role

No

A category used to group agents by function. The following roles are available: Monitor, Analyst, Responder, Processor, Publisher, Alerter, Replayer, Orchestrator, Gateway, Collector, Technician, and Tester.

Job Title

No

A human-readable title that appears in workforce views of the Control Plane. For example, "Quality Analyst".

Parameters

Parameters are values that 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. If the agent is fully deterministic, skip the section. The agent then runs 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. The available models change over time. Current examples 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 default API endpoint URL of the provider.

Supply the API key of the provider 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 the trigger 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 record of each cycle and appends it to the hash of the previous cycle. 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. With memory, the platform holds records in process memory and discards them on restart (use for development). With file, the platform writes records to a file on disk. With postgres, the platform writes records to a PostgreSQL database.

Audited stages

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

Enable anchoring

Periodically snapshot the audit chain so that 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 the agent 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

Next Steps

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.