Skip to content

Microsoft Teams#

Prism Agent can run in Microsoft Teams. It answers personal chats and channel @mentions, holds threaded conversations, and posts heartbeat alerts and scheduled-task results. Microsoft delivers each message to the agent as an HTTPS request, so Teams needs a public endpoint on the agent. Teams is optional; the runtime starts without it.

Create the Teams app#

To create the app the agent signs in as:

  1. In Microsoft Entra ID, navigate to App registrations and create a registration. Record the Application (client) ID and the Directory (tenant) ID. Under Certificates & secrets, create a client secret and copy its value.
  2. Create an Azure Bot resource. Select the type Single Tenant, then select Use existing app registration and enter the Application (client) ID.
  3. In the bot's Configuration, set Messaging endpoint to https://<YOUR-HOST>/agents/teams/messages. See Publish the messaging endpoint for the host.
  4. In the bot's Channels, enable Microsoft Teams.

  5. Create a Teams app package for the bot with the scopes personal and team, "supportsFiles": true, and "supportsChannelFeatures": "tier1". Give it the ChannelMessage.Read.Group permission, so the agent can follow up in a channel thread without an @mention. Without this permission, the agent answers @mentions only. The manifest needs these entries:

    "webApplicationInfo": { "id": "<TEAMS-APP-ID>", "resource": "https://prism" },
"authorization": {
  "permissions": {
    "resourceSpecific": [{ "name": "ChannelMessage.Read.Group", "type": "Application" }]
  }
}

  6. Upload the package to your tenant from the Teams Developer Portal. Your tenant must allow custom app upload.

  7. Optional. To let the agent read files shared in channels, a Microsoft 365 administrator adds the Microsoft Graph application permission Files.Read.All to the app registration and grants admin consent. Without it, the agent tells you that it could not read the file.

Configure the runtime#

The runtime reads three variables. Set all three to start the Teams adapter:

Variable Value
TEAMS_APP_ID The app registration's Application (client) ID.
TEAMS_APP_PASSWORD The app registration's client secret.
TEAMS_APP_TENANT_ID The Directory (tenant) ID of the app registration.

Put them in ~/.prism/.env for a native install or pass them with -e for Docker, then restart the runtime. On Lens Agents, toggle Microsoft Teams in the Prism Agent template instead: the platform keeps the client secret, and the sandbox holds only a placeholder. See Configuration.

Publish the messaging endpoint#

The runtime serves the bot endpoint, POST /agents/teams/messages, on its own port: 3979 by default, set by TEAMS_PORT. That port serves nothing else, and the runtime refuses every request on it that has no valid Bot Framework token. Publish that port over HTTPS with a valid certificate, and keep the web UI port, 3003, private.

  • Docker. Publish the port with -p 3979:3979, and terminate TLS in front of it.
  • Local development. Tunnel the port, for example with a dev tunnel: devtunnel host -p 3979 --allow-anonymous.
  • Lens Agents. The template publishes the port as the public teams port. The messaging endpoint is https://teams--<SANDBOX-SLUG>.<INGRESS-HOST>/agents/teams/messages.

An egress-filtered deployment must allow login.microsoftonline.com, login.botframework.com, and smba.trafficmanager.net, plus *.sharepoint.com and graph.microsoft.com for files and pasted images. A file shared in a channel is read through graph.microsoft.com, as is a pasted image that Teams hosts there. The Lens Agents template allows every host but graph.microsoft.com, so there the agent reads nothing through Microsoft Graph.

Before the agent talks to you, it needs to know who you are. Linking starts from the web UI Channels page, which issues a six-character code that is valid for about 15 minutes. Personal Mode and Team Mode are mutually exclusive: unlink all channels before you link a personal chat, and the other way around.

Personal Mode#

To chat with the agent:

  1. In the web UI, navigate to Channels and click Link Account under Personal Mode in the Microsoft Teams section.
  2. Open a personal chat with the agent in Teams and send it the code.
  3. The agent confirms the link. From then on, you can chat with it there.

If an unrecognized person messages the agent, it replies with a short prompt that explains how to link, rather than answering.

Team Mode#

To link a channel:

  1. In the web UI Channels page, click Add channel in the Microsoft Teams section to generate a channel link code.
  2. Add the agent's Teams app to the team.
  3. @mention the agent in the channel with the code. The agent confirms that it is connected.

You can link several channels. Click Add channel again for each one. Linked channels appear in a table, each with an Unlink action. A channel can be linked to one agent only.

When several channels are linked, one is the main channel (marked ★ in the table). The first channel you link becomes main. Heartbeat alerts post to the main channel only. Use Set main to move it.

How the agent behaves in Teams#

  • Personal chats. It replies to everything you send. The chat history stays in Teams, separate from the web chat.
  • Channels. It answers when you @mention it. In a thread it has answered in, it also answers a reply that asks it for something, with or without a mention, and leaves replies meant for other people alone. The agent knows which channel it is replying in.
  • Group chats. The agent ignores messages in group chats.
  • Threads. The agent replies in the thread of the message that mentioned it. A top-level mention starts a thread. Each Teams reply chain is its own conversation thread in Prism Agent.
  • Working cue. When your message arrives, the agent shows a typing indicator. Teams removes it after a few seconds, so on a long task the cue disappears before the reply arrives.
  • Messages sent mid-reply. A message that arrives while the agent works is handed to the running task. The agent reads it at its next step and adjusts.
  • Files. The agent reads files you send in a personal chat, images you paste into a message, and files shared in a channel when the optional Files.Read.All permission is granted. On Lens Agents, a file shared in a channel reaches the agent as a notice with its name. A file the agent shares arrives as a download link to the web UI's address. On a standalone server, set PRISM_PUBLIC_URL so that the link opens; see Configuration.
  • Formatting. Replies are markdown, and Teams renders tables.

Autonomous messages — heartbeat alerts and scheduled task results — arrive as posts. In Team Mode, heartbeat alerts go to the main channel. In Personal Mode, they arrive in your personal chat.