Présentation de TypeSpec pour Microsoft 365 Copilot

TypeSpec for Microsoft 365 Copilot est un langage spécifique à un domaine (DSL) que vous pouvez utiliser pour créer des agents déclaratifs et des plug-ins d’API avec une syntaxe expressive propre. Construit sur les bases de TypeSpec, ce langage spécialisé fournit des décorateurs spécifiques à Microsoft 365 et des fonctionnalités qui simplifient le processus de développement pour étendre Microsoft 365 Copilot. TypeSpec sert d’alternative à la création manuelle de fichiers manifestes JSON, offrant une approche plus conviviale pour les développeurs avec une productivité et une maintenabilité améliorées.

TypeSpec pour Microsoft 365 Copilot fournit une couche d’abstraction de haut niveau sur des schémas JSON complexes et des fichiers OpenAPI. Le langage génère automatiquement les fichiers manifestes et les configurations requis, ce qui réduit le temps de développement et les erreurs. Grâce à la prise en charge d’IntelliSense, à la sécurité du type et à la validation complète, vous pouvez vous concentrer sur le comportement de votre agent plutôt que sur les détails de configuration.

Conseil

Work IQ Dev Tools (préversion) et Microsoft 365 Agents Toolkit fournissent des flux de travail pro-code associés. Pour choisir en fonction de vos capacités, de l’itinéraire du package et de l’expérience cible, consultez Choisir des outils de développement pour votre plug-in.

Sécurité des types et expérience du développeur

TypeSpec pour Microsoft 365 Copilot offre une expérience de développement fortement typée qui intercepte les erreurs au moment de la compilation plutôt qu’au moment de l’exécution. Le langage inclut une vérification de type complète pour toutes les constructions spécifiques à Microsoft 365 Copilot, garantissant que vos agents déclaratifs et plug-ins d’API sont correctement configurés avant leur mise en service. Cette sécurité de type s’étend à tous les aspects de la définition de votre agent, des métadonnées de base aux configurations de capacités complexes et aux définitions d’opérations d’API.

La prise en charge d’IntelliSense dans Visual Studio Code et Visual Studio fournit des commentaires en temps réel, la saisie semi-automatique et une documentation en ligne. Le langage s’intègre à Microsoft 365 Agents Toolkit, offrant un workflow de développement complet, de la création à l’approvisionnement et à la publication. Les messages d’erreur sont clairs et exploitables, ce qui vous permet d’identifier et de résoudre rapidement les problèmes pendant le développement.

Création simplifiée d’agents et de plug-ins

TypeSpec simplifie le processus de création d’agents déclaratifs et de plug-ins d’API en remplaçant les configurations JSON détaillées par une syntaxe intuitive basée sur le décorateur. Au lieu de créer manuellement des fichiers manifestes complexes, vous pouvez utiliser des décorateurs sémantiques comme @agent, @instructionset @capabilities pour définir vos agents. Cette approche réduit le risque d’erreurs de configuration et rend la base de code plus facile à gérer et à lire.

Lorsque vous travaillez avec des surfaces d’API complexes, TypeSpec vous aide lorsque les fichiers OpenAPI traditionnels deviennent lourds et difficiles à gérer. Les grandes spécifications OpenAPI avec des centaines de points de terminaison, des schémas imbriqués complexes et des modèles d’authentification complexes peuvent être difficiles à créer, à maintenir et à comprendre. TypeSpec résout ces problèmes en fournissant des abstractions de haut niveau qui génèrent automatiquement les spécifications OpenAPI sous-jacentes. Vous pouvez vous concentrer sur la définition de la logique métier et du comportement de l’API à l’aide de la syntaxe expressive de TypeSpec, tandis que le compilateur gère les détails de la conformité d’OpenAPI, la validation du schéma et la gestion des références croisées.

La langue fournit des décorateurs intégrés pour toutes les fonctionnalités de Microsoft 365 Copilot, y compris la recherche web, l’intégration de OneDrive et SharePoint, les messages Teams, l’interprète de code, etc. Les plug-ins d’API bénéficient de la génération automatique de spécifications OpenAPI, où les opérations TypeSpec sont converties en définitions d’API REST. Cette automatisation élimine la nécessité de conserver une documentation d’API distincte et garantit la cohérence entre vos définitions TypeSpec et les contrats d’API résultants.

Génération et validation automatiques du manifeste

TypeSpec pour Microsoft 365 Copilot génère automatiquement des fichiers manifestes valides à partir de vos définitions TypeSpec. Le compilateur de langage analyse votre code TypeSpec et produit les manifestes JSON appropriés pour les agents déclaratifs et les plug-ins d’API, en veillant à ce qu’ils soient conformes aux dernières exigences de schéma. Ce processus de génération comprend une validation complète, qui intercepte les erreurs de configuration courantes avant qu’elles n’atteignent la production.

La génération automatique va au-delà de la création de manifestes de base pour inclure des configurations complexes telles que les cartes adaptatives, les paramètres d’authentification et les métadonnées spécifiques aux fonctionnalités. TypeSpec valide toutes les références, garantit la liaison de données appropriée pour les cartes adaptatives et vérifie que toutes les propriétés requises sont présentes. Cette validation se produit pendant le processus de génération, ce qui vous permet d’obtenir un retour immédiat et de ne pas provisionner de configurations non valides.

Exemples

Voici des exemples pratiques illustrant la syntaxe TypeSpec pour Microsoft 365 Copilot :

Agent déclaratif de base

import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;

@agent(
  "Customer Support Assistant",
  "An AI agent that helps with customer support inquiries and ticket management"
)
@instructions("""
  You are a customer support specialist. Help users with their inquiries,
  provide troubleshooting steps, and escalate complex issues when necessary.
  Always maintain a helpful and professional tone.
""")
@conversationStarter(#{
  title: "Check Ticket Status",
  text: "What's the status of my support ticket?"
})
namespace CustomerSupportAgent {
  // Agent capabilities defined here
}

Agent avec des fonctionnalités

import "@typespec/http";
import "@microsoft/typespec-m365-copilot";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;

@agent(
  "Multi-Capability Assistant",
  "An AI agent that can search the web, access SharePoint content, and execute Python code"
)
@instructions("""
  You are a versatile assistant that can help users with research, data analysis, and document management.
  Use web search for current information, access SharePoint for company documents, and execute Python code for calculations and data analysis.
  Always provide clear explanations of your findings and methodology.
""")
namespace MyAgent {
  op webSearch is AgentCapabilities.WebSearch<Sites = [
    {
      url: "https://learn.microsoft.com"
    }
  ]>;

  op oneDriveSearch is AgentCapabilities.OneDriveAndSharePoint<
   ItemsByUrl = [
      {
        url: "https://contoso.sharepoint.com/sites/projects"
      }
    ]
  >;

  op codeInterpreter is AgentCapabilities.CodeInterpreter;
}

Plug-in d’API avec opérations

import "@typespec/http";
import "@microsoft/typespec-m365-copilot";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;
using TypeSpec.M365.Copilot.Actions;

@agent(
  "Project Management Assistant",
  "An AI agent that helps manage projects and tasks through API operations"
)
@instructions("""
  You are a project management assistant that helps users create, track, and manage projects.
  Use the available API operations to list projects, get project details, and create new projects.
  Always provide clear status updates and help users organize their work effectively.
""")
@service
@server("https://api.contoso.com")
@actions(#{
  nameForHuman: "Project Management API",
  descriptionForHuman: "Manage projects and tasks",
  descriptionForModel: "API for creating, updating, and tracking project tasks"
})
namespace ProjectAPI {
  model Project {
    id: string;
    name: string;
    description?: string;
    status: "active" | "completed" | "on-hold";
    createdDate: utcDateTime;
  }

  model CreateProjectRequest {
    name: string;
    description?: string;
    status?: "active" | "on-hold";
  }

  @route("/projects")
  @get op listProjects(): Project[];

  @route("/projects/{id}")
  @get op getProject(@path id: string): Project;

  @route("/projects")
  @post op createProject(@body project: CreateProjectRequest): Project;
}

Prise en main

Pour commencer à créer avec TypeSpec pour Microsoft 365 Copilot, consultez les ressources suivantes :

Contenu connexe

  • Dernière mise à jour :