> This page is for DSX Flex.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/dsx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/dsx/_mcp/server.

# NVIDIA DSX Flex Grid Services Integration Guide

> Connect a grid services solution to DSX Flex, from a grid-event power-limit request through the reported response of managed loads.

Connect a grid services solution to DSX Flex, from a grid-event power-limit request through the reported response of managed loads.

## What You Will Implement

When a grid event calls for a power limit on AI factory loads managed by NVIDIA Dynamic Power Software (DPS), your grid services solution needs to send that request and interpret the reported response. Your agent integrating with DSX Flex acts as the Grid Event Publisher: it translates the requirement into a load target, sends the command through DSX Exchange, and reads Power State Status published by the DSX Flex Agent, the factory-side message role that reports the state of DPS-managed loads.

This guide covers the DPS 0.10 integration using the DSX Flex 1.7.0 schema. Capabilities beyond that baseline are called out where they affect implementation. The roles involved in this implementation are explained in more detail under [Participants and Message Boundary](#participants-and-message-boundary).

## Integration Path at a Glance

1. **Prepare the feed mapping and connection.** Map the site feeds covered by a request. Gather broker access, identifiers, and signing-key handoff.

2. **Listen, then publish.** Subscribe to Power State Status before sending a command so an early response is not missed. Build and sign the command data, wrap it as a Load Target Set (`grid.loadtarget.set.v1`) event, then publish it through DSX Exchange. This is a request to schedule and apply a constraint, not a synchronous operating result.

3. **Confirm the schedule.** The DSX Flex Agent receives the command and publishes Power State Status (`grid.powerstate.status.v1`) snapshots for all feeds. A snapshot whose relevant feed has `event` set to `target_set` says the schedule was updated; a broker acknowledgement (PUBACK) says only that the command reached Exchange. Neither says the managed load has reached the limit.

4. **Read the reported response.** Later snapshots show which target is active and the operating state DPS reports as the load changes. Use those updates to assess the managed load's response. Grid-program compliance reporting also needs the site or utility evidence that DSX Flex status does not provide.

5. **Follow the exception branch only when supported.** If the deployment supports breach and enforcement events, the DSX Flex Agent can publish a breach alert and the Infrastructure Management Agent can publish the associated enforcement outcome. Subscribe, verify, and correlate those events as part of the same target's result path; they are not a required step in the baseline exchange.

## Participants and Message Boundary

The

DSX Flex schema

identifies the participant roles in this integration. These roles and their responsibilities indicate how your integration will operate with the rest of the AI factory to handle responses.

* **Grid Event Publisher (`isv`):** Your agent signs and publishes load targets, then consumes status and supported exception events.

* **DSX Exchange:** Carries the messages between participants.

* **DSX Flex Agent (`dsx-flex-agent`):** Receives targets and publishes full power-state snapshots and, when supported, breach alerts. DPS applies the constraints through its internal power-management functions; that internal function is not another message source role.

* **Infrastructure Management Agent (`infra`):** On a supported exception path, receives breach alerts and publishes enforcement outcomes.

DSX Flex messages use CloudEvents: an outer envelope identifies the event and its sender and carries a signed data payload. The procedures below introduce each field and topic when the reader uses it.

![Baseline exchange: the Grid Event Publisher sends a load target through DSX Exchange to the DSX Flex Agent. PUBACK confirms broker receipt. A full status snapshot with target\_set reports the schedule update, without proving the limit was reached. Later snapshots report the active target and operating state.](/dsx/_fern-img/b9e7ac623a9c426379c7fa4a9011dec17f8e61d7d69b20d9b384226f1894e075.webp)

*Figure 1. Broker receipt, schedule update, and later operating status are separate signals in the baseline load-target exchange.*

Figure 1 shows the message flow when communication succeeds. The Grid Event Publisher must also monitor its Power State Status subscription for missing or unexpected updates. How it responds depends on the failure and the specific deployment.

## Prepare the Feed Mapping and Connection

1. Obtain the deployment’s configured feed tags and the site feed each identifies from the deployment operator.

2. Obtain the broker endpoint and network path, MQTT authentication mode and credentials, topic permissions, and publisher and agent identifiers from the deployment operator. At the same time, confirm supported event paths and the expected status heartbeat cadence.

3. Obtain an ES256- or RS256-compatible signing key pair and its `kid`. With the operator, coordinate registration of your public signing key and obtain the public keys needed to verify DSX Flex Agent status and, when supported, Infrastructure Management Agent enforcement events.

4. Deploy the publisher where it can reach the broker and protect both broker and signing credentials. Use an MQTT 3.1.1 SDK with the assigned authentication mode. Use the

   DSX Exchange Integrator Quickstart

   and

   Authentication guide

   for broker connectivity and permissions. For each Flex publish or subscription, use its linked operation page for the topic, message format, and MQTT delivery level (QoS).

## Subscribe and Publish the Load Target

A load target is a requested power constraint and the interval in which it applies. One `grid.loadtarget.set.v1` command can contain one or more targets. Build its plaintext JSON data first, sign that data, and then publish it inside a CloudEvent.

1. **Subscribe to status.** Subscribe to

   Power State Status

   on `grid/v1/dsx-flex-agent/{agentIdentifier}/powerstate/status` with the assigned permissions before sending the first command. Use the assigned DSX Flex Agent identifier and keep the subscription active to receive an early response. The DSX Flex Agent publishes full status snapshots periodically, independently of your subscription or commands; use the first snapshot received after subscribing as your initial view of the managed feeds.

2. **Build the load-target data.** Create `SetLoadTargetData` with at least one item in `targets`. Each item needs `interval` and `load_constraint`; use `feed_tags` to select feeds and `strategy` when needed:

   * **Power limit and unit.** Set `load_constraint` to the requested limit for the grid event, expressed in watts, kilowatts, or megawatts.

   * **Timing.** Set `interval` to when the target applies. `interval.start_time` defaults to immediate application when omitted; without `interval.end_time`, the target remains until replaced.

   An omitted or empty `feed_tags` list applies the target to all feeds. The

   DSX Flex schema

   supplies the complete field definitions and allowed values.

3. **Sign the data.** Sign the plaintext JSON data payload with JWS using ES256 or RS256, and include the signing-key identifier in the protected `kid` header. Put the resulting JWS compact serialization string in the CloudEvents `data` field. The wire-format `data` value is the signed string, not the unsigned JSON object.

4. **Wrap the command.** Build a structured CloudEvent JSON envelope around the signed data. Include its required attributes in these groups:

   * **Event identity:** `specversion: "1.0.2"`, a new UUIDv4 `id`, `source: "//grid/v1/isv/{publisherIdentifier}"`, and `type: "grid.loadtarget.set.v1"`.

   * **Context:** `time` as an ISO 8601 timestamp, `datacontenttype: "application/json"`, a resource `subject` such as `"loadtarget"`, and a W3C Trace Context `traceparent`. Propagate optional `tracestate` when present.

   * **Payload and matching:** the signed `data` string. A UUIDv4 envelope `correlationid` is optional in the published schema and recommended to associate a command with later status.

5. **Validate and publish.** Check the completed message against the

   DSX Flex message format and signing rules

   . Use the same assigned `{publisherIdentifier}` in the source and the publish topic, then

   publish Load Target Set

   to `grid/v1/isv/{publisherIdentifier}/loadtarget/set`. A broker PUBACK confirms receipt of that publish, not a schedule update or operating result.

**Target ramp rate.** To follow a site-defined target ramp rate—the expected pace of change in DPS-managed load—repeat steps 2–5 for each stage, publishing a separate Load Target Set message for the affected feeds. Set each target’s interval and power limit so the first makes an incremental change, intermediate targets progress at the desired pace, and the final target reaches the intended limit. Compare subsequent Power State Status snapshots with that sequence.

**Other target choices.** `strategy.best_effort` defaults to `false`. Set `load_constraint` to `null` to remove an active grid constraint and return the affected feed to its configured default constraint.

## Example: Map a Grid Event to a DSX Flex Command

Suppose a grid event calls for a 500-kilowatt limit on feed `main-a` for a defined interval. Your Grid Event Publisher maps that requirement into this outbound DSX Flex `SetLoadTargetData` payload:

```json
{
  "targets": [
    {
      "interval": {
        "start_time": "START_TIME_UTC",
        "end_time": "END_TIME_UTC"
      },
      "feed_tags": ["main-a"],
      "load_constraint": { "value": 500, "unit": "kilowatt" }
    }
  ]
}
```

For a real command, the publisher fills in the requested start and end times, signs the completed data payload, and places the resulting JWS compact string in a CloudEvent envelope. The outbound wire message then has this shape:

```json
{
  "specversion": "1.0.2",
  "id": "EVENT_UUID_V4",
  "source": "//grid/v1/isv/PUBLISHER_IDENTIFIER",
  "type": "grid.loadtarget.set.v1",
  "time": "EVENT_TIME_UTC",
  "datacontenttype": "application/json",
  "subject": "loadtarget",
  "correlationid": "COMMAND_UUID_V4",
  "traceparent": "W3C_TRACEPARENT",
  "data": "JWS_HEADER.JWS_PAYLOAD.JWS_SIGNATURE"
}
```

Uppercase values are placeholders; supply actual values and the signed JWS before publishing. The example includes the recommended but schema-optional `correlationid`.

## Interpret Power-State Status

The DSX Flex Agent publishes full snapshots for all feeds, including updates unrelated to your latest command. Verify the agent's JWS signature in the CloudEvents `data` field before decoding `PowerStateStatusData`. Use `snapshot_time` and the relevant feed's target and operating fields together; one status field alone is not an operating result.

First, inspect `feeds.<feed_tag>.event` in the verified status payload. A value of `target_set` means the schedule was updated; check that the reported target, feed scope, and interval match the command. It does not mean the requested load has already been reached. A broker PUBACK is an earlier transport signal and cannot substitute for this status.

Then follow later snapshots as the interval starts, the target becomes active, and the managed load changes. A feed's `targets[]` includes active and scheduled entries; `active: true` marks a target currently being enforced. Read the active target with these reported fields:

* When a transition begins, the DSX Flex Agent publishes a Power State Status snapshot whose affected feed reports `start_ramp_down` or `start_ramp_up` as its `event` value. Use an `end_ramp_down` or `end_ramp_up` status and its `snapshot_time` to report when DPS says the transition completed.

* `calculated_load`, `in_flight`, and `compliant` describe the state known to DPS. `calculated_load` can differ from measured facility power during a transition. `compliant` can also be true when no target is active; for an active target, check it before reporting that the limit was met.

* `periodic` is a heartbeat without a state change; its cadence is deployment-specific. Use the cadence confirmed during setup to recognize a late heartbeat.

To associate a snapshot with the command, distinguish identifiers by their location in the message:

| **Identifier**   | **Where to find it**                                   | **Published schema**                                           |
| ---------------- | ------------------------------------------------------ | -------------------------------------------------------------- |
| `id`             | Every CloudEvent envelope                              | Required; identifies this event instance.                      |
| `correlationid`  | Load-target or status CloudEvent envelope              | Optional; associates a command with a later event when echoed. |
| `correlation_id` | A status snapshot's `feeds.<feed_tag>.targets[]` entry | Optional; associates that reported target with its command.    |

Use the later active target and operating snapshot to say what DPS reports about the managed load. Power-state status is one input to grid-program reporting, not a complete utility-compliance record. The grid services solution must obtain and reconcile the site metering and program evidence required by the applicable grid program or utility.

## Handle the Exception Branch When Supported

A Power Breach Alert reports a detected exceedance of a feed's load target, with the target constraint and measured load at the event. The alert alone does not establish whether DPS can subsequently meet the target.

When breach alerts (`grid.powerbreach.alert.v1`) and enforcement outcomes (`grid.powerbreach.enforcement.v1`) are supported, as confirmed during connection setup, extend the result path as follows:

1. Subscribe with the assigned permissions to the

   breach alert

   and

   enforcement outcome

   topics. Verify each event sender's signature before processing its data. Both linked breach and enforcement operations specify MQTT QoS 2; use that setting when subscribing to those events.

2. When a breach alert arrives, use its required `target.correlation_id` to associate the alert with the target. That requirement differs from the optional `correlation_id` in a power-state status target. Retain `breach.breach_id` across lifecycle updates and for the enforcement outcome.

3. Follow `status` (`active`, `escalated`, or `resolved`) for the alert's lifecycle, and read `severity` and `measured_load` with the target limit. The alert can include advisory `shed_hints`; its `infrastructure_actions` list describes possible infrastructure responses.

4. Match an enforcement event to the alert by `breach_id`, then read `action` (`applied` or `reverted`), the overall `code` (`success`, `partial`, or `error`), and the per-resource `results`. Do not treat an alert or a suggested action as evidence that enforcement occurred.

## Verify the Basic Integration Path

These are minimum end-to-end checks for the message path described here. They show whether the publisher can send a target and interpret DSX Flex's reported response; they do not by themselves establish production readiness or grid-program compliance. Use a known grid-event request to exercise the sequence:

1. Confirm broker connectivity, authentication, and topic permissions. Subscribe to status before sending the command.

2. Publish a schema-valid signed command with a known limit, feed scope, and interval. Check for `target_set` with the expected schedule. This establishes that the target was accepted into the schedule, not that the limit was reached.

3. Exercise activation and expiration. Inspect the active target, transition event, `in_flight`, `calculated_load`, and `compliant` before reporting that DPS says the managed load met the target. After a target with an `end_time` expires, confirm it is no longer active. Keep site-level compliance evidence separate.

4. Test invalid fields and signatures, reconnect and duplicate delivery, periodic and delayed or out-of-order snapshots, and commands from another publisher. If the deployment supports exception events, also test alert lifecycle and alert-to-enforcement correlation.

Extend these checks with the deployment's failure, scale, performance, and program-specific reporting tests before production use. If the site specifies a ramp-rate expectation, record it and compare reported load and timing across successive Power State Status snapshots. With multiple scheduled targets, also check the reported schedule and active target at transitions or overlaps.

## Roadmap

* **Breach signaling:** Planned after DPS 0.10, with Q4 2026 as the current target.

* **Native ramp rate and target severity support:** Anticipated for Q1 2027. The DSX Flex 1.7.0 load-target message carries neither field. Where supported, an integration can approximate a ramp by scheduling multiple targets; native support would let the publisher specify the requested rate in the message. Target severity would let the publisher assign severity to a constraint for use in a resulting breach notification if DPS cannot meet it.

These dates and feature details are planning expectations and may change.

## References

* DSX Flex 1.7.0 overview

* DSX Flex schema definitions

* [DSX Flex AsyncAPI YAML](https://github.com/dsx-ai-factory/dsx-exchange/blob/main/schemas/asyncapi/dsx-flex/dsx-flex.yaml)

* DSX Exchange Integrator Quickstart

* DSX Exchange Authentication

## DSX Exchange References

* [DSX Flex schema](https://docs.nvidia.com./dsx-exchange/schema/dsx-flex/overview#source-format)
* [DSX Exchange Integrator Quickstart](https://docs.nvidia.com./dsx-exchange/integrator-quickstart)
* [DSX Exchange Authentication](https://docs.nvidia.com./dsx-exchange/authentication)
* [Power State Status](https://docs.nvidia.com./dsx-exchange/schema/dsx-flex/operations/subscribepowerstatestatus)
* [DSX Flex schema definitions](https://docs.nvidia.com./dsx-exchange/schema/dsx-flex/schemas)
* [DSX Flex 1.7.0 overview](https://docs.nvidia.com./dsx-exchange/schema/dsx-flex/overview)
* [publish Load Target Set](https://docs.nvidia.com./dsx-exchange/schema/dsx-flex/operations/publishloadtargetset)
* [breach alert](https://docs.nvidia.com./dsx-exchange/schema/dsx-flex/operations/subscribepowerbreachalert)
* [enforcement outcome](https://docs.nvidia.com./dsx-exchange/schema/dsx-flex/operations/subscribepowerbreachenforcement)