Set Up Connections

An agent uses external services, such as MQTT brokers, databases, REST APIs, and email providers, to collect data and take action. A connection defines how the agent reaches a service. You give each connection a name and reference the name in the Sense and Actuate substages.

You enter connection details in the Connections stage (stage 02) of the Agent Builder. The builder saves your entries in the connections block of the agent template YAML file.

This page documents each connection type, including the fields and their meaning, and the YAML that the builder writes. Use the field descriptions to complete the Connections stage in the Agent Builder. Use the YAML reference when you review a downloaded agent template or edit the YAML directly.

Not every external service appears in the connections block:

 
connections:
  my-connection-name:
    type: mqtt # Connection type
    # ... type-specific fields

Use ${ENV_VAR} syntax in any connection field to pull values from environment variables. Use ${ENV_VAR:-default} to fall back to a default value when the variable is not set. Set the values in the deploy wizard or forward them from the orchestrator.

Never enter secret values, such as passwords and API keys, directly in a connection field. Always reference secrets through environment variables.

Manage Connections in the Agent Builder

The Connections stage shows one card per connection. Each card shows the connection name, a type badge, and the common fields for the type. For an MQTT connection, the fields are URL, Client ID, Username, Password, Keepalive, and Reconnect Period. Each form field corresponds to a YAML key in the tables on this page. For example, the Client ID field sets the clientId, and the Reconnect Period field sets the reconnectPeriod.

To add a connection, click Add new connection. To remove a connection, click the delete icon on the card.

The form shows common fields for each connection type. For options that the form does not show, such as the tls block, edit the agent template YAML.

The Agent Builder does not yet include an inline YAML text editor. To edit the agent template YAML, download the agent template from the builder menu, edit the file, and import it on the Agent Templates tab.

MQTT

Subscribe to topics on a broker and publish messages to the broker:

connections:
  factory-mqtt:
    type: mqtt
    url: mqtt://broker.hivemq.com:1883 # Use mqtts:// for TLS
    clientId: quality-monitor-${uuid()} # Use ${uuid()} to ensure uniqueness
    username: ${MQTT_USER} # Optional
    password: ${MQTT_PASS} # Optional
    keepalive: 60 # Seconds between keep-alive pings
    reconnectPeriod: 1000 # Milliseconds before reconnection attempt
    tls: # Optional — for mqtts:// connections
      ca: ${MQTT_CA_PEM} # CA certificate PEM (overrides system trust store)
      cert: ${MQTT_CLIENT_CERT_PEM} # Client certificate PEM (mutual TLS)
      key: ${MQTT_CLIENT_KEY_PEM} # Client private key PEM (mutual TLS)
      rejectUnauthorized: true # Set false for dev/test only
      servername: broker.example.com # SNI override when CN doesn't match URL hostname
Field Required Description

type

Yes

mqtt

url

Yes

Broker URL. Supports mqtt://, mqtts://, ws://, wss://

clientId

No

MQTT client ID. Use ${uuid()} to avoid ID conflicts.

username

No

Broker authentication username.

password

No

Broker authentication password.

keepalive

No

Keep-alive interval in seconds (default: 60).

reconnectPeriod

No

Reconnection delay in milliseconds.

tls

No

TLS configuration. All PEM fields take full PEM-encoded text.

PostgreSQL

Connect to a PostgreSQL database:

connections:
  quality-db:
    type: postgresql
    host: ${DB_HOST:-localhost}
    port: 5432
    database: factory_data
    username: ${DB_USER}
    password: ${DB_PASSWORD}
    ssl: true # Optional, enables TLS
    poolSize: 5 # Optional, connection pool size

MySQL

Connect to a MySQL database:

connections:
  legacy-db:
    type: mysql
    host: ${MYSQL_HOST}
    port: 3306
    database: production
    username: ${MYSQL_USER}
    password: ${MYSQL_PASSWORD}

REST API

Call a REST API:

connections:
  erp-api:
    type: api
    baseUrl: https://erp.internal.example.com
    timeoutMs: 10000 # Request timeout in milliseconds
    headers:
      Authorization: 'Bearer ${ERP_API_TOKEN}'
      Content-Type: application/json

  # With basic auth
  scada-api:
    type: api
    baseUrl: https://scada.internal.example.com
    auth:
      type: basic
      username: ${SCADA_USER}
      password: ${SCADA_PASS}
Field Required Description

type

Yes

api

baseUrl

Yes

Base URL that the connection prepends to all request paths.

timeoutMs

No

Request timeout in milliseconds (default: 30000).

headers

No

Static headers that the connection adds to every request.

auth

No

Authentication configuration (basic supported).

Email: SendGrid

Send email through SendGrid:

connections:
  alert-email:
    type: email
    provider: sendgrid
    apiKey: ${SENDGRID_API_KEY}
    from: alerts@example.com # Must be a verified sender in SendGrid
    to: ${ALERT_TO:-ops@example.com} # Default recipient (can be overridden per executor)
Field Required Description

type

Yes

email

provider

Yes

sendgrid

apiKey

Yes

SendGrid API key.

from

Yes

Sender address. Verify the address in your SendGrid account first.

to

No

Default recipient. The email-send executor can override the default recipient.

Email: SMTP

Send email through an SMTP server:

connections:
  smtp-email:
    type: email
    provider: smtp
    host: smtp.example.com
    port: 587
    secure: false # true for port 465 (TLS), false for STARTTLS
    auth:
      user: ${SMTP_USER}
      pass: ${SMTP_PASS}
    from: alerts@example.com
Field Required Description

port

Yes

Usually 465 (TLS) or 587 (STARTTLS).

secure

No

true for implicit TLS (port 465), false for STARTTLS (port 587).

Slack

Both Slack provider modes use type: slack. The provider field selects the mode:

connections:
  # Incoming Webhook — simplest, no bot token needed
  ops-slack-webhook:
    type: slack
    provider: webhook
    webhookUrl: ${SLACK_WEBHOOK_URL}

  # Bot Token — supports channel selection per-action
  ops-slack-bot:
    type: slack
    provider: bot
    botToken: ${SLACK_BOT_TOKEN}
    defaultChannel: '#ops-alerts'

MCP Server

Connect your agent to a Model Context Protocol (MCP) server to give the agent access to specialized tools and knowledge:

connections:
  knowledge-mcp:
    type: mcp-server
    url: https://mcp.internal.example.com
    transport: sse # sse | streamable-http | stdio
    tools:
      - search_knowledge_base
      - get_document
    resources:
      - knowledge://product-specs

Register MCP servers as network tools at the network level, not per agent. All agents on the network can then use them, with no changes to each data-defined agent (DDA). See Provide Tools for Agents in a Network.

Naming Conventions

Connection names must be unique within a data-defined agent (DDA) and are case-sensitive. Use descriptive names that reflect the service purpose:

# Good
connections:
  factory-mqtt:     # Clear: MQTT, factory environment
  quality-db:       # Clear: database, quality data
  alert-email:      # Clear: email, alert purpose

# Avoid
connections:
  conn1:            # Not descriptive
  myMqtt:           # Inconsistent casing

Infrastructure-Injected Connections

The platform automatically injects connections whose names start with __ (double underscore). Do not define these connections in your DDA.

Connection name Provided when

__long_term_storage

The network has a long-term-storage tool.

__agent_bus

The network has an mqtt-broker tool with isAgentBus: true.