Cookbook: run Hermes Agent as a Microsoft Foundry autonomous agent

Listen
Share

Deploy Nous Research's open-source Hermes Agent into your own Microsoft 365 tenant, create it from Teams and give it its first tasks.

TL;DR. You install Hermes in your own tenant from our open-source repository, in one of two ways:

  • Guided install (recommended). One installer builds Hermes in your Azure subscription and submits it to your administrator for approval. Follow Steps 1 to 7.
  • Advanced route. Deploy step by step with the advanced guide in the repository, build the upload ZIP with the repository's package script, and upload it in the Microsoft 365 admin center. See "Advanced route: build and upload the package yourself".

Both routes end the same way: an administrator approves Hermes in the Microsoft 365 admin center, and employees create it from Teams.

What you'll build

By the end of this recipe, your company has its own Hermes autonomous agent: a Foundry hosted agent with its own Microsoft 365 account. You'll create an instance from Microsoft Teams, chat with it, have it send email and work with files in its own OneDrive, and schedule a recurring task that runs with nobody signed in.

Status. Autonomous agents are in preview through Microsoft's Frontier program, and this repository is a proof of concept. Use a test or pilot tenant, not production.

What you'll learn

  1. How to deploy Hermes as a Foundry hosted agent and publish it as an autonomous agent blueprint.
  2. How an administrator approves the blueprint and chooses who may create it.
  3. How an employee creates an instance in Teams, and what that instance gets.
  4. How Hermes works as its own account in Teams, email and OneDrive.
  5. How scheduled routines run without anyone's login.
  6. How to update, troubleshoot and remove the deployment.

How it fits together

Hermes runs in a single container on Foundry, alongside three small helpers. The edge receives each message from Teams, email or a routine, checks who sent it and gets a short-lived token for the agent's own account. The gateway passes the message to Hermes. Hermes reasons, then calls tools through the Microsoft 365 sidecar, which acts as the agent's own account. The AI models come from your own Foundry project.

Hermes Agent on Foundry architecture: Teams, Outlook and Foundry routines reach the Hermes container through Azure Bot Service and the Foundry agent endpoint
ComponentPortWhat it does
Edge (.NET, Microsoft 365 Agents SDK)8088Speaks Foundry's Activity and Responses protocols, checks the caller and gets the agent's token
Gateway8080Translates each request for Hermes and keeps sessions apart
Hermes Agent8642The standard Hermes image from Nous, pinned by digest
Microsoft 365 sidecar8010Mail, calendar, OneDrive, SharePoint, document, web and other tools

Only the edge port is exposed. The other components talk to each other inside the container.

Prerequisites

Microsoft 365

  • A tenant enrolled in the Frontier preview program, with the Agent 365 terms accepted by a Global Administrator.
  • At least one Microsoft 365 Copilot or Microsoft Agent 365 licence. We tested with Microsoft 365 Copilot (SKU Microsoft_365_Copilot), assigned to the administrator who enrols the tenant in Frontier.
  • A free agent seat. Frontier tenants get 25 preview seats, and each created instance uses one.
  • Microsoft Teams for the employees who will work with Hermes.

Azure

  • An active Azure subscription in the same Microsoft Entra tenant.
  • A region that supports Foundry hosted agents, with quota for the chat model.

People and roles

StepWhoRole needed
Deploy (Steps 2–3)Deployment operatorOwner on the subscription, or Contributor plus Role Based Access Control Administrator
Approve (Step 4)Tenant administratorGlobal Administrator or AI Administrator
Connect routing (Step 5)Deployment or identity administratorCan register an application and grant delegated consent (a Global Administrator can)
Create (Step 6)EmployeeMember of the hiring scope chosen in Step 4

In a test tenant, one person can hold all of these roles.

Your computer

Windows with WSL (Windows Subsystem for Linux), macOS, or Ubuntu or Debian Linux, with git, curl and Python 3. The installer is a Bash script, so on Windows you run it in a WSL terminal, such as Ubuntu from the Microsoft Store. It installs the Azure CLI and the Azure Developer CLI if they are missing.

Step 1: get the code

git clone https://github.com/NousResearch/hermes-foundry
cd hermes-foundry

The repository holds the edge, gateway and sidecar, the container build and the installer. Hermes itself comes from Nous's published Docker image, pinned by digest in the Dockerfile, so there is no separate Hermes download.

Step 2: check before you create anything

Two read-only modes let you check your tenant first. Neither creates Azure resources.

./deploy.sh --validate   # sign in and run read-only prerequisite checks
./deploy.sh --preview    # list the Azure resources the installer would create

Expected result: validation passes, and the preview lists a Foundry account and project with a model deployment, a container registry, an Azure Bot with a Teams channel, a managed identity and the role assignments they need.

Step 3: deploy

./deploy.sh

The installer guides you through each stage and saves its progress as it goes. It:

  1. signs you in and lets you choose the tenant and subscription;
  2. registers the Azure resource providers and deploys the infrastructure and the model;
  3. builds the Hermes image in your own container registry;
  4. creates the hosted agent and publishes it as an autonomous agent blueprint, privately, inside your tenant;
  5. declares the Microsoft Graph permissions the agent will ask for; and
  6. installs the automation that lets each new agent schedule routines (see Step 7c).

Then it pauses and waits for an administrator to approve the blueprint. Publishing here means making Hermes available inside your own tenant. Nothing goes to Azure Marketplace or the public Teams store.

Expected result: the installer waits at the approval prompt, and a request named Hermes Agent on Foundry with the status Pending activate appears in the Microsoft 365 admin center under Agents → All agents → Requests. It usually appears within five minutes, though it can take a few hours.

If the installer stops, fix the cause and resume with ./deploy.sh --continue. Don't delete its saved progress or start a second installation.

Advanced route: build and upload the package yourself

Some organisations want to control every step and add agents by uploading a package in the Microsoft 365 admin center. Instead of running the installer in Step 3, follow ADVANCED_TENANT_DEPLOYMENT.md in the repository. It walks through the same deployment one step at a time: the Foundry project, the models, the container registry, the Hermes image, the blueprint and its Microsoft Graph permissions.

Then build the upload package from the repository. You need a 192×192 colour icon and a 32×32 transparent white-outline icon, both PNG:

python3 scripts/package-agent365-blueprint.py \
  --blueprint-id "<your blueprint ID>" \
  --display-name "Hermes Agent on Foundry" \
  --version 1.0.0 \
  --color-icon color.png \
  --outline-icon outline.png

The script writes deployment-output/hermes-agent-on-foundry/Hermes-Agent-on-Foundry.zip. It holds only the agent's manifests, the two icons and your blueprint ID, with no secrets or tokens. The package belongs to your tenant's blueprint, so it can't be reused in another tenant.

In Step 4, select Upload custom agent, upload the ZIP, then approve it as usual. In Step 5, set the Bot Based routing by hand, and continue from Step 6.

Step 4: approve the blueprint

A Global Administrator or AI Administrator approves the blueprint once. After that, anyone in the hiring scope can create an instance without further approval.

  1. Open the Microsoft 365 admin center at admin.cloud.microsoft and go to Agents → All agents → Requests.
  2. Select Hermes Agent on Foundry.
  3. On Publish to users, confirm Teams as a host product. Under Activate, choose who can create instances: Specific users or groups for a pilot, All users, or None.
  4. On Apply template, choose a policy template.
  5. On Accept permissions, compare the requested permissions with the table below, then select Grant admin consent.
  6. On Review and finish, select Publish.
PermissionWhat Hermes uses it for
Chat.ReadWriteReading and replying in its Teams chats
Mail.ReadWriteReading and organising its own mailbox
Mail.SendSending mail from its own mailbox
Calendars.ReadWriteManaging its own calendar
Files.ReadWrite.AllWorking with files its account can reach
Sites.ReadWrite.AllWorking with SharePoint sites shared with it
User.Read.AllLooking up the people it works with
User.ReadBasic.AllShowing basic profiles of people

All eight are delegated permissions for the agent's own account. They set what the account may ask for; they don't share anyone's files or mail with it. Access still follows normal Microsoft 365 sharing, so the agent sees a folder only after someone shares it.

Expected result: Hermes Agent on Foundry shows as Available on the Registry tab.

Step 5: finish the setup

Back in the terminal, press Enter, or run ./deploy.sh --continue later. The installer now:

  • connects the blueprint to its Azure Bot in Bot Based mode, after you complete a browser sign-in, and reads the setting back to confirm it saved; and
  • checks that the Hermes version receives all traffic, and asks before enabling the hosted endpoint if it is disabled.

An enabled endpoint still scales to zero when nobody is using it, so you pay for compute only while sessions are active.

If your tenant blocks the automatic routing step, set it by hand. Open https://dev.teams.microsoft.com/tools/agent-blueprint/<BLUEPRINT_ID>/configuration, using the blueprint ID the installer printed. Set Agent Type to Bot Based and Bot ID to the same blueprint ID, save, and reload the page to check the change stuck.

Expected result: the installer reports that routing is verified and the endpoint is enabled, then asks about your first instance.

Step 6: create your first Hermes

  1. In Microsoft Teams, go to Apps → Agents for your team.
  2. Select Hermes Agent on Foundry, then Create instance.
  3. Enter a name (up to 32 characters), an alias and a domain, confirm the manager, and select Create.

Administrators can also create instances from Agents → All agents → Hermes Agent on Foundry → Create instance, which lets IT choose the name and the owner.

Each instance uses one agent seat and gets its own agent identity and agent user account. Microsoft provisions it in the background, and the mailbox and OneDrive can take a little longer than the account itself, so give them a few minutes before you test them.

Expected result: the new agent starts a Teams chat with you and appears in the org chart with you as its manager. Give the installer the instance's email address, and it confirms that the instance belongs to this blueprint.

Step 7: put it to work

Try these prompts in your Teams chat with the agent, in order. The first ones only read; the later ones change things.

7a. Check who it is

What's your name, and what's your Microsoft 365 email address?

Expected result: it gives its own address, not yours.

List up to three files in your own OneDrive. Don't change anything.

Expected result: a short list, or a plain statement that the folder is empty. A 404 error on a new instance means the OneDrive isn't ready yet; wait a few minutes and ask again.

7b. Write, share and send

Create a file called hello.txt in your OneDrive containing 'Hello from Hermes', then read it back to me.

Share hello.txt with me and email me the link.

Expected result: the email comes from the agent's own address, and the file is shared from the agent's own OneDrive. Now email the agent from Outlook: it replies from the same address, and if the same email arrives twice, it answers once.

7c. Schedule work for when nobody is around

Every weekday at 8:30 my time, summarise the new email in your inbox and send me the summary.

Only the agent's owner can create routines. Hermes sets up a Foundry routine with a signed record of its owner, its agent and its exact task, so nobody can change the task later. When the routine fires, the edge gets a fresh token for the agent's account through Microsoft Identity Web's agent user flow. No one's login is stored anywhere.

List your routines.

Delete the routine you just created.

Expected result: the routine appears in the list and is gone after you delete it. A brand-new instance can take 5 to 10 minutes before it can create routines, while the automation from Step 3 grants it access to the Foundry project.

7d. Work with a colleague

An agent with its own account hears from more than one person, so it follows three rules. Its owner can use all of its tools. Colleagues can ask it questions, but it touches its files, mail or calendar for them only with the owner's permission. People outside the company get no reply.

Let Alex read the files in the Invoices folder.

Expected result: Hermes shows you exactly what will change: who gets access, to what, and until when. Nothing happens until you reply "Yes". These checks run in code on every tool call, outside the AI model, so a clever prompt can't talk its way past them.

Ship a new version

Every Foundry agent version is immutable. To ship a change, build a new image, create a new agent version from it and move traffic to that version once you have checked it. To roll back, move traffic back to the previous version. The calls are in Microsoft's guide to managing hosted agents.

Conversations stay on the version they started with. To see new code, start a new conversation, or let old sessions time out (after 15 minutes of quiet by default).

Troubleshooting

What you seeLikely causeWhat to do
The request doesn't appear under RequestsPublication is still propagatingWait. It usually appears within five minutes, occasionally hours. Don't publish a second copy.
Create instance is missing in TeamsThe tenant isn't in Frontier, the blueprint isn't activated, or you're outside the hiring scopeCheck Frontier enrolment, activation and the hiring scope
Hiring fails with a licensing errorNo free agent seatsFree a seat or ask Microsoft for more
The agent never replies in TeamsThe blueprint isn't set to Bot Based, or the endpoint is disabledRun ./deploy.sh --continue, or repeat Step 5 by hand
Email to the agent gets no replyThe endpoint uses BotServiceRbac authorizationUse BotServiceTenant, as the installer does
OneDrive or mail returns 404 on a new instanceMicrosoft 365 is still provisioningWait a few minutes and retry before changing permissions
OneDrive or mail returns 404 after a releasePublishing reset the blueprint's Graph permissionsDeclare them again with scripts/configure-blueprint-graph-permissions.sh
Creating a routine fails with 403The new agent doesn't have the Foundry User role yetWait 5 to 10 minutes, and check that the routine automation is installed
New code doesn't seem to runThe conversation is still on the old versionStart a new conversation, or stop the old sessions

Clean up

  • Remove created instances, then the blueprint, in the Microsoft 365 admin center under Agents → All agents. Deleting Azure resources doesn't remove the instances people created.
  • Remove the routine automation with scripts/remove-agent-rbac-automation.sh, then delete the Azure resources with azd down from the repository folder.
  • Each agent's mailbox and OneDrive are Microsoft 365 data. Review and remove them separately, in Microsoft Entra and the Microsoft 365 admin center.

Next steps

All articles

The Internet's Own AI

© 2026, Nous Research, Inc.

Terms|Privacy

MIT License · 2026