Build Your First Copilot Connector with the Agents Toolkit

Most of the value people expect from Microsoft 365 Copilot lives outside Microsoft 365. The knowledge your staff actually need is sitting in a policy library, a claims system, a project database, an old intranet nobody wants to touch. Copilot is good at the content already in your tenant, but the first question every organisation asks after the demo is some version of "can it answer questions about our stuff". That is what a Copilot connector does, and the Agents Toolkit is the fastest sane way to build one.

I have watched teams try to hand-roll this against the Microsoft Graph connectors API, wiring up ingestion, schema registration and connection lifecycle by hand. It can be done. It is also a lot of fiddly plumbing that the Agents Toolkit now handles for you, so before anyone spends a fortnight rebuilding scaffolding, this is the path I would point them at.

What a connector actually is

Strip away the marketing and a Copilot connector is a pipe plus a contract. The pipe pushes records from your source system into the Microsoft Graph semantic index. The contract is a schema that tells Copilot what each field means and who is allowed to see each record. Once your data is in that index, Copilot can search it, cite it, and reason over it alongside everything else in the tenant.

The important mental shift is that you are not building a chatbot. You are feeding a shared index that Copilot draws on. Get the data and the permissions right and Copilot does the hard part. Get them wrong and you have either an assistant that cannot find anything or, much worse, one that cheerfully surfaces records to people who should never see them.

Why the Agents Toolkit earns its place

The Agents Toolkit is the Visual Studio Code and Visual Studio extension for building Microsoft 365 extensibility projects. For connectors, it gives you a project template, local debugging, and the deployment glue that used to be a manual slog. The Microsoft walkthrough on building your first connector takes you through the mechanics. What I want to add is where the toolkit genuinely helps and where you still have to think.

The honest win is the scaffolding. You scaffold a connector project, you get a working sample that registers a connection, defines a schema, and pushes some items, and you can run the whole thing locally against your dev tenant within an hour. For a team that has never touched Graph connectors, that hour saves a lot of confused reading of API docs. It turns "how do we even start" into "right, now let us change the schema to match our data".

The other win is that the toolkit keeps the connection definition, schema, and app registration in one project you can put in source control. Before this, the connection setup lived in scripts or Graph Explorer calls that nobody remembered six months later. Having it as code you review and redeploy is a real improvement for anything you intend to keep running.

The shape of the work

Here is roughly how a first connector goes once you have the toolkit installed and a dev tenant to point at.

You start from the connector template, which sets up an app registration with the Graph permissions a connector needs, plus a bit of code that creates the connection and registers a schema. The schema is where you spend your actual thinking time. Every property you push gets flags: is it searchable, is it queryable, is it retrievable, is it refinable. These are not cosmetic. A field that is not retrievable will not come back in results even though Copilot indexed it, and I have seen people lose an afternoon to exactly that. Decide deliberately which fields matter for search and which are just there for display.

Then you write the ingestion. This is your code reading from the source system and mapping each record to a Graph external item with your schema's properties. For a first pass you might pull a static list or a small API page. In production this becomes a proper sync, which I will come back to.

Every item you push carries an access control list. This is the part I will not let a team skip. The ACL says which Entra users or groups can see this record, and Copilot enforces it at query time. If your source system has row-level or record-level access rules, they have to be reflected here, per record. The lazy default is to grant everyone, and it makes the demo look great and the security review go badly.

Once items are flowing, you register the connector in the tenant, wait for the index to catch up, and start asking Copilot questions that should hit your data. The toolkit's local debugging lets you watch the ingestion and catch mapping mistakes before you blame Copilot for not finding things.

Where it is still rough

The toolkit is good, but it is not magic, and a few things consistently bite.

The indexing delay throws people. You push items and they do not appear in Copilot instantly. There is a lag while the semantic index processes them, and during early testing that lag makes it feel like your push failed when it did not. Build a habit of checking the connection's ingestion status rather than assuming a missing result means broken code.

Schema changes are not free. Decide your searchable and retrievable flags carefully up front, because changing a registered schema later is more painful than getting it close the first time. This is one of those areas where an hour of design saves a re-ingestion of your whole dataset.

And the sample is a sample. It shows you a happy path with a handful of items. Real source systems have paging, rate limits, deletions, and records that do not map cleanly. The toolkit gets you to a working connector fast, but the distance between that and a production sync that handles a hundred thousand records without hammering the source is real engineering. That gap is most of the actual project, and it is where a lot of our Copilot Studio consulting work concentrates, because clients underestimate it every time.

Freshness is the part that decides trust

A connector that ingests once and never updates is worse than no connector, because it answers with confidence from stale data. If your project database says a job is closed and Copilot says it is open because it indexed the old state, people stop trusting Copilot entirely, and that mistrust spreads to the parts that were working fine.

So the sync strategy matters more than the initial load. You want incremental sync, pushing only what changed, on a schedule that matches how fast the source moves. A policy library might be fine on a nightly crawl. An operational system might need updates every few minutes. The thing teams forget is deletions. When a record disappears at the source, your connector has to remove it from the index, or you get ghosts, results pointing at things that no longer exist. Handling deletions properly is unglamorous and it is the difference between a connector people rely on and one they learn to ignore.

Should you build one, and who should

My blunt take: connectors are worth it when the knowledge people need is genuinely trapped outside Microsoft 365 and searched often. If the content is already in SharePoint and Teams, Copilot can mostly see it already and a connector adds cost for little gain. The strong cases are line-of-business systems, custom databases, and knowledge stores that have no Microsoft-native surface.

The Agents Toolkit lowers the barrier enough that a capable in-house .NET or TypeScript team can build a solid first connector, and I would encourage them to. Where it gets harder is the permissions modelling against a system with complex access rules, and the production sync that stays fast and honest at scale. That judgement is a big part of our Microsoft AI consulting, and it sits alongside the broader agent work we do as AI agent builders, because a connector is often step one before the more interesting agents that sit on top of it.

If you have a system full of knowledge your staff keep asking about and you want Copilot to actually answer from it, that is exactly the kind of thing worth scoping properly. Have a look at what we do, or get in touch and tell us what you want Copilot to know.

Reference: Build your first connector with the Agents Toolkit