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 Set by adding the | > 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 | > 3.1.9 | > 4.3.4 |
Channel messagesPerMin | Adds a minimum time between processing messages so that at maximum Set by adding the Note: Setting | > 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: Set by adding the | > 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 | > 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 Default is 5, or 1 when Set by adding the | > 3.1.9 | > 5.0.4 |
AA-only enhanced ACK mode (enhanced=aa) | A variant of enhanced mode that sends an Application Accept ( 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 | > 3.1.9 | > 5.0.11 |
returnAck parameter | Allows configuring which ACK message the Agent returns when sending HL7 messages via
Can be configured at two levels:
Priority order: per-message | > 3.1.9 | > 5.0.13 |
Agent/$stats operation | Allows for remotely fetching runtime statistics from the Agent via the Agent/$stats FHIR operation. Includes connection counts, queue depths, RTT metrics, and overall agent health. See also Statistics logging for similar functionality without the need for the operation. | > 5.1.9 | > 5.1.9 |
Byte stream channel autoRespond | Allows a byte stream channel to answer a link-level handshake itself, writing a fixed byte sequence back to the socket as soon as a configured sequence is seen, without waiting on framing or the Set by adding an Byte sequences use the same For the rules an ASTM analyzer expects, see ASTM Channels. | Any | > 5.1.28 |
| Byte stream channel body filtering | Allows a byte stream channel to clean up a message body before it is sent to the
Set via query parameters in the channel endpoint url (e.g. Filtering works on bytes, not on frames, so anything printable in a device's framing still reaches the | Any | > 5.1.28 |
Byte stream channel ignoreResponse | Makes a byte stream channel one-way: the Use it for devices that never read a reply, such as an analyzer that considers a session complete once its own link-level exchange ends. Without it every message draws a write back to the device, and a Set by adding | Any | > 5.1.28 |
DICOM channel storage=dicomweb | Sends each instance a DICOM channel receives via C-STORE to the server's DICOMweb STOW-RS endpoint ( Set by adding the Requires a server with DICOMweb support; against an older server the STOW-RS request 404s and the C-STORE fails with a processing failure status. | > 5.1.27 | > 5.1.28 |
Agent durableQueue | Routes inbound HL7 messages through an on-disk SQLite queue on the Agent before they reach the Set by adding the Required for auto-retry and for logical channels. Also enables the | Any | > 5.1.22 |
| Channel auto-retry | Retries queue-to- Set agent-wide via the Requires | Any | > 5.1.25 |
| Channel logical channels | Partitions a single HL7 channel's queue into independent FIFO streams keyed on message content, so unrelated messages process concurrently instead of queueing behind each other. Order is strict within a partition and unconstrained across partitions — a feed keyed on patient ID keeps each patient's messages ordered while draining many patients in parallel. Set the key via the Requires | Any | > 5.1.29 |
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 |
| N/A | 5.1.15 | Improves the reliability of the Agent/$upgrade process. A behavior change in the underlying @medplum/hl7 library in v5 introduced a downstream ordering issue during upgrade: the new Agent version would install successfully, but the new service could stall while waiting to acquire its ports because the old service had not yet released them. In practice this required manually stopping the old service to trigger cleanup and complete the upgrade. The shutdown of the old Agent is now signaled before the new Agent waits on its channels, allowing ports to be released in the correct order and making the upgrade process significantly more stable. | 9382 |
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.