Agent Features

Each feature that the Agent supports, such as the Agent/$push operation, Agent/$status, Agent/$reload-config, etc. all require minimum versions of both Medplum Server and Medplum Agent in order to work. The matrix of feature, Medplum Server version, and Medplum Agent version looks like this:

Feature	Description	Medplum Server	Medplum Agent
Prefer: respond-async	Allows asynchronous calls to Agent/$push via the Prefer header. The header tells the server to return a 202 Accepted HTTP response and allows the client to poll for the completion of the Agent/$push operation asynchronously without keeping the client waiting for an HTTP response. Useful when a response from a target device can take several seconds or even minutes to come back.	> 3.1.5	> 3.1.5
Agent/$reload-config	Allows for dynamically reloading the config of the Agent from Medplum Server via the Agent/$reload-config FHIR operation. Useful for pushing changes to an Agent via the Agent resource without restarting the Agent service.	> 3.1.6	> 3.1.6
Agent.status	Allows using Agent.status and Agent.channel.endpoint.status to disable an Agent or a particular channel via the Agent resource. Useful for stopping traffic during Agent maintenance or for debugging of particular channels.	> 3.1.6	> 3.1.6
Agent keepAlive setting	Allows you to tell the Agent to keep TCP connections alive for both outgoing traffic (via Agent/$push) and incoming traffic (via configured Agent channels) by setting the keepAlive setting to true on the Agent resource. Useful when you want to reduce number of connections to the Agent or if a particular device configuration expects the connection not to close.	> 3.1.9	> 3.1.10
Agent/$upgrade	Allows for remotely upgrading the Agent version via the Agent/$upgrade FHIR operation.	> 3.1.9	> 3.1.10
Channel enhanced mode	Allows agent to acknowledge receipt of a message by enabling enhanced mode. In enhanced mode, the Agent will send a Commit Accept ACK response before the Bot has completed processing. Useful when receiving high volumes of messages. Set by adding the enhanced=true query parameter in the channel endpoint url (e.g. mllp://0.0.0.0:2500?enhanced=true)	> 3.1.9	> 4.1.8

| Statistics logging |

Allows for enabling periodic stats logging on the agent, which includes stats such as: internal message queue depth, number of active HL7 connections, etc.

Set by adding the logStatsFreqSecs setting to the Agent.setting array, with a valid valueInteger value, representing the number of seconds between each statistics log line.

| > 3.1.9 | > 4.3.4 | | Channel messagesPerMin |

Adds a minimum time between processing messages so that at maximum messagesPerMin messages can be processed in a minute. Useful when receiving high volumes of messages, especially when using enhanced mode.

Set by adding the messagesPerMin=<integer> query parameter in the channel endpoint url (e.g. mllp://0.0.0.0:2500?enhanced=true&messagesPerMin=60).

Note: Setting messagesPerMin tries to smooth out load, and is not just a hard cap on messages per minute. For example, messagesPerMin=60 will make it so that time between processing messages is at least 1 second.

| > 3.1.9 | > 4.3.10 | | Agent/$fetch-logs | Allows for remotely fetching the Agent logs via the Agent/$fetch-logs FHIR operation. | > 4.3.14 | > 4.3.14 | | Channel appLevelAck |

Allows configuring application-level acknowledgment behavior for HL7 messages. Controls when application-level ACKs are sent to the remote system based on the ACK code and enhanced mode status.

Valid values: AL (Always - default), ER (Error/Reject only), NE (Never), SU (Success only).

Set by adding the appLevelAck=<value> query parameter in the channel endpoint url (e.g. mllp://0.0.0.0:2500?enhanced=true&appLevelAck=ER).

| > 3.1.9 | > 5.0.4 | | Channel assignSeqNo |

Allows the Agent to automatically assign sequence numbers to incoming HL7 messages in the MSH-13 field. Useful when the sending system does not provide sequence numbers or when you need consistent sequence numbering.

Set by adding the assignSeqNo=true query parameter in the channel endpoint url (e.g. mllp://0.0.0.0:2500?assignSeqNo=true).

| > 3.1.9 | > 5.0.4 | | Agent maxClientsPerRemote |

Allows configuring the maximum number of concurrent HL7 client connections per remote host. Controls connection pooling behavior when sending messages via Agent/$push.

Default is 5, or 1 when keepAlive is enabled (unless explicitly set).

Set by adding the maxClientsPerRemote setting to the Agent.setting array, with a valid valueInteger value.

| > 3.1.9 | > 5.0.4 | | AA-only enhanced ACK mode (enhanced=aa) |

A variant of enhanced mode that sends an Application Accept (AA) immediately instead of Commit Accept (CA). Provides enhanced throughput without requiring the remote system to support or be configured for the two-step enhanced acknowledgement handshake.

Trade-off: Application-level ACKs (AA/AE/AR) are not forwarded after processing, so the remote system cannot receive asynchronous feedback about processing success or failure.

Set by adding the enhanced=aa query parameter in the channel endpoint url (e.g. mllp://0.0.0.0:2500?enhanced=aa). See AA Mode documentation for details.

| > 3.1.9 | > 5.0.11 | | returnAck parameter |

Allows configuring which ACK message the Agent returns when sending HL7 messages via Agent/$push. Valid values:

• first (default): Returns the first ACK message received (e.g., a Commit ACK CA when the remote uses enhanced mode)
• application: Waits for and returns the application-level ACK (AA, AE, or AR), skipping any commit-level ACKs

Can be configured at two levels:

• Per-device default: Set via the defaultReturnAck query parameter on the Device.url (e.g., mllp://192.168.1.100:2575?defaultReturnAck=application)
• Per-message override: Set via the returnAck parameter on Agent/$push operation or pushToAgent() method

Priority order: per-message returnAck > device defaultReturnAck > first (global default)

| > 3.1.9 | > 5.0.13 |

Major Bug Fixes

Server Version	Agent Version	Description	Related PR
3.2.10	N/A	Fixes HL7 ACK messages from bots not making it back to the sending device.	5212
< 3.2.10	4.1.9	Reverted backwards-incompatible change requiring callback field for agent:transmit:response messages.	6793
N/A	5.0.13	Reverted default returnAck behavior back to first for backwards compatibility. Previously changed to application, which broke workflows expecting the first ACK (e.g., Commit ACK CA) to be returned immediately.	8279

Compatibility Between Versions

Aside from the features and bug fixes listed above, the majority of the core functionality of the Medplum Agent is broadly compatible across all versions; notably from 3.1.5 onward. This means the Agent/$push FHIR operation functions broadly the same across versions and should be compatible on Medplum Server and Medplum Agent versions > 3.1.5.

However, it is not advised to run older versions of the Medplum Agent or Medplum Server against each other if possible, and we recommend to regularly update both Medplum Server and Medplum Agent in tandem.