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.

Services

AgentManagementService

AgentManagementService exposes read-only agent discovery to operators.

ListAgents

rpc ListAgents(ListAgentsRequest) returns ListAgentsResponse

ListAgents returns the current in-memory agent inventory.

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) returns AgentRequest

Messages

AgentAlerts

AgentAlerts is the batch payload for agent-originated alert state updates.

Field	Type	Description
alerts	repeated Alert	none

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.

AgentInfo

AgentInfo describes topology configuration and live sessions for one agent ID.

Field	Type	Description
agent_id	string	Agent identifier from topology assignments or live handshakes.
configured	bool	Configured is true when the active topology assigns devices to the agent.
connected	bool	Connected is true when the agent has at least one active stream.
assigned_devices	repeated string	Device instance IDs assigned to the agent by the active topology.
sessions	repeated AgentSessionInfo	Active connections for this agent ID.

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
traceparent	string	W3C Trace Context parent for the message carried by this envelope.
tracestate	string	W3C vendor-specific trace state associated with traceparent.
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
oneof msg.alerts	AgentAlerts	agent alert stream

AgentSessionInfo

AgentSessionInfo contains metadata reported by one active agent connection.

Field	Type	Description
version	string	Agent build version reported in the handshake.
capabilities	repeated string	Capabilities reported in the handshake.
reported_devices	repeated string	Device instance IDs reported in the handshake.

Alert

Alert is one typed alert inside an AgentAlerts payload.

Field	Type	Description
oneof payload.node_compliance	NodeComplianceAlert	none

CPUComplianceResource

Field	Type	Description
index	uint32	none

ComplianceResource

ComplianceResource identifies the node scope that the compliance status applies to.

Field	Type	Description
oneof scope.node	NodeComplianceResource	none
oneof scope.gpu	GPUComplianceResource	none
oneof scope.cpu	CPUComplianceResource	none
oneof scope.memory	MemoryComplianceResource	none

GPUComplianceResource

Field	Type	Description
index	uint32	none

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.

ListAgentsRequest

ListAgentsRequest requests the current configured and connected agent inventory.

ListAgentsResponse

ListAgentsResponse contains one record per configured or connected agent ID.

Field	Type	Description
agents	repeated AgentInfo	Agents is ordered lexically by agent_id.

MemoryComplianceResource

Field	Type	Description
index	uint32	none

NodeComplianceAlert

NodeComplianceAlert reports whether observed node or component power is compliant with the desired DPS set point.

Field	Type	Description
device	string	none
resource	ComplianceResource	none
compliance_status	NodeComplianceAlert.ComplianceStatus	none
desired_set_point_watts	double	Desired DPS target in watts.
current_reading_watts	double	Agent-observed power reading in watts.
observed_at	google.protobuf.Timestamp	Agent-observed telemetry timestamp. Unset means unavailable.
ends_at	google.protobuf.Timestamp	Alert expiration time. Unset means unavailable.

NodeComplianceResource

Ping

Ping is sent by the agent to keep the stream alive through ingresses.

Pong

Pong is the server’s response to a Ping.

PushDeviceConfig

PushDeviceConfig carries per-device-instance agent configuration.

Field	Type	Description
instance_id	string	Topology device instance ID (for example, “eos0205”).
telemetry_id	string	Telemetry stream identifier (for example, Zapp sensor UUID).
device_model_json	bytes	Device model JSON from topology, including Redfish endpoint and credential reference.

RemoteConfig

RemoteConfig is the device-management state pushed from server to agent. Sent after handshake (bootstrap) and whenever topology or device assignments change. The agent applies it atomically - it always has a consistent view of catalog + assignments + firmware validation policy.

Follows the OpAMP RemoteConfig pattern for topology and routing state: the server owns these inputs, and 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.
device_configs	repeated PushDeviceConfig	Per-device instance configuration for this agent (telemetry and future fields).

Scalar Value Types

.proto Type	Notes	C++ Type	Java Type	Python Type
double		double	double	float
float		float	float	float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long
uint32	Uses variable-length encoding.	uint32	int	int/long
uint64	Uses variable-length encoding.	uint64	long	int/long
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long
sfixed32	Always four bytes.	int32	int	int
sfixed64	Always eight bytes.	int64	long	int/long
bool		bool	boolean	boolean
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str