Copilot: Declarative Agents in TypeSpec

Key insights

• TypeSpec is a domain-specific language for defining declarative agents for Microsoft 365 Copilot.
  It simplifies complex JSON and OpenAPI work by letting developers describe agent behavior in a clear, typed syntax.
• Type safety catches many errors at design time so agents are less likely to fail at runtime.
  Developer experience improves with automatic manifest generation, inline feedback, and fewer manual configuration steps.
• Capabilities let agents access services like search, OneDrive/SharePoint, and code interpreters with configurable parameters.
  API plugins extend agents so they can integrate external APIs or custom business logic.
• Microsoft 365 Agents Toolkit in Visual Studio Code scaffolds projects, adds IntelliSense, and guides deployment steps.
  Use the toolkit to generate files, run local checks, and iterate quickly during development.
• OpenAPI and REST actions are produced from TypeSpec models so Copilot can call services reliably.
  Developers describe actions in TypeSpec, generate OpenAPI, wire plugins, and run the agent in Copilot Chat.
• Demo and labs show a practical workflow: define capabilities, generate manifests, wire plugins, and test in Copilot Chat.
  Start with the Copilot Developer Camp labs and the Agents Toolkit to follow the same step-by-step process.

Microsoft published a demonstration video that shows how to use TypeSpec to build declarative agents for Microsoft 365 Copilot. The recording, presented by Paolo Pialorsi from Microsoft during a community call on July 8, 2025, walks through modeling REST actions, scaffolding agents, and running them in Copilot Chat. This article summarizes the video for editorial readers, and it highlights practical steps, tradeoffs, and challenges for teams considering this approach.

Overview of the Demo

The video demonstrates a workflow that starts with describing agent capabilities in TypeSpec and ends with an agent running inside Copilot Chat. Paolo shows how the language maps high-level declarations into concrete artifacts such as generated manifests and an OpenAPI surface for backend interactions. In addition, he uses the Microsoft 365 Agents Toolkit inside VS Code to scaffold code, wire plugins, and test the agent locally.

Overall, the demo aims to show a practical path from design to execution with an emphasis on developer ergonomics and repeatability. It leans on the Copilot Developer Camp labs for hands-on steps and validation during the walkthrough. Consequently, viewers see both conceptual patterns and live examples that make the process easier to adopt.

Key Technical Highlights

A central technical point is that TypeSpec provides high-level abstractions over JSON schema and API descriptions, which simplifies manifest generation for Copilot agents. Paolo models REST actions and uses TypeSpec decorators to express Microsoft 365-specific capabilities, allowing the toolkit to output the required configuration files automatically. This automation reduces manual errors and saves time, especially when teams must manage many agent definitions.

The demo also shows how the generated OpenAPI specifications connect to API plugins and external services, enabling agents to perform actions like file access or web searches. While the tooling integrates tightly with VS Code, it also emphasizes the need for clear contract definitions between the agent and backend services. Thus, the approach favors compile-time safety and predictable behavior.

Developer Experience and Workflow

Using the Microsoft 365 Agents Toolkit in VS Code delivers a streamlined developer experience with code scaffolding, IntelliSense, and live feedback. Paolo demonstrates that real-time validation and auto-complete reduce the friction of writing and updating capability declarations. As a result, developers can iterate faster and focus on agent behavior rather than low-level manifest syntax.

However, the workflow also introduces dependencies on the toolkit and the editor ecosystem, which can create challenges for teams that prefer different toolchains. Teams may need to adapt their CI/CD processes to handle generated artifacts and ensure consistent builds. Therefore, while the developer experience improves productivity, it requires discipline around versioning and artifact management.

Tradeoffs and Practical Challenges

The declarative approach in TypeSpec trades flexibility for safety and speed; it enforces contracts that catch many errors earlier but can limit unconventional integration patterns. Paolo’s demo emphasizes type safety and automated generation, which reduce runtime surprises but may obscure low-level behavior that seasoned engineers sometimes need to tune. Consequently, teams must balance the convenience of abstraction with the option to drop down to manual configurations when necessary.

There are additional operational challenges such as security, testing, and governance. Declared capabilities that access files or external APIs require careful permission scoping and auditing, and generated manifests must be reviewed to meet compliance standards. Testing declarative agents also requires robust mocks and integration tests because the generated surface can hide complexity that only appears under real workloads.

Implications and Recommended Next Steps

For teams considering this path, start with a small pilot that models one or two capabilities and runs through the full cycle from TypeSpec declaration to Copilot Chat execution. This phased approach helps uncover configuration gaps, permission issues, and performance concerns before committing to a large-scale rollout. Moreover, involving security and platform teams early reduces rework and ensures governance requirements are met.

Finally, the video suggests that the ecosystem is evolving, so organizations should plan for change by keeping generated artifacts in source control and automating validation. While TypeSpec and the Agents Toolkit simplify many tasks, they introduce new operational patterns that teams must adopt. In sum, the demo offers a compelling workflow for rapid agent development, yet it also reminds teams to weigh the tradeoffs between abstraction, control, and long-term maintainability.

Keywords

TypeSpec declarative agents, Microsoft 365 Copilot TypeSpec, Declarative agents for Copilot, Build Copilot agents with TypeSpec, TypeSpec Copilot integration, Declarative AI agents Microsoft 365, Copilot agent development guide, TypeSpec tutorial for Copilot