Set Up Connections

The connections block names every external service your agent uses. Each connection gets a name that you reference in Sense and Actuate substages.

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. Set those values in the deploy wizard or forward them from the orchestrator.

MQTT

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

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

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

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 prepended to all request paths

timeoutMs

No

Request timeout in milliseconds (default: 30000)

headers

No

Static headers added to every request from this connection

auth

No

Authentication configuration (basic supported)

Email: 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

Verified sender address. Must be verified in your SendGrid account

to

No

Default recipient. Can be overridden in the email-send executor

Email: SMTP

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

Two provider modes share the same type: slack discriminator.

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 an MCP (Model Context Protocol) server to give it access to specialised 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).

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

Connections with names starting with __ (double underscore) are injected automatically by the platform. Do not define these in your DDA.

Connection name Provided when

__long_term_storage

A long-term-storage network tool is registered on the network

__agent_bus

An mqtt-broker network tool with isAgentBus: true is registered on the network