Write an Agent

Build an Agent in code: a Device model, Observations, and /probe, /current, and /sample over HTTP, or an Agent embedded in your application.
MTConnect.NET Docs Menu

This recipe walks through building an MTConnect agent in code, end to end. By the end you have a running process that:

  • Holds a Device with a Controller component and a few DataItems.
  • Accepts observations.
  • Serves /probe, /current, and /sample over HTTP on port 5000.

The complete code is small: about 60 lines of C# plus a *.csproj reference.

1. Set Up the Project

Create a new console project and add the meta package:

dotnet new console -o MyAgent
cd MyAgent
dotnet add package MTConnect.NET

The MTConnect.NET meta package transitively pulls every shipped library, including MTConnect.NET-Common, MTConnect.NET-HTTP, and MTConnect.NET-XML.

2. Build the Device

In Program.cs:

using MTConnect.Devices;
using MTConnect.Devices.Components;
using MTConnect.Devices.DataItems;

// Create a Device with a Controller and an Availability data item on each.
var device = new Device
{
    Id = "mill-01",
    Uuid = "1234-5678-9abc-def0",
    Name = "Mill #1",
    Type = Device.TypeId,
};

// Attach an AVAILABILITY data item on the Device itself.
var availability = new AvailabilityDataItem(device.Id);   // id "mill-01_availability"
device.AddDataItem(availability);

// Attach a Controller with CONTROLLER_MODE and EXECUTION data items.
var controller = new ControllerComponent { Id = "ctrl" };
var mode = new ControllerModeDataItem(controller.Id);      // id "ctrl_mode"
var execution = new ExecutionDataItem(controller.Id);      // id "ctrl_exec"
controller.AddDataItem(mode);
controller.AddDataItem(execution);
device.AddComponent(controller);

AddComponent and AddDataItem set the parent-pointers automatically — you do not need to populate Container or Parent by hand. The (parentId) constructors build each DataItem ID as <parentId>_<name>.

3. Create the Agent

The agent is a MTConnectAgentBroker instance — the broker subclass of MTConnectAgent that adds an observation buffer and an asset buffer:

using MTConnect.Agents;

var agent = new MTConnectAgentBroker(
    uuid: "agent-uuid-01",
    instanceId: (ulong)DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
    deviceModelChangeTime: DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
    initializeAgentDevice: true);

agent.AddDevice(device);

The initializeAgentDevice: true argument auto-registers the self-describing Agent Device that emits agent-introspection observations.

4. Push Observations

A single observation lifecycle:

agent.AddObservation(device.Uuid, availability.Id, "AVAILABLE", DateTime.UtcNow);
agent.AddObservation(device.Uuid, mode.Id, "AUTOMATIC", DateTime.UtcNow);
agent.AddObservation(device.Uuid, execution.Id, "ACTIVE", DateTime.UtcNow);

The second argument is a DataItem key: the DataItem's id, name, or source all resolve. Omit the timestamp to stamp the observation with the current time.

The agent assigns a monotonically increasing Sequence to each observation as it enters the buffer.

5. Start the HTTP Server

MTConnectHttpServer from MTConnect.NET-HTTP (already transitive through MTConnect.NET) hosts the MTConnect endpoints for an agent broker:

using MTConnect.Configurations;
using MTConnect.Servers.Http;

var httpConfig = new HttpServerConfiguration
{
    Port = 5000,          // leave Server unset to listen on every interface
    IndentOutput = true,
    DocumentFormat = "xml",
};

var httpServer = new MTConnectHttpServer(httpConfig, agent);
httpServer.Start();

Console.WriteLine("Agent running at http://localhost:5000/probe");
Console.WriteLine("Press Ctrl-C to exit.");
await Task.Delay(Timeout.Infinite);

6. Hit the Endpoints

In another terminal:

curl -s http://localhost:5000/probe | head -30
curl -s http://localhost:5000/current | head -30
curl -s http://localhost:5000/sample?count=10 | head -30

/probe returns the Device model — Components, Compositions, DataItems — wrapped in a MTConnectDevices envelope. /current returns the most-recent observation per DataItem. /sample returns the observation history.

A /probe response looks like:

<MTConnectDevices xmlns="urn:mtconnect.org:MTConnectDevices:2.5">
  <Header creationTime="2025-01-01T12:34:56Z" sender="agent-01"
          instanceId="1735734896" version="2.5.0.0" assetBufferSize="1000"
          assetCount="0" bufferSize="150000"/>
  <Devices>
    <Device id="mill-01" uuid="1234-5678-9abc-def0" name="Mill #1">
      <DataItems>
        <DataItem category="EVENT" id="mill-01_availability" name="availability" type="AVAILABILITY"/>
      </DataItems>
      <Components>
        <Controller id="ctrl">
          <DataItems>
            <DataItem category="EVENT" id="ctrl_mode" name="mode" type="CONTROLLER_MODE"/>
            <DataItem category="EVENT" id="ctrl_exec" name="exec" type="EXECUTION"/>
          </DataItems>
        </Controller>
      </Components>
    </Device>
  </Devices>
</MTConnectDevices>

Device.AddComponent consults MTConnect.Devices.Organizers on insert and creates the Organizer a Component type requires (for example Axes around a Linear). Controller is the exception: it is added directly under Components, without a Controllers wrapper.

7. Test It

A minimal smoke test using dotnet's built-in HTTP client:

using System.Net.Http;

var http = new HttpClient { BaseAddress = new Uri("http://localhost:5000") };
var probe = await http.GetStringAsync("/probe");
Console.WriteLine(probe);

The HTTP client returns the same XML envelope the agent serves to curl.

What You Have Now

  • A running agent with one Device, one Controller, and three EVENT DataItems.
  • Observations entering the buffer with monotonic sequence numbers.
  • The four MTConnect endpoints (/probe, /current, /sample, /asset) served over HTTP.

Embedded Agent

Steps 2–5 wire the broker and the HTTP server by hand. The alternative is to host the full agent application inside your process and plug your data source in as an agent module. The agent then reads agent.config.yaml, loads the http-server module (and any others) from it, and your module writes observations into the agent directly — no separate SHDR adapter and no TCP hop between adapter and agent. Pick this shape when the data source is .NET code you control (a PLC poller, a database tail) and you want the standalone agent's configuration, logging, and module set without writing them yourself.

The runnable version lives in examples/MTConnect.NET-Agent-Embedded/:

dotnet run --project examples/MTConnect.NET-Agent-Embedded

In your own project, reference the agent host package:

dotnet add package MTConnect.NET-Applications-Agents

Entry Point

using MTConnect.Applications;

var app = new MTConnectAgentApplication();
app.Run(args, true);

MTConnectAgentApplication is the same host the standalone agent uses. Run(args, true) reads agent.config.yaml from the working directory, loads the modules listed in it — including module classes in your own assembly — and blocks until shutdown.

The Data-Source Module

using MTConnect.Agents;
using MTConnect.Configurations;
using MTConnect.Devices;
using MTConnect.Devices.Components;
using MTConnect.Devices.DataItems;
using MTConnect.Observations.Events;

public class ModuleConfiguration
{
    public string DeviceUuid { get; set; }
    public string DeviceName { get; set; }
    public string SerialNumber { get; set; }
}

public class Module : MTConnectInputAgentModule
{
    public const string ConfigurationTypeId = "datasource"; // matches the key in agent.config.yaml
    private readonly ModuleConfiguration _configuration;

    public Module(IMTConnectAgentBroker agent, object configuration) : base(agent)
    {
        Id = "DataSource Module"; // used for logging
        _configuration = AgentApplicationConfiguration.GetConfiguration<ModuleConfiguration>(configuration);
    }

    // Called once at start-up: return the Device to register with the agent.
    protected override IDevice OnAddDevice()
    {
        var device = new Device();
        device.Uuid = _configuration.DeviceUuid;
        device.Id = _configuration.DeviceName;
        device.Name = _configuration.DeviceName;
        device.AddDataItem<AvailabilityDataItem>();

        var controller = new ControllerComponent { Name = ControllerComponent.NameId };
        controller.AddDataItem<EmergencyStopDataItem>();

        var path = new PathComponent { Name = PathComponent.NameId };
        path.AddDataItem<ExecutionDataItem>();
        path.AddDataItem<SystemDataItem>();
        controller.AddComponent(path);
        device.AddComponent(controller);

        var axes = new AxesComponent { Name = AxesComponent.NameId };
        foreach (var name in new[] { "X", "Y", "Z" })
        {
            var axis = new LinearComponent { Name = name };
            axis.AddDataItem<PositionDataItem>(PositionDataItem.SubTypes.ACTUAL);
            axis.AddDataItem<LoadDataItem>();
            axes.AddComponent(axis);
        }
        device.AddComponent(axes);

        return device;
    }

    // Called every readInterval milliseconds: read the data source and emit observations.
    protected override void OnRead()
    {
        AddValueObservation<AvailabilityDataItem>(Availability.AVAILABLE);
        AddValueObservation<ControllerComponent, EmergencyStopDataItem>(EmergencyStop.ARMED);
        AddValueObservation<LinearComponent, PositionDataItem>(0.0002, "X", PositionDataItem.SubTypes.ACTUAL);
        AddValueObservation<LinearComponent, LoadDataItem>(2, "X");
        AddConditionObservation<PathComponent, SystemDataItem>(
            MTConnect.Observations.ConditionLevel.WARNING, "404", "This is an Alarm");
    }
}

MTConnectInputAgentModule is the base class for modules that produce observations. It has two hooks:

  • OnAddDevice() — runs once at start-up; the returned IDevice is added to the agent and appears in /probe. Building the model in code (rather than loading a static devices.xml) suits devices whose shape depends on what the data source reports — variable axis counts, optional sensors, serial numbers read at boot.
  • OnRead() — runs every readInterval milliseconds. AddValueObservation<TComponent, TDataItem>(value, componentName, subType) finds the DataItem by Component type, Component name, and DataItem type, so the three axes share one call shape and differ only in the axis name. AddConditionObservation does the same for CONDITION DataItems.

AgentApplicationConfiguration.GetConfiguration<T> deserializes the module's YAML section into your configuration class.

The Configuration File

modules:

- datasource:
    deviceUuid: 7E647B2D-C6A3-40BF-9CE9-FB09834850C9
    deviceName: dev-001
    serialNumber: 123456
    readInterval: 1000

- http-server:
    port: 5000

The datasource key matches ConfigurationTypeId; the fields under it map onto ModuleConfiguration, plus the inherited readInterval. Copy the file to the build output (<None Update="agent.config.yaml"><CopyToOutputDirectory>Always</CopyToOutputDirectory></None> in the *.csproj) so the agent finds it at run time, then check the result with curl http://localhost:5000/probe and curl http://localhost:5000/current.

To publish to MQTT as well, add an mqtt-relay section (see Configure the MQTT Relay). To package a module as a reusable NuGet package, see Write an Agent Module.

Where to Next

  • Add an adapter: see Write an Adapter for the ingestion side.
  • Switch to JSON output: set documentFormat: "json-cppAgent" in the HTTP config and Accept: application/mtconnect+json on the request. See JSON-CPPAGENT (v2).
  • Persist the buffer: set durable: true in agent.config.yaml (the IAgentApplicationConfiguration.Durable setting) when the agent runs under MTConnectAgentApplication, as in Embedded agent.
  • Run it via YAML: see Configure an Agent for the configuration-driven path that skips writing C# entirely.
  • Add an MQTT relay: see Configure the MQTT Relay.