Microsoft Teams#

How to let your team ask the OSPREY agent questions from a Microsoft Teams channel or chat, and get answers, plots and files back in the same conversation.

Before you start
  • A project whose build profile has a dispatch: block — see Event Dispatch.

  • Docker or Podman, for the container path.

  • An Azure subscription in which you can create an app registration, a bot, a Service Bus namespace and a Function App.

  • Permission to add an app to your Teams tenant, or a Teams administrator who will do it for you.

  • The Azure CLI (az) and the Azure Functions Core Tools (func), signed in to that subscription.

Overview#

The bridge turns a Teams conversation into a way of talking to the agent. Someone mentions the bot in a channel or writes to it in a chat. The question is handed to the event dispatch pipeline, and the answer is posted back in the same conversation.

Teams differs from the other two platforms in one way that shapes the setup. A Teams bot receives messages only as an HTTPS POST to an address reachable from the public internet — there is nothing for the bridge to read from. So the deployment has two pieces rather than one:

  • A relay: a small Azure Function that is the bot’s public address. It checks that each incoming message really came from Microsoft, and puts it on a Service Bus queue. It is four files that ship with Osprey; you publish them, you do not write them.

  • The bridge itself, running in your stack beside the dispatcher. It pulls that queue, and posts replies back through the bot connector.

The bridge is therefore still a reader of a queue, not a server. It opens no port, and nothing has to be able to reach it. That is what lets it run on a control-room network with no inbound path from the internet. The relay is the only public surface, and the only thing it can do is put a validated message on your queue.

Like every bridge, it remembers each question and conversation. What is particular to Teams is that there is no reading position to keep. A message the bridge has not finished with stays on the queue. So anything sent while the bridge was down is waiting when it comes back.

Each question gets an acknowledgement as soon as it is picked up, and the answer when the run finishes, each as its own message. Any plots and files follow as further messages. Nothing is edited after it is posted. In a channel all of them are threaded under the question itself. A one-to-one or group chat has no threads in Teams. There the acknowledgement and the answer open with a quote of the question’s first line, so it is clear which message is being answered.

Note

If your tenant is GCC High, the differences are two configuration values, not a different deployment. Set TEAMS_CLOUD=gcchigh on the bridge and the same setting on the relay. The sovereign-cloud login host, token scope, signing-key metadata address and issuer are all selected from that one value. Point the CLI at the right cloud first with az cloud set --name AzureUSGovernment, and read azurewebsites.us wherever the commands below say azurewebsites.net. Everything else on this page is the same.

Enable It in a Profile#

Add a teams_bridge: block to your build profile. It holds two settings:

  • Which dispatcher trigger the bridge fires. That trigger decides what the agent is allowed to do with a chat question.

  • Whether the agent may @mention people.

The block is only meaningful next to a dispatch: block:

profile.yml#
teams_bridge:
  trigger: teams-question        # default; must exist in your triggers file
  mentions: true            # default; false posts @mentions as plain text

dispatch:
  triggers: my_triggers.yml      # the file that trigger must be declared in
  worker_count: 1

env:
  required:
    - TEAMS_APP_ID
    - TEAMS_APP_SECRET
    - TEAMS_TENANT_ID
    - TEAMS_SERVICEBUS_CONNECTION_STRING
    - TEAMS_SERVICEBUS_QUEUE

Note

The bridge and the dispatch pair must sit on the same network. Workers go on the host’s network whenever the agent has to reach a control system or a co-deployed bridge at a loopback address (Network attachment: bridge or host). This bridge then has to move with them: add services.teams_bridge.network: host to your profile’s config: block. osprey build refuses a split pair and names the key to change.

The bot’s credentials and the queue it reads are not profile settings. Which tenant this deployment authenticates in and which queue it drains differ per deployment. The client secret and the connection string are also secrets that must never be baked into a build. Listing them under env.required documents them in .env.example. Fill the values into the profile’s .env, which is where a secret survives a rebuild. The build derives the project’s .env from it (created mode 0600, readable only by you).

Two mistakes are caught at build time rather than at runtime: declaring the bridge without a dispatch: block, and naming a trigger your triggers file does not declare. Both fail the build with a message naming the problem.

Runtime settings#

These are the ones you create and set yourself.

Variable

Meaning

TEAMS_APP_ID

The bot’s app-registration (client) id, a GUID. It is also what an @mention is matched against, so a wrong value makes the bridge ignore every channel message instead of failing loudly — worth double-checking. The relay needs the same value.

TEAMS_APP_SECRET

The client secret of that app registration, which the bridge exchanges for a token to post with. A secret: it belongs in the .env and nowhere else.

TEAMS_TENANT_ID

The directory (tenant) id the app registration lives in. Single-tenant bots have no default for this.

TEAMS_SERVICEBUS_CONNECTION_STRING

Connection string for the queue the relay writes to, taken from the Listen-only policy (bridge-listen below). The bridge never sends to the queue, so it never holds a key that could.

TEAMS_SERVICEBUS_QUEUE

The name of that queue. Read the warning below before pointing a second deployment at it.

TEAMS_CLOUD

Optional. Leave it unset, or set it to commercial, for an ordinary commercial tenant. Set it to gcchigh for a GCC High tenant. Those are the only two values; any other one stops the bridge at startup rather than failing later as an unexplained authentication error.

TEAMS_FILES_DRIVE_ID

Optional. The drive id of the one document library the bot shares files from (see step 9). Unset, files the bridge cannot post inline are named in a closing note rather than shared.

TEAMS_FILES_FOLDER

Optional. A folder inside that library, such as osprey/answers. Unset means the library root. Each run’s files go into their own folder below it.

The bridge refuses to start if any of the required five is missing, naming all the missing variables at once.

Warning

One bridge per queue. Deploy exactly one bridge against a given queue. Service Bus hands each message to only one of a queue’s readers. So a second deployment pointed at the same queue does not get its own copy of every message. It silently splits them: each bridge answers only the messages it happened to receive. The other questions look to your team like they were ignored, and nothing anywhere logs an error. The second deployment can be a staging stack, a container someone forgot to remove, or another facility reusing the name. Give every deployment its own queue, and its own relay writing to it.

Settings that are filled in for you, or safe to leave alone

Variable

Meaning

DISPATCH_TRIGGER

The trigger to fire. Comes from the profile block.

TEAMS_MENTIONS

Whether @mentions are on. Comes from the profile block.

EVENT_DISPATCHER_TOKEN, DISPATCH_WORKER_TOKEN

The two shared secrets the bridge needs to reach the dispatcher and the worker, generated for you when unset — see Authentication.

DISPATCHER_URL, WORKER_URL

Where the dispatcher and worker are — the bridge collects answers and files from the worker directly. Filled in for you when they run in the same stack; when they run elsewhere you must set them, and the bridge refuses to start without them.

DISPATCH_TIMEOUT_SEC

How long the worker may spend on one run. Comes from your project configuration, so raising it raises it for both halves at once.

POLL_BUDGET

How long the bridge waits for an answer before giving up on it. Defaults to 30 seconds more than the worker’s own limit, and may never be less than that limit — the bridge refuses to start if it is.

POLL_INTERVAL

Seconds between checks on an answer in progress (default 2).

DRAIN_INTERVAL

Seconds between sweeps of the queue of questions that could not be handed off yet (default 60).

RETRY_MIN_AGE

How long a failed hand-off is held before it is retried, so a brief outage has time to clear (default 20 minutes).

RETRY_GIVE_UP

Age at which a question that still cannot be handed off is abandoned (default 48 hours).

RETRY_LIFETIME_CAP

Hard ceiling on how long anything may sit in that queue, whatever its state (default 7 days).

BRIDGE_TRUST_ENV

Set to 1 only if this host’s outbound calls must go through your site’s web proxy. Off by default, so a proxy inherited from a shell or a CI runner cannot quietly place itself in front of Microsoft.

HISTORY_ANSWER_LIMIT

Longest earlier answer, in characters, sent back in full with a follow-up (default 3000). A longer one is sent as its opening, and the agent reads the rest only if it needs it. 0 always sends every answer in full.

GITLAB_URL, GITLAB_PROJECT, GITLAB_ISSUES_TOKEN

Optional alert host. With GITLAB_URL and GITLAB_ISSUES_TOKEN set, the bridge holds queued questions while GITLAB_PROJECT has an open osprey-alert issue, or while GitLab cannot be reached. Leave them unset to skip the check.

APP_VERSION_DISPLAY

A release label shown with each acknowledgement, so a conversation shows which version answered: the acknowledgement reads On it — working on this now.  (OSPREY 2026.9.0) with this label in the parenthesis. When it is unset the bridge uses the version of the Osprey package it is running, and drops the parenthesis only if even that is unavailable.

DEDUP_PATH

Where the bridge keeps the questions it has answered. It defaults to a file under /data, its own volume; change it only if you deliberately relocate that state.

TZ

Timezone, taken from your project configuration so timestamps match the rest of the stack.

Bring It Up#

The commands below use one set of names throughout: resource group osprey-teams, namespace osprey-teams-bus, queue osprey-questions and Function App osprey-teams-relay. You can paste them in order and change the names once, at the top. Namespace, Function App and storage-account names are part of a public address, so they must be unique across Azure; pick something with your facility in it if these are taken.

1. Create a resource group to hold everything.

az login
az group create --name osprey-teams --location westus2

On a GCC High tenant, run az cloud set --name AzureUSGovernment before az login, and use one of that cloud’s regions (for example usgovvirginia) throughout.

2. Give this deployment its own queue. One namespace, and one queue that nothing else reads — see the warning above for what a shared queue does.

az servicebus namespace create \
  --resource-group osprey-teams --name osprey-teams-bus --sku Standard
az servicebus queue create \
  --resource-group osprey-teams --namespace-name osprey-teams-bus \
  --name osprey-questions

3. Create one key for writing and one for reading. The relay may only send, the bridge may only listen; neither half holds the other’s rights.

az servicebus queue authorization-rule create \
  --resource-group osprey-teams --namespace-name osprey-teams-bus \
  --queue-name osprey-questions --name relay-send --rights Send
az servicebus queue authorization-rule create \
  --resource-group osprey-teams --namespace-name osprey-teams-bus \
  --queue-name osprey-questions --name bridge-listen --rights Listen

Then read the two connection strings out. Keep them somewhere safe for steps 5 and 8; they are credentials.

az servicebus queue authorization-rule keys list \
  --resource-group osprey-teams --namespace-name osprey-teams-bus \
  --queue-name osprey-questions --name relay-send \
  --query primaryConnectionString --output tsv
az servicebus queue authorization-rule keys list \
  --resource-group osprey-teams --namespace-name osprey-teams-bus \
  --queue-name osprey-questions --name bridge-listen \
  --query primaryConnectionString --output tsv

4. Register the bot and the identity it speaks as. The registration’s name is internal. The name your team sees replying is the one you give the Teams app in step 7. Single-tenant keeps the bot usable only inside your own directory.

az ad app create --display-name "OSPREY agent" --sign-in-audience AzureADMyOrg \
  --query appId --output tsv
az account show --query tenantId --output tsv

Note both values — they are TEAMS_APP_ID and TEAMS_TENANT_ID. Then create a client secret, which is shown once and never again:

az ad app credential reset --id <app id> --display-name teams-bridge \
  --query password --output tsv

Now create the bot resource. Its messaging endpoint is the relay’s address. You can write it down before the relay exists. It is the Function App name you are going to use in step 5:

az bot create \
  --resource-group osprey-teams --name osprey-agent-bot --sku F0 \
  --app-type SingleTenant --appid <app id> --tenant-id <tenant id> \
  --endpoint https://osprey-teams-relay.azurewebsites.net/api/messages
az bot msteams create --resource-group osprey-teams --name osprey-agent-bot

The second command turns on the Teams channel; without it the bot exists but Teams will not talk to it.

5. Create the relay’s Function App. Use Flex Consumption with one always-ready instance. Teams expects an answer from the endpoint within 15 seconds. An app that has scaled to nothing spends most of that budget starting up.

az storage account create \
  --resource-group osprey-teams --name ospreyteamsrelay \
  --location westus2 --sku Standard_LRS
az functionapp create \
  --resource-group osprey-teams --name osprey-teams-relay \
  --storage-account ospreyteamsrelay \
  --flexconsumption-location westus2 \
  --runtime python --runtime-version 3.11
az functionapp scale config always-ready set \
  --resource-group osprey-teams --name osprey-teams-relay \
  --settings http=1

Then give it its settings. These are the relay’s own names and are not the bridge’s. In particular, the connection string here is the relay-send one. The setting is called SERVICEBUS_CONNECTION because the Functions host reads it directly, so the send key never passes through the relay’s own code.

az functionapp config appsettings set \
  --resource-group osprey-teams --name osprey-teams-relay \
  --settings TEAMS_APP_ID=<app id> \
             TEAMS_SERVICEBUS_QUEUE=osprey-questions \
             SERVICEBUS_CONNECTION="<the relay-send connection string>"

On a GCC High tenant add TEAMS_CLOUD=gcchigh to that same command. Leave it unset anywhere else.

6. Publish the relay. osprey build copies it into your deployment repository, under build/services/teams_bridge/relay/. Publish from that directory:

cd build/services/teams_bridge/relay
func azure functionapp publish osprey-teams-relay --python

The endpoint is then live at https://osprey-teams-relay.azurewebsites.net/api/messages — the address you gave the bot in step 4. It accepts anonymous requests on purpose. The proof that a message is genuine is the signed token Microsoft sends with it. The relay checks that token against the bot’s app id before anything reaches your queue. A request that fails that check is refused and never enqueued.

7. Install the app in Teams. Build a Teams app package — a manifest.json plus its two icons, zipped — whose bots entry carries the app id from step 4:

{
  "bots": [
    {
      "botId": "<app id>",
      "scopes": ["team", "groupChat", "personal"],
      "supportsFiles": false,
      "isNotificationOnly": false
    }
  ]
}

Upload it in the Teams admin center, or in Teams itself if your tenant allows custom apps, then add the app to each team or chat it should serve. It only sees conversations it has been added to.

8. Fill in the environment file. Set the values in the profile’s .env (the build derives the project’s .env from it):

TEAMS_APP_ID=00000000-0000-0000-0000-000000000000
TEAMS_APP_SECRET=the-secret-from-step-4
TEAMS_TENANT_ID=11111111-1111-1111-1111-111111111111
TEAMS_SERVICEBUS_CONNECTION_STRING=<the bridge-listen connection string>
TEAMS_SERVICEBUS_QUEUE=osprey-questions
# TEAMS_CLOUD=gcchigh                  # only on a GCC High tenant

9. Optional: give the bot one file library. Without one, the bridge posts plots inline and names every other file it could not deliver. With one, it uploads those files there and shares each with the people in the conversation. Create or pick a SharePoint document library that nobody else reads. A shared file keeps the library’s own permissions as well as the per-conversation share. So a library with broad membership shares wider than the conversation.

First look up the site and the library ids:

SITE_ID=$(az rest --method get \
  --url "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/osprey-files" \
  --query id -o tsv)
LIST_ID=$(az rest --method get \
  --url "https://graph.microsoft.com/v1.0/sites/$SITE_ID/lists" \
  --query "value[?displayName=='OSPREY files'].id" -o tsv)

In the app registration from step 4, add the Microsoft Graph application permission Lists.SelectedOperations.Selected and grant admin consent. That permission reaches no list until one is granted to the app. An administrator who holds Sites.FullControl.All then grants the app the owner role on this one library — owner is what lets it share a file; write is not enough:

POST https://graph.microsoft.com/v1.0/sites/{site-id}/lists/{list-id}/permissions
Content-Type: application/json

{
  "roles": ["owner"],
  "grantedTo": {"application": {"id": "<TEAMS_APP_ID>"}}
}

Read the library’s drive id:

az rest --method get \
  --url "https://graph.microsoft.com/v1.0/sites/$SITE_ID/lists/$LIST_ID/drive" \
  --query id -o tsv

Then add the two variables to the profile’s .env, with the drive id the command printed:

.env#
TEAMS_FILES_DRIVE_ID=b!the-drive-id
TEAMS_FILES_FOLDER=osprey/answers

On GCC High the Graph host follows TEAMS_CLOUD (graph.microsoft.us). Confirm your cloud offers the Selected permissions before you set a library, and leave it unset if it does not.

10. Bring the stack up. The bridge is registered in deployed_services, so it starts with everything else:

osprey up        # add --dev to bake in a local osprey checkout

Then mention the bot in a channel it has been added to and ask it something. If nothing happens, work outwards from the bridge: a missing credential stops it at startup with the missing variable named. A wrong app id is the quieter failure. The bridge runs happily and ignores every channel message, because nothing it sees looks like a mention of itself. If the bridge looks idle, check the Function App’s logs. A message refused there never reaches the queue. A relay whose settings name the wrong queue writes where nobody is reading.

Important

The bridge keeps what it remembers — which questions it has answered and the recent conversation — in a named volume mounted at /data. Do not remove that volume. Without it, a restart in the middle of a question can answer it twice or drop it, and conversations lose their thread of context.

Who Can Ask, and What Is Shared#

Who may reach the agent, and what the trigger lets it do, is the same for every bridge — see Who Can Ask. What is particular to Microsoft Teams:

The conversations are the ones the app was added to. Teams, not Osprey, decides who is in those teams and chats. So add the app as deliberately as you would choose who gets an account.

In a channel or a group chat, only a real @mention of the bot is answered. The bridge matches the mention Teams itself records, not the message text. So writing the bot’s name in passing does not trigger it. A one-to-one chat has nobody else to address, so every message there is a question.

Other people’s names survive the question. When a question mentions a colleague as well as the bot, the bot’s own mention is removed as addressing. Every other mention becomes that person’s display name, so the agent sees who was named.

Who is in the conversation, and @mentions. Each question reaches the agent with who asked it and who is in the conversation; for a channel that is the channel’s members. The bridge lists them with the bot’s own sign-in, so there is no extra permission to grant. A member’s name is the one Teams lists. If Teams lists none, it is the name the bridge has seen that person use or be @mentioned under. If the bridge has seen none either, the member is listed without a name, and the agent is told not to guess. The agent may @mention a member of the same conversation only when someone in it asks the agent to pass something on or to notify someone. It never does so on its own. Anyone not in the conversation is written as plain text. Set mentions: false in the profile block to have every mention posted as plain text instead.

Plots and files. Each plot arrives as its own message directly after the answer, one image per message, attached inline. Every other file goes into the one file library set aside for the bot (step 9). That covers a table, a PDF, or an image too large to attach. Each run’s files go into a folder of their own, and each file is shared with the people in the conversation at the moment it was sent. One message per file carries an Open button; opening it takes a Microsoft 365 sign-in. People who join a channel later cannot open older files, the files do not appear in the channel’s Files tab, and the library’s own retention rules apply to them. No organisation-wide or anonymous link is ever made. This is the opposite of the Google Chat deployment, where files are published as public links.

Note

What the agent cannot exchange in Teams.

  • Inline images are PNGs up to 1 MB. Each one is fitted into a 1024×1024 box and re-encoded before posting. One still over 1 MB after that goes to the file library at its original size instead.

  • Documents need the file library. Without TEAMS_FILES_DRIVE_ID, PDFs, CSVs and other files are not delivered, and one last message names each one so the answer never quietly omits it. The same note names a file whose upload or share failed.

  • Images need Pillow to be posted inline. It is installed with the teams extra, which the shipped image uses. Without it every image takes the file library, or is named in the note when there is none.

  • Files attached to a question are ignored. Teams attachments are not downloaded. So a question that says “look at this log” and attaches one gets an answer written without it. Paste the relevant part into the message instead.