dpsagent
API Reference: v1/dpsagent.proto
DPS Agent service for remote device management.
The agent connects to the DPS server via a bidirectional gRPC stream, receives device control requests, and dispatches them locally via SimpleController + Redfish plugins.
Protocol versioning: nvidia.dcpower.v1 package. Additive-only changes within v1 (new oneof fields, new RPCs). Breaking changes require v2 package.
Table of Contents
-
Services
-
Messages
Services
DPSAgentService
DPSAgentService is exposed by the DPS server on a separate gRPC port (mTLS). The agent opens Connect(), sends Handshake as the first AgentResponse, then loops receiving AgentRequests and sending AgentResponses.
Connect
rpc Connect(AgentResponse) AgentRequest
Messages
AgentError
AgentError carries structured error information for device-level errors.
| Field | Type | Description |
|---|---|---|
| code | string | Error code: “unknown_device”, “unknown_agent”, “invalid_handshake”, “queue_full” |
| message | string | none |
| device | string | Device name, if applicable. |
AgentRequest
AgentRequest is the envelope for core-to-agent messages. The oneof acts as the capability router - each message type maps to a capability declared in the agent’s Handshake. The agent dispatches based on the concrete type.
| Field | Type | Description |
|---|---|---|
| oneof msg.pong | Pong | Core agent lifecycle (not capability-specific) |
| oneof msg.remote_config | RemoteConfig | none |
| oneof msg.device_request | DeviceControllerRequest | device_control capability |
AgentResponse
AgentResponse is the envelope for agent-to-core messages. First message must be a Handshake.
| Field | Type | Description |
|---|---|---|
| oneof msg.handshake | Handshake | Core agent lifecycle |
| oneof msg.ping | Ping | none |
| oneof msg.device_response | DeviceControllerResponse | device_control capability |
Handshake
Handshake is the first message an agent sends after connecting. Core verifies cert CN matches agent_id when identity verification is enabled.
| Field | Type | Description |
|---|---|---|
| agent_id | string | Agent identifier. Must match topology AgentId assignments. |
| version | string | Agent build version (diagnostic, not used for negotiation in v1). |
| devices | repeated string | Topology device instance IDs this agent manages (e.g. “eos0205”, “b20001”). Populated from persisted RemoteConfig received from the server. Core uses this for device request routing and mismatch detection. |
| capabilities | repeated string | Enabled capabilities, e.g., [“device_control”, “metrics”]. Diagnostic in v1; request routing is based on the concrete AgentRequest type. |
Ping
Ping is sent by the agent to keep the stream alive through ingresses.
Pong
Pong is the server’s response to a Ping.
RemoteConfig
RemoteConfig is the single configuration message pushed from server to agent. Sent after handshake (bootstrap) and whenever any part of the config changes (device upsert, topology activation, settings change). The agent applies it atomically - it always has a consistent view of catalog + assignments + settings.
Follows the OpAMP RemoteConfig pattern: the server owns the truth, the agent reconciles to match.
| Field | Type | Description |
|---|---|---|
| device_catalog_data | bytes | Device type definitions (YAML-encoded). Agent rebuilds its device registry from this. SHA-256 hash allows the agent to skip rebuilds when unchanged. |
| device_catalog_hash | bytes | none |
| assigned_devices | repeated string | Topology device instance IDs assigned to this agent. Empty means no devices assigned (e.g. fresh deploy before first topology activation). |
| firmware_validation_enforce | bool | When true, firmware validation blocks topology activation and device operations. When false, validation only logs warnings. |