# Deploying an AI Agent in Microsoft Teams

> To put an AI agent in Microsoft Teams, you register a bot in Azure, host the agent logic on your own HTTPS endpoint and distribute an app package (manifest plus two icons) through the Teams admin center. Teams provides the chat interface; the model, data and logic stay with you.

Canonical URL: https://www.ruebstudio.de/en/guides/ai-agent-integrations/deploy-ai-agent-in-microsoft-teams  
Author: Dr.-Ing. Marcus Rüb, CEO  
Published: 2026-11-09

If your organisation already lives in Microsoft Teams, that is where questions get asked. An AI agent that answers there needs no new interface and no extra tool to roll out. This guide treats Teams as the **front end** for an agent you build and run yourself: registration, packaging, admin rollout, and where this differs from Copilot agents. Reading mail, files and calendars from Microsoft 365 is a separate topic, covered in [Connecting an AI Agent to Microsoft 365](https://www.ruebstudio.de/en/guides/ai-agent-integrations/connect-ai-agent-microsoft-365).

## What does deploying an AI agent in Teams actually involve?

Deploying an agent in Teams means your agent runs on your own server and Teams forwards user messages to it over HTTPS. People talk to it in a one-to-one chat, a group chat or a channel. Teams handles sign-in, the chat interface and distribution; you control the model, the logic and every data access.

Microsoft's [app packaging documentation](https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/apps-package) is explicit: Teams does not host your app. Users install a package containing only a manifest and icons. The logic and data storage live elsewhere, on localhost during development and on infrastructure such as Azure in production.

That split shapes every later decision:

- **Where data is processed:** on your endpoint, by the model you choose.
- **What Teams contributes:** user identity, the chat surface, cards, distribution and IT policies.
- **What you have to run:** an always-on service with authentication, logging and updates.

Microsoft calls agents that bring their own model and orchestration [custom engine agents](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/overview-custom-engine-agent). According to the documentation they give developers full control over workflows, models and integrations instead of relying on Microsoft 365 Copilot's orchestration.

## Custom engine agent or Copilot agent: which one do you need?

A declarative Copilot agent is configuration (instructions, knowledge sources and actions) that runs on Microsoft 365 Copilot. A custom engine agent brings its own model, orchestration and hosting. Microsoft itself points to custom engine agents when you need complete control over the model, orchestration, hosting or user interface.

Microsoft describes [declarative agents](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/overview-declarative-agent) as goal-directed conversational experiences powered by Microsoft 365 Copilot. You define purpose, instructions, knowledge and actions; Microsoft supplies the model and orchestration. The same page draws the line: if the solution requires complete control of orchestration, model, hosting or interface, compare declarative and custom engine agents.

| Criterion | Declarative agent | Custom engine agent in Teams |
|---|---|---|
| Model | Microsoft 365 Copilot | your choice, including self-hosted |
| Orchestration | Copilot | your own (LangGraph, Semantic Kernel, plain code) |
| Hosting | Microsoft | your server or cloud |
| Channels and group chats | depends on the Copilot surface | yes, via bot scopes |
| Effort | low, configuration | higher, a software project |

In practice: if you want answers from SharePoint content and already pay for Copilot, a declarative agent gets you there quickly. If you must use a specific model (for instance one running in your own data centre), call your own tools, run multi-step workflows or have the agent work alongside a whole team in a channel, you need a custom engine agent. Copilot Studio sits in between: low-code, hosted by Microsoft, and listed by Microsoft as one of the routes to a custom engine agent.

## How does a Teams agent work under the hood?

A Teams agent has four parts: a bot identity registered in Azure, an HTTPS endpoint running your agent logic, an app package with a manifest and icons, and approval by your Teams administrators. Teams sends each message to your endpoint as an activity; your code replies with text, cards or a streamed response.

### Part 1: Bot registration in Azure

You create the bot identity as an **Azure Bot** resource. [Microsoft Learn](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) lists three identity options: user-assigned managed identity, single-tenant app and multi-tenant app. Creating new multi-tenant bots has been deprecated since 31 July 2025, so pick single-tenant or managed identity. You also choose global or local data residency; the same page lists local residency for the West Europe and Central India regions, which matters if your data protection team asks where message traffic is handled.

### Part 2: The endpoint with your agent logic

Your service accepts messages on a path such as `/api/messages`. Everything that makes the agent useful lives here: prompts, model calls, tools, access to your ERP or ticketing system, and logging. Teams does not care which model you use, as long as the endpoint is reachable over HTTPS.

### Part 3: The app package

The [app package](https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/apps-package) is a zip file holding `manifest.json` and two PNG icons, one in colour and one outline. The manifest declares name, description, the bot ID from Azure, the scopes (personal, group chat, team) and any permissions. Microsoft states that custom engine agents are supported from [app manifest version 1.21](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/overview-custom-engine-agent) onwards.

### Part 4: Admin approval

Nobody sees the agent until it is approved and distributed. The rollout section below covers how.

## Which SDKs and tools should you use (as of November 2026)?

New Teams agents have two pro-code options: the Teams SDK, built specifically for Teams including channels and meetings, and the Microsoft 365 Agents SDK, for agents that should also run in Copilot, websites or partner platforms. The older Bot Framework SDK is out of support.

**Teams SDK.** Microsoft's [overview](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/overview-custom-engine-agent) positions it for collaborative agents in Teams channels and meetings. It is available for TypeScript, C# and Python. The [quickstart](https://learn.microsoft.com/en-us/microsoftteams/platform/teams-sdk/getting-started/quickstart), dated 9 October 2026, requires Node.js 22.12 or later, .NET 8 or later, or Python 3.12 or later, and uses the Teams Developer CLI.

**Microsoft 365 Agents SDK.** Intended, per Microsoft, for multi-channel agents with custom orchestration such as Semantic Kernel or LangChain and any model. Choose it if the same agent must be reachable outside Teams too.

**Bot Framework SDK.** The [notice in the GitHub repository](https://github.com/microsoft/botframework-sdk) says long-term support ended in December 2025 and support tickets are no longer serviced as of 31 December 2025; the repository is archived. Existing bots continue to run, but do not start new work on it.

**Copilot Studio and Microsoft Foundry.** Copilot Studio is the low-code route with Microsoft-managed hosting. If your agents already run in Microsoft Foundry, Microsoft documents a direct publishing path to Microsoft 365 and Teams that provisions Azure Bot Service and Entra ID for you.

Getting started with the Teams SDK looks like this (commands from the official quickstart, Python variant):

```bash
# Install the Teams Developer CLI
npm install -g @microsoft/teams.cli
teams --version

# Scaffold an echo agent as a starting point
teams project new python quote-agent --template echo
cd quote-agent
python -m venv .venv && source .venv/bin/activate
pip install -e .
python src/main.py   # listens on port 3978
```

If you already run a Python service, the quickstart shows how to add Teams support with the `microsoft-teams-apps` package. The message handler is where your own model call goes:

```python
from microsoft_teams.apps import App

app = App()

@app.on_message
async def handle_message(ctx):
    # Replace the echo with your own model or orchestration call
    await ctx.send(f"You said: {ctx.activity.text}")
```

For local testing without a Teams tenant, use the Microsoft 365 Agents Playground. The quickstart warns that the option accepting unauthenticated requests is for local development only and must never be enabled in production.

## Where does Teams work well as the agent's interface?

Teams works well when the question comes up where people already collaborate: a project channel, a chat with the service desk, a quick exchange before a quote goes out. The agent brings knowledge or data into that conversation, so nobody has to switch applications to get an answer.

**Personal assistant in one-to-one chat.** Staff ask about an order status, an inspection procedure or a delivery note, and the agent searches connected systems and answers with a reference. The page on [AI agents for knowledge management](https://www.ruebstudio.de/en/ai-agents/knowledge-management) shows how such agents are structured.

**Agent in a project or service channel.** An agent that follows a channel can summarise tickets, collect open items or suggest relevant entries from the service history when someone asks about a machine. See [AI agents for technical service](https://www.ruebstudio.de/en/ai-agents/technical-service) for typical service workflows.

**Notifications and approvals.** The agent reaches out on its own, for example when a draft quote is ready, and offers an Adaptive Card with approve and reject buttons. A person stays in control ([human-in-the-loop](https://www.ruebstudio.de/en/glossary/human-in-the-loop)), and the decision is recorded in the chat. The page on [AI agents for quotation](https://www.ruebstudio.de/en/ai-agents/quotation) covers how agents prepare quotes.

When Teams is the wrong choice: if most users work outside Microsoft 365, if customers or suppliers without guest access need the agent, or if the task needs a proper form- and table-based interface. A web front end or an integration into the business application is usually better then.

## What do you need before you start?

You need a Microsoft 365 tenant with Teams, an Azure subscription for the bot registration, an always-on HTTPS endpoint for the agent logic, and someone with Teams administrator rights to approve the app. On top of that come model access and permissions for whichever systems the agent draws answers from.

In detail:

- **Tenant and roles:** a Teams administrator or Global Administrator to upload to the organisation's catalogue. For testing, an app setup policy that lets developers upload custom apps, or a separate test tenant.
- **Azure:** an Azure Bot resource with single-tenant or managed identity, the Microsoft Teams channel enabled and the messaging endpoint configured.
- **Hosting:** a service with a valid TLS certificate, monitoring and automatic restarts. Azure is one option; any server works as long as Teams can reach it.
- **Model:** a cloud model under a suitable contract or a self-hosted one ([local AI](https://www.ruebstudio.de/en/glossary/local-ai)). If personal data is involved, decide on processing location and data processing agreements first, not last.
- **Data access:** permissions for source systems. Reading mail, files or calendars goes through Microsoft Graph, as described in the guide to [connecting an agent to Microsoft 365](https://www.ruebstudio.de/en/guides/ai-agent-integrations/connect-ai-agent-microsoft-365).
- **Organisation:** a named owner for the agent, a written scope of what it may and may not do, and, depending on your country and company, involvement of the data protection officer and employee representatives once it processes staff messages.

## Step by step: from prototype to rollout

Getting into Teams takes five steps: build and test the agent locally, register the bot in Azure, create the app package, test with a small group, and release it to the organisation through the Teams admin center. Each step can be verified on its own and rolled back.

1. **Build locally.** Scaffold with the Teams Developer CLI, add your own model call to the handler, test in the Agents Playground. Only move to Teams once the answers are right.
2. **Register.** Create the Azure Bot (single-tenant or managed identity), set the messaging endpoint, enable the Teams channel. Put app ID, tenant ID and any secret in the service configuration, never in code.
3. **Package.** Fill in the manifest with bot ID, scopes and description, add both icons and zip it. The Microsoft 365 Agents Toolkit or the Developer Portal for Teams can generate and validate the package.
4. **Pilot.** Developers upload the app in the Teams client if their app setup policy allows it. Alternatively IT uploads it and limits access to a pilot group with an app permission policy.
5. **Roll out.** In the [Teams admin center](https://learn.microsoft.com/en-us/microsoftteams/upload-custom-apps), go to Teams apps > Manage apps > Upload new app. According to Microsoft the app appears in the "Built for your org" section of the Teams store after a few hours.

Updates follow the same route: upload a new version from the app's detail page. Microsoft notes that existing policies carry over to the new version. If only the server-side logic changes, you do not need a new package at all, because the package contains configuration only.

If the agent should see every message in a channel rather than only those that mention it, the manifest needs extra permissions. That is a deliberate decision, covered next.

## Limits and risks

An agent in Teams has access to conversations, and that is where the risks lie: overly broad permissions, unclear data flows to the model, unchecked answers in busy channels and a service someone has to keep running. The platform also has technical limits worth knowing before you commit.

**Listening requires consent.** According to [Microsoft](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc), an agent in group chats and channels only receives messages in which it is @mentioned by default. To receive everything it needs the resource-specific consent permissions `ChannelMessage.Read.Group` or `ChatMessage.Read.Chat`, and the team or chat owner must consent on installation. Messages from other bots, including the Workflows bot, are not delivered even then. An agent that reads everything also ingests text written by others, which opens the door to [prompt injection](https://www.ruebstudio.de/en/glossary/prompt-injection). Whether it should listen is a question for data protection and, where applicable, employee representatives, not just developers.

**Conversation retention.** Microsoft's custom engine agent documentation states that prompts and responses in Copilot Chat and Teams are stored under Microsoft 365 product terms and can be reviewed by admins through Content Search or Microsoft Purview. Anything your own service logs is your responsibility.

**Data flow to the model.** Teams hands the message to your endpoint, and from there it goes to your model. Where that model runs determines whether the setup can be operated in line with the GDPR or your local equivalent. This guide is not legal advice; involve your data protection officer.

**Message ordering.** Microsoft warns that messages can appear out of sequence if an agent mixes streaming, attachments and separate messages in one turn. The recommendation is a single stream per user turn, properly closed.

**Operations.** The agent is a long-running service. If it goes down, it simply falls silent in Teams. Certificates, secrets, model updates and costs all need an owner; the guide to [AgentOps](https://www.ruebstudio.de/en/guides/ai-agent-development/agentops-running-ai-agents) covers monitoring agents in production.

**Platform churn.** Microsoft has retired the Bot Framework SDK, renamed the Teams AI library to [Teams SDK](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/overview) and deprecated new multi-tenant bot registrations. Keep the Teams layer thin so your actual agent logic survives such changes.

## How should you get started?

Start with one well-defined question that people already ask in Teams, and an agent in one-to-one chat without permissions to read channels. That keeps data protection review and approval simple and quickly shows whether the answers hold up. Channels, cards and notifications come later.

A pragmatic path in three stages:

- **Stage 1:** pick the question, clarify the sources, build the agent locally with the Teams SDK and test it in the Agents Playground with real example questions.
- **Stage 2:** Azure Bot (single-tenant), HTTPS hosting, app package. Pilot with five to ten people via an app permission policy.
- **Stage 3:** review feedback, check answer quality and running costs, then decide: wider rollout, extension to channels, or a switch to a declarative agent if Copilot turns out to handle the task just as well.

In our own operations, it has paid off to build the Teams integration as a thin wrapper around an agent that runs and can be tested without Teams. The interface stays replaceable and tests run without a tenant. For an overview of agent types and use cases, see [AI agents](https://www.ruebstudio.de/en/ai-agents).

## Frequently asked questions

### Do I need Microsoft 365 Copilot licences to run a custom agent in Teams?

Microsoft describes custom engine agents as bringing your own orchestration and AI services rather than building on Copilot. It still lists licensing, consumption and hosting costs as things to check, so confirm the current terms with your IT team before rollout.

### Will the agent read every message in a channel?

Not by default. In channels and group chats an agent only receives messages in which it is @mentioned. Receiving all messages requires resource-specific consent permissions in the manifest, which the team or chat owner approves on installation.

### Is the Bot Framework SDK still an option?

Existing bots keep running, but Microsoft ended support for the Bot Framework SDK at the end of 2025 and archived the repository. New projects should start with the Teams SDK or the Microsoft 365 Agents SDK.

### How quickly does an uploaded agent reach users?

Microsoft states that an app uploaded by an admin becomes available to users after a few hours. For a single developer testing, uploading the package in the Teams client is faster if policy allows it.

## Sources

- [Microsoft Learn: Custom engine agents for Microsoft 365 overview](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/overview-custom-engine-agent)
- [Microsoft Learn: Declarative agents for Microsoft 365 Copilot](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/overview-declarative-agent)
- [Microsoft Learn: Teams SDK quickstart](https://learn.microsoft.com/en-us/microsoftteams/platform/teams-sdk/getting-started/quickstart)
- [Microsoft Learn: Package your app (Teams)](https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/apps-package)
- [Microsoft Learn: Manage custom app policies and settings](https://learn.microsoft.com/en-us/microsoftteams/upload-custom-apps)
- [Microsoft Learn: Configure an agent to receive all messages in group chats and channels](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc)
- [Microsoft Learn: Register a bot with Azure AI Bot Service](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration)
- [Microsoft Learn: Teams bots overview](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/overview)
- [GitHub: Bot Framework SDK retirement notice](https://github.com/microsoft/botframework-sdk)
