Starting a Copilot Agent Project With the Agents Toolkit for VS Code

The first Copilot agent is always the hardest one, and almost never for the reason people expect. The agent logic - the instructions, the knowledge sources, the actions - is usually the easy part. What burns the first week is everything around it: how a project should be structured, how the manifest works, how you get the thing into a tenant so you can actually talk to it. I've watched capable developers at Australian companies stall for days at exactly that point, not because they lack skill but because the packaging and deployment story around Microsoft 365 is genuinely foreign if you've never shipped anything into it.

The Microsoft 365 Agents Toolkit for Visual Studio Code exists to collapse that first week into a first afternoon. It's the extension that scaffolds a working agent project, wires up the debugging loop, and handles the provisioning ceremony so you can get to the interesting part. If you're starting your first agent project, this is where you start it. Microsoft's walkthrough for creating a new project with the toolkit covers the click-by-click; what I want to add is the context around it, because the docs assume a few things that aren't true at most organisations.

What the toolkit does for you

If you've been around this ecosystem a while, the Agents Toolkit is the artist formerly known as Teams Toolkit, renamed and refocused as Microsoft pivoted everything toward agents. The rename caused a fortnight of confusion in every team I know that was mid-project at the time, but the new name does describe the tool better.

Installed into VS Code, it gives you three things that matter.

First, project scaffolding. You pick an agent type from the templates - a declarative agent being the sensible first choice - and it generates a complete, runnable project: the manifest files, the agent definition, the folder structure, the configuration for different environments. This alone is worth the install. The manifest format is fiddly, versioned, and unforgiving of hand-editing errors, and starting from a generated project that already validates saves you from a class of mistake that produces unhelpful errors at upload time.

Second, the inner loop. Press F5 and the toolkit packages your agent, pushes it into your development tenant, and opens Copilot so you can chat with what you just built. Change the instructions, F5 again, test again. It's not as tight as hot reload in a web project, but compared with manually zipping app packages and uploading them through admin portals - which is what this used to be - it's a different sport.

Third, lifecycle commands for provisioning and publishing when you move beyond your own dev tenant. Environments are defined in config files that live in the repo, which means the path from "works on my machine" to "deployed properly" is at least versioned and repeatable.

What you need before you start

This is the section I wish someone had handed me before my first agent, because the toolkit's prerequisites are where most of the real friction lives.

You need a Microsoft 365 tenant where you're allowed to upload custom apps, with a Copilot licence attached to the account you're testing with. Most developers at most companies have neither on their day-to-day account, and IT is rightly reluctant to switch on custom app upload in the production tenant so someone can experiment. The answer is the Microsoft 365 developer program tenant or a properly set up dev tenant, and sorting this out is an IT conversation, not a coding task. Start that conversation before you install anything, because it has a lead time and the toolkit is useless without it.

You also need Node.js installed, since the toolkit's tooling runs on it even for agent types where you're not writing JavaScript. And you need to be signed in to the right accounts inside VS Code - the toolkit will prompt you, but if your machine has a personal Microsoft account and a work account and a dev tenant account, take a moment to check which one it grabbed. A confusing proportion of "the toolkit is broken" reports we've helped clients through turn out to be "signed into the wrong tenant".

None of this is hard. All of it is annoying if you discover it mid-flow at 4pm.

The new-project flow, honestly

The actual creation flow is short: open the toolkit panel, create a new agent, pick your template, name it, and you have a project. For a declarative agent, the files that matter are the agent definition - where the instructions, conversation starters and capabilities live - and the manifest that packages it for Microsoft 365. Everything else is scaffolding you can mostly ignore on day one.

My advice for the first project: change one thing at a time. Take the generated template, F5 it, and confirm the untouched version works in Copilot before you edit anything. Then change the instructions and go again. The feedback loop is the product here, and you want to establish a known-good baseline before you start layering in knowledge sources and API actions, because when something breaks later you'll want to know which change broke it. This sounds obvious. It is also the exact discipline that evaporates when a developer is excited about a new toy, and the debugging session that follows is always longer than the discipline would have been.

The first F5 is slow, by the way. Provisioning, consent prompts, package upload - budget a few minutes and don't assume it's hung. Subsequent runs are much quicker.

Where it's still rough

The toolkit is the best on-ramp this ecosystem has had, and it's still got edges.

Template churn is real. The set of project templates, their names, and what they generate has changed repeatedly as Microsoft's agent story evolved, so screenshots in tutorials more than a few months old often won't match what you see. Trust the current docs and the tool itself over anything with a date on it.

Error messages at the boundary between your project and the tenant can be opaque. When a manifest is subtly wrong or a tenant setting blocks upload, the failure sometimes surfaces as a generic error a long way from the cause. The toolkit's output panel in VS Code has more detail than the notification toast; make a habit of reading it.

And the toolkit gets you a working agent, not a good one. Instructions that make an agent genuinely useful take iteration and testing with real users and real questions. That part is craft, and it's where projects succeed or die - we wrote about testing approaches in a previous post on testing agents with the toolkit, and I'd treat testing as a first-class part of the project rather than a step at the end.

Making it count

Here's the pattern that works, from watching a good number of Australian organisations go through this: one developer, one afternoon, one deliberately small internal agent. An HR policy answerer, a "how do I" agent for one team's tooling, something with a bounded knowledge source and no API calls. The goal of the first project isn't the agent - it's that the developer comes out the other side knowing the toolkit, the tenant setup, and the deploy loop, which makes the second agent a fraction of the cost of the first.

If you'd rather compress that learning curve, that's a thing we do. Our Copilot training gets teams through the setup pain and into building working agents with someone in the room who's already hit every one of these snags, and our Microsoft AI consulting team builds agents alongside client teams so the knowledge stays in-house when we leave. For organisations further along, our AI agent developers take on the bigger builds where the declarative model runs out of road.

But honestly, if you've got the dev tenant sorted and a free afternoon, just install the toolkit and build something. The barrier to a first working Copilot agent has never been lower, and the organisations getting value from this stuff are, without exception, the ones that started with something small and shipped it.