Building Microsoft 365 Copilot Agents With the Teams AI TypeScript SDK - A Practical Look

There are two ways to build an agent for Microsoft 365 Copilot, and the choice you make on day one shapes everything that follows. You can use the low-code declarative route, describe your agent, point it at some knowledge, wire up a few actions through a designer, and ship. Or you can write it in code with the TypeScript SDK and get full control over how the agent thinks, what it can do, and how it fits into the rest of your systems. Most of the Australian businesses we work with start assuming they want the first option and end up needing the second, which is worth understanding before you commit.

I want to talk through the TypeScript SDK for Copilot extensibility from the perspective of someone who has shipped these things, not someone reading the marketing. Microsoft's TypeScript SDK documentation has the API reference. What follows is the context around it: when to reach for it, what it does well, and where it will make you work.

Declarative versus code, and why it matters more than people think

The declarative agent route is genuinely good for what it is. If you need an agent that answers questions from a defined set of SharePoint documents, follows a persona, and calls a couple of pre-built actions, you can build that without writing much code at all, and you should. Do not reach for the SDK to build something the low-code path handles perfectly well. That is just extra maintenance for no gain.

The SDK becomes the right choice the moment your agent needs to do something the designer cannot express. Custom logic that decides which tool to call based on business rules. Multi-step workflows where the agent has to hold state across a conversation. Integration with internal systems that speak their own protocols. Fine control over how the model reasons about a task. Once you are in that territory, the low-code path stops being a shortcut and starts being a ceiling, and fighting the designer to do something it was not built for is more painful than just writing the code.

The honest framing I give clients: start declarative, and switch to the SDK when you hit the first wall you cannot design your way around. Do not over-engineer from day one, but do recognise the wall early, because retrofitting real logic onto an agent that grew up as a declarative toy is more work than building it properly once you know you need to.

What the TypeScript SDK gives you

The SDK is built on the same foundations as building for Teams, which matters because it means the agents you build are not locked to a single surface. An agent built this way can show up in Copilot chat, in Teams, and across the other places Microsoft surfaces agents, from one codebase. For an organisation that already lives in Teams, that reach is a large part of the appeal. You are not building a bot that lives in a corner. You are building something that meets people where they already work.

In practical terms the SDK gives you the building blocks a real agent needs. You define how the agent handles incoming messages and activities. You wire up actions and tools it can call, your own APIs, internal services, whatever the business logic requires. You manage conversation state so the agent can carry context across turns instead of treating every message as isolated. And you control the prompt and reasoning layer, which is where a competent agent gets separated from a frustrating one.

Because it is TypeScript, you also get the thing that low-code cannot give you: it is real software. It goes in source control. It gets code review. It has tests. It ships through a proper pipeline. For anything that is going to live in production and be maintained by a team over years, that alone justifies the choice. A declarative agent configured through a portal is hard to version, hard to test, and hard to reason about when something breaks at 4pm on a Friday. Code is not.

Where it gets sharp

I would be doing you a disservice to pretend this is all smooth. A few things are worth going in with your eyes open.

The extensibility platform moves fast. Microsoft 365 Copilot and its extensibility story have been changing quickly, and SDKs that sit on a fast-moving platform inherit that pace. APIs get renamed, patterns get superseded, and documentation sometimes lags the reality by a version. You need to be comfortable reading release notes and occasionally discovering that the tutorial you followed last quarter is now the old way. This is normal for a platform this young, but it is a real cost, and a team that expects a stable, finished SDK will be unhappy.

The local development and debugging loop is better than it was and still not effortless. Building and testing an agent that ultimately runs inside Microsoft's cloud surfaces means your inner loop involves more moving parts than a plain web app. Getting a tight test-and-iterate cycle set up is worth the upfront effort because you will run that loop thousands of times, but budget for the setup.

Authentication and permissions are where the real complexity lives, and it is unavoidable rather than accidental. The moment your agent reaches into Microsoft Graph or an internal system, you are dealing with identity, consent, and scopes, and getting that right, especially so it works cleanly for every user and not just the developer who built it, is genuinely the hardest part of most agent projects. It is not the SDK's fault. It is the nature of an agent acting on behalf of users across an organisation's data. But it is where projects slow down, so plan for it rather than treating it as a detail.

How we build these on client work

When we build Copilot agents for clients, and this is a growing part of what our Microsoft AI consultants do, the SDK decision is one of the first real conversations we have. We are not precious about it. If the low-code path solves the problem, we use it and save everyone the cost of custom development. The SDK comes out when the requirements genuinely need it, custom logic, real integrations, workflows with state, and when the agent is going to be a maintained product rather than a one-off experiment.

The pattern that works is treating the agent like the piece of production software it is from the start. Source control, a real test setup, a deployment pipeline, and a clear-eyed plan for authentication before anyone writes the fun bits. The teams that struggle are the ones that treat the agent as a demo that accidentally went to production, because a demo has none of the scaffolding a maintained system needs, and bolting it on afterwards is miserable. This is the same discipline we bring to our broader AI agent development work: the model is the easy, exciting part, and the boring engineering around it is what determines whether the thing survives contact with real users.

The other thing we push clients on is being honest about what the agent is for. An agent that reaches into Graph, calls internal APIs, and holds conversation state is a serious piece of software with a real security surface. That is fine, it is often exactly what the business needs, but it deserves the same care as any system touching company data, not the "it is just a chatbot" treatment it sometimes gets.

The short version

The TypeScript SDK for Copilot extensibility is the right tool when your agent needs real logic, real integrations, or conversation state, and when it is going to be a maintained production system rather than a quick experiment. Its big wins are reach across Copilot and Teams from one codebase, and the fact that it is proper software you can version, test, and ship like anything else. Its rough edges are a fast-moving platform, a development loop with more moving parts than a normal web app, and authentication complexity that is unavoidable the moment the agent touches organisational data. Start declarative, move to the SDK when you hit the first wall you cannot design around, and treat the result like production software from day one.

If you are weighing up building a Copilot agent and are not sure whether the low-code path will hold up or whether you need to build it properly in code, that is exactly the conversation we have with clients before a line gets written. Take a look at our services or get in touch and tell us what you want the agent to actually do.