Back to Blog

What you need to know about the Microsoft Hybrid Agent GA

Image of Michel de Rooij
Michel de Rooij

In February, Microsoft released the initial public preview version of the Hybrid Agent, about which was written here. The purpose of the Hybrid Agent, also branded as the “Exchange Modern Hybrid Topology”, is to simplify the process of setting up and deploying Microsoft Exchange Hybrid for Exchange 2010 and later deployments, where full “classic” Exchange Hybrid is not an option.

It can also address scenarios where deploying the Hybrid Agent would satisfy organizational migration requirements.  For example, moving mailboxes between Exchange Online and Exchange on-premises while providing rich-coexistence features, but without requiring (re)configuration of the publishing of Exchange services. Another functionality the Hybrid Agent doesn’t contain is mail transport. Future builds of the Hybrid Agent might also enable cross-premises functionality such as Send As delegations, as demonstrated at Microsoft Ignite last year.

This week, the Hybrid Agent Public reached General Availability status. In this article, we will discuss the major changes in the agent since the initial Preview release.


Regarding availability of Exchange Hybrid deployments leveraging the Hybrid Agent, the updated Hybrid Agent now supports installing and running multiple instances of the Hybrid Agent. This is similar to what running multiple Pass-Through Authentication (PTA) agents does for authentication.

To install additional agents, you have two options:

  1. Installation through opening the Hybrid Configuration Wizard (HCW) on the server where you would like to deploy another agent. In the Hybrid Agents overview screen choose ‘Install an additional agent’. Note that it is not required to deploy the Hybrid Agent on Exchange servers, as any member server from Windows Server 2012 R2 or up with internet access should suffice.
  2. Manual installation by downloading the Hybrid Agent installer from, followed by executing msiexec /I MSHybridService.msi. When asked, provide the credential of a Global Admin in your tenant.

Note that when inspecting the Hybrid Configuration Wizard logs, the Hybrid Agent is referred to as Hybrid Connector, as it’s an Azure AD Application Proxy Connector. The installation logs for the Hybrid Agent are logged separately in the same folder where HCW stores its logs (Use F12 in the HCW to open the shortcut menu, and select Open Logging Folder), in a file named <timestamp>.hybridconnector.log


The Hybrid Agent comes with a PowerShell module, which depends on the Azure module. Use Install-Module Azure to install the Azure module from the PowerShell Gallery. After this, you can import the Hybrid Agent module using:

Import-Module Azure
Import-Module ‘C:\Program Files\Microsoft Hybrid Service\HybridManagement.psm1’

The status of the currently registered Hybrid Agents can be retrieved by running

$Credential= Get-Credential
Get-HybridAgent -Credential $Credential


The Hybrid Agent module provides the following interesting, yet undocumented cmdlets:


Get authentication head for specified token, e.g. GetAuthHeader -Token $token -Credentials $cred


Get token for specified credential, e.g. $token= GetAuthToken -Credentials $cred


Shows status of registered Hybrid Agents


Used to manage the registered Hybrid Agent application in the tenant.


Test Hybrid Agent connectivity.


Test Proxy Settings


Test TLS Client configuration


The Hybrid Agent endpoint can be configured to connect to a load balanced endpoint instead of default Client Access server specific endpoint. In order to accomplish this, we first need to determine the AppId of the Hybrid Agent. After connecting to Exchange Online Management shell, run:

(Get-MigrationEndpoint 'Hybrid Migration Endpoint - EWS (Default Web Site)').RemoteServer.Split('.')[0]


Then, on a server containing the Hybrid Agent PowerShell module, take this/these Guid(s), and run the following cmdlet, specifying the desired load balanced name space as targetUri (internalUrl) in combination with each AppId:

Update-HybridApplication -AppId <AppId> -targetUri


The module is still an early version, as not all parameters and properties have been aligned yet, and not all cmdlets follow the verb-noun PowerShell directive. But this is a minor inconvenience, as they allow you to script the deployment and configuration of the Hybrid Agent.

Final Note

Even with the Hybrid Agent reaching GA status, you might want to get acquainted with the Hybrid Agent in a lab environment first, before implementing it in production.

Meanwhile, the Exchange team is still looking for feedback and continues to work on updates in functionality. Note that when required, you can always reconfigure Exchange hybrid to use Exchange Classic Hybrid Topology mode. Unfortunately, the other way around is not possible.

Monitor Your Hybrid Environment with ENow

Monitoring a Hybrid deployment is complex. Administrators that use ENow are confident their entire system is functioning correctly as they begin transitioning into using Office 365. See why top trusted brands such as Experian, Facebook, VMware, and Barclay's use ENow's personalized monitoring dashboard and reporting to self-generate the most crucial, current, and accurate data.

Learn more

Office 365 message encryption

New Features in Office 365 Message Encryption

Image of Nathan O'Bryan MCSM
Nathan O'Bryan MCSM

I have long been interested in encryption. I started off my IT career in the United States Marine...

Read more
businessman touching virtual cloud and padlock

Accessing Exchange Online Objects (without legacy auth) | ENow

Image of Ingo Gegenwarth
Ingo Gegenwarth

Microsoft postponed deprecation of Basic Authentication in Exchange Online for existing tenants....

Read more