> 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 Architecture > Understand the participant roles, event lifecycles, and system boundaries defined by NVIDIA DSX Flex. The public DSX Flex event model establishes how grid-facing power requirements enter an AI factory, how participating systems report operating state and exceptions, and which decisions remain local. These boundaries help NCPs plan the factory-side response and give integrators the context needed before implementation-specific configuration and validation. ## What the Flex Schema Standardizes The DSX Flex schema provides the shared event model that independently implemented systems use to exchange power intent and reported outcomes through DSX Exchange. It standardizes participant roles and publisher responsibilities, versioned event types, topic and payload structures, lifecycle states, correlation fields, and message-security requirements. The schema does not prescribe how targets are validated, how local schedules are implemented, where telemetry originates, which workload or site controls respond, or how advisory infrastructure actions are evaluated. Those decisions remain with each participating solution and the deployment's operating policy. ### Read the Generated Reference and Source Together The operation, message, and schema pages are generated from the same AsyncAPI definition. Start with an operation page to identify the MQTT topic, publishing and subscribing roles, and message type. Then follow the message to its payload schema for required fields, allowed values, and referenced objects. Some nested objects and arrays appear as references instead of being fully expanded in the generated page. If the page does not show an object's complete structure, open the Raw AsyncAPI Spec . A `$ref` entry points to another named definition in the same specification; follow its path into `components.schemas`. For an array, `items` either defines each entry directly or points to its definition with another `$ref`. The [versioned AsyncAPI source](https://github.com/dsx-ai-factory/dsx-exchange/blob/main/schemas/asyncapi/dsx-flex/dsx-flex.yaml) contains the same contract. ## How Flex Participants Relate The DSX Flex schema assigns event responsibilities to three logical participant roles: | Role | Event responsibility | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Grid ISV** (`isv`) | Represents the grid-services participant or software, publishes a time-bound load target, and observes reported operating state and exception outcomes. | | **DSX Flex Agent** (`dsx-flex-agent`) | Receives load targets and publishes power-state status and breach alerts. | | **Infrastructure Management Agent** (`infra`) | Receives breach alerts and publishes infrastructure-enforcement outcomes when infrastructure enforcement is used. | The parenthesized values are schema role identifiers. A participant uses its role identifier in the CloudEvents `source` attribute and corresponding Flex topic paths. See the source format in the authoritative schema. Each role identifies the events a participant publishes or receives. ## How Flex Uses DSX Exchange Each participant connects to NVIDIA DSX Exchange as an MQTT client. Publishers send events to topics, the Exchange broker routes them, and authorized subscribers receive them. Each event is a structured CloudEvent encoded as JSON. The topic identifies the operation and publisher, the CloudEvent metadata identifies the event and its source, and the signed `data` field contains the event-specific payload. Exchange and Flex secure different boundaries. Exchange authenticates each client connection and limits the topics that identity can publish or subscribe to. Flex requires the publisher to sign the event-specific `data` field with JWS , which the receiving participant verifies for payload integrity and authenticity. Connection authorization does not replace payload verification. Flex exchanges are asynchronous. A load target communicates intent rather than producing a synchronous operating result. The DSX Flex Agent reports changing state through a continuing stream of full power-state snapshots, published when state changes and at periodic reporting points. Subscribers may therefore receive status updates that do not correspond to a target they published. Correlation identifiers can relate events within an interaction, but they do not make the status stream a command response. Exchange transports these events; participating systems maintain the state and make the decisions described by them. For the Flex integration described here, the Grid ISV connects through the configured gateway to an Exchange broker in the Common Services Cluster (CSC). Exchange handles routing between this shared-services boundary and factory-side systems. For more about the transport and cluster topology, see the DSX Exchange architecture and stateless asynchronous bus model . For exact topics, payloads, delivery requirements, and security fields, use the DSX Flex schema as the authoritative reference. ## How Load Targets Become Reported Power State A Load Target Set specifies one or more requested power constraints and when they apply. A target can cover selected feeds or all feeds. When the DSX Flex Agent receives a target, it updates its schedule and reports the update in a later Power State Status event. Factory-side power management uses local control logic to determine how the managed loads respond. Flex scopes targets and reported state by feed. A `feed_tag` is a deployment-defined identifier for a managed power scope. It can correspond to an electrical feed, a data hall, or another site-defined boundary, but the schema does not prescribe that mapping. The NCP and participating systems must use a consistent mapping; when `feed_tags` is omitted or empty, the target applies to all feeds. A Power State Status event is a full snapshot of the reported state for all feeds. It includes active and scheduled targets, calculated load, transition state, and target compliance. When no target is active, status reports operation against the feed's default constraint. ### Example: Observe a Scheduled Load Reduction In this example, a grid services solution publishes a scheduled load reduction. The DSX Flex Agent reports when it has updated the schedule, when the transition begins, the current state during operation, and when the transition ends. Each arrow represents an event publication routed through Exchange. ```mermaid sequenceDiagram accTitle: Example load-target and power-state sequence accDescr: A grid services solution publishes a load target. The DSX Flex Agent then publishes status snapshots as it registers the target, begins the transition, reports current state, and completes the transition. participant ISV as Grid services solution participant PM as DSX Flex Agent ISV->>PM: Load Target Set Note right of PM: Register target PM-->>ISV: Power State Status (target_set) PM-->>ISV: Power State Status (start_ramp_down) PM-->>ISV: Power State Status (periodic) PM-->>ISV: Power State Status (end_ramp_down) ``` After receiving the target, the agent publishes `target_set` to report that it updated the schedule; this value does not mean that the requested operating state was achieved. `start_ramp_down` and `end_ramp_down` mark publications at the beginning and end of the reported transition. The `in_flight` field indicates whether the agent is actively moving between power levels, while a `periodic` event reports current state without asserting a new transition. These fields do not prescribe the internal control method. Because every Power State Status event is a full snapshot, subscribers evaluate the active and scheduled targets, calculated load, transition state, and compliance together. ### Target Compliance Is Not Grid-Program Compliance Power State Status reflects the state known to factory-side power management for the loads it manages. A `compliant` value means that the calculated load is within the active Flex target; it is not a complete utility or grid-program compliance record. External metering, site operations, reconciliation, and program reporting remain outside the Flex event model. ## How the Schema Represents Breach and Enforcement The published schema defines an exception lifecycle for a factory that cannot maintain an active target. It defines the meaning of the events without requiring every deployment to implement breach detection or infrastructure enforcement. A Power Breach Alert reports the power exception. One breach can progress through `active`, optional `escalated`, and `resolved` states under the same breach identifier. The event identifies the affected target and feed, reports the power condition, and can include ordered shed hints. Shed hints are advisory. An Infrastructure Management Agent uses its own topology and operating criteria to decide how to respond. A Power Breach Enforcement event separately reports whether infrastructure actions were `applied` or `reverted` and whether the overall outcome was `success`, `partial`, or `error`. ### Example: Report and Respond to a Breach This example shows how the two event streams can overlap without representing the same state. The DSX Flex Agent publishes breach state, while the Infrastructure Management Agent reports its actions and their outcomes. Each arrow represents an event publication routed through Exchange. ```mermaid sequenceDiagram accTitle: Example breach and enforcement sequence accDescr: The DSX Flex Agent publishes a breach alert to the grid services solution and Infrastructure Management Agent. The Infrastructure Management Agent reports enforcement, the DSX Flex Agent later reports resolution, and the Infrastructure Management Agent reports that the action was reverted. participant PM as DSX Flex Agent participant ISV as Grid services solution participant INFRA as Infrastructure Management Agent PM-->>ISV: Power Breach Alert (active) PM-->>INFRA: Power Breach Alert (active) opt Breach remains unresolved PM-->>ISV: Power Breach Alert (escalated) PM-->>INFRA: Power Breach Alert (escalated) end INFRA-->>ISV: Power Breach Enforcement (applied) INFRA-->>PM: Power Breach Enforcement (applied) PM-->>ISV: Power Breach Alert (resolved) PM-->>INFRA: Power Breach Alert (resolved) INFRA-->>ISV: Power Breach Enforcement (reverted) INFRA-->>PM: Power Breach Enforcement (reverted) ``` Breach state and enforcement outcome answer different questions: the Power Breach Alert reports whether the power condition is active, escalated, or resolved, while Power Breach Enforcement reports what the Infrastructure Management Agent did in response. An enforcement outcome alone does not establish that the breach was resolved. ## Next Steps * **Plan the factory-side response.** NCPs and AI factory operators can review the [NVIDIA DSX MaxLPS overview](/dsx/maxlps/overview) and [DPS documentation](https://docs.nvidia.com/datacenter/dps/). * **Review the Flex schema.** Grid-facing integrators can use the DSX Flex schema to identify the Grid ISV operations, topics, messages, payload fields, delivery requirements, and security fields.