Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
TypeSpec per Microsoft 365 Copilot è un linguaggio DSL (Domain Specific Language) che è possibile usare per creare agenti dichiarativi e plug-in API con una sintassi pulita ed espressiva. Basato su TypeSpec, questo linguaggio specializzato offre decoratori specifici per Microsoft 365 e funzionalità che semplificano il processo di sviluppo per l'estensione di Microsoft 365 Copilot. TypeSpec rappresenta un'alternativa alla creazione manuale dei file manifesto JSON. Offre un approccio più intuitivo per gli sviluppatori con maggiore produttività e gestibilità.
TypeSpec per Microsoft 365 Copilot fornisce un livello di astrazione di alto livello su schemi JSON complessi e file OpenAPI. Il linguaggio genera automaticamente i file manifesto e le configurazioni richieste, riducendo i tempi di sviluppo e minimizzando gli errori. Con il supporto IntelliSense, la sicurezza dei tipi e la convalida completa, è possibile concentrarsi sul comportamento dell'agente anziché sui dettagli di configurazione.
Suggerimento
Consigliato: Inizia con Work IQ Dev Tools per scenari di agenti dichiarativi e plug-in pro-code supportati. Vedere la guida introduttiva di WIQD. Le istruzioni basate su toolkit rimangono disponibili per i progetti e i flussi di lavoro esistenti che le richiedono. Controlla il supporto per le funzionalità e l'esperienza di destinazione prima di scegliere uno strumento: WIQD non si rivolge agli agenti del motore personalizzato.
Sicurezza dei tipi ed esperienza di sviluppo
TypeSpec per Microsoft 365 Copilot offre un'esperienza di sviluppo fortemente tipizzata che rileva gli errori in fase di compilazione anziché in fase di esecuzione. Il linguaggio include il controllo completo dei tipi per tutti i costrutti specifici di Microsoft 365 Copilot, assicurandosi che gli agenti dichiarativi e i plug-in API siano configurati correttamente prima di eseguirne il provisioning. Questa sicurezza dei tipi si estende a tutti gli aspetti della definizione dell'agente, dai metadati di base alle configurazioni di funzionalità complesse e alle definizioni delle operazioni delle API.
Il supporto di IntelliSense in Visual Studio Code e Visual Studio fornisce feedback in tempo reale, completamento automatico e documentazione in linea. Le procedure dettagliate di TypeSpec in questa documentazione usano Microsoft 365 Agents Toolkit per la compilazione, il provisioning e la pubblicazione. Tali procedure rimangono disponibili; la raccomandazione di WIQD non implica che WIQD supporti lo stesso flusso di lavoro TypeSpec. I messaggi di errore sono chiari e fruibili e consentono di identificare e risolvere rapidamente i problemi durante lo sviluppo.
Creazione semplificata di agenti e plug-in
TypeSpec semplifica il processo di creazione di agenti dichiarativi e plug-in API sostituendo configurazioni JSON dettagliate con una sintassi intuitiva basata su Decorator. Invece di creare manualmente file manifesto complessi, puoi usare decoratori semantici come @agent, @instructions, e @capabilities per definire i tuoi agenti. Questo approccio riduce la probabilità di errori di configurazione e rende la base di codice più gestibile e leggibile.
Quando si lavora con superfici API complesse, TypeSpec aiuta quando i file OpenAPI tradizionali diventano ingombranti e difficili da gestire. Le specifiche OpenAPI di grandi dimensioni con centinaia di endpoint, schemi annidati complessi e modelli di autenticazione complessi possono essere difficili da creare, gestire e comprendere. TypeSpec risolve questi punti critici fornendo astrazioni di livello superiore che generano automaticamente le specifiche OpenAPI sottostanti. Puoi concentrarti sulla definizione della logica di business e del comportamento delle API utilizzando la sintassi espressiva di TypeSpec, mentre il compilatore gestisce i dettagli della conformità OpenAPI, della convalida dello schema e della gestione dei riferimenti incrociati.
Il linguaggio fornisce decoratori incorporati per tutte le funzionalità di Microsoft 365 Copilot, tra cui ricerca Web, integrazione con OneDrive e SharePoint, messaggi di Teams, interprete di codice e altro ancora. I plug-in API traggono vantaggio dalla generazione automatica delle specifiche OpenAPI, in cui le operazioni TypeSpec vengono convertite in definizioni API REST. Questa automazione elimina la necessità di mantenere una documentazione API separata e garantisce la coerenza tra le definizioni TypeSpec e i contratti API risultanti.
Generazione e convalida automatica di manifesti
TypeSpec per Microsoft 365 Copilot genera automaticamente file manifesto validi dalle definizioni TypeSpec. Il compilatore del linguaggio analizza il codice TypeSpec e produce i manifesti JSON appropriati per gli agenti dichiarativi e i plug-in API, assicurando che siano conformi ai requisiti dello schema più recenti. Questo processo di generazione include una convalida completa, che rileva gli errori di configurazione comuni prima che raggiungano la produzione.
La generazione automatica va oltre la creazione di manifesti di base per includere configurazioni complesse, ad esempio schede adattive, impostazioni di autenticazione e metadati specifici delle funzionalità. TypeSpec convalida tutti i riferimenti, garantisce l'associazione dati corretta per le schede adattive e verifica che siano presenti tutte le proprietà necessarie. Questa convalida viene eseguita durante il processo di compilazione, in modo da ottenere un feedback immediato senza eseguire il provisioning di configurazioni non valide.
Esempi
Ecco alcuni esempi pratici che illustrano TypeSpec per la sintassi di Microsoft 365 Copilot:
Agente dichiarativo di 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
}
Agente con funzionalità
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 API con operazioni
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;
}
Guida introduttiva
Per iniziare a creare contenuti con TypeSpec per Microsoft 365 Copilot, vedi le risorse seguenti:
-
Decorators for TypeSpec for Microsoft 365 Copilot - Informazioni di riferimento per i decorator di Microsoft 365 Copilot, tra cui
@agent,@instructions,@capabilities, e altro ancora. - Funzionalità dell'agente dichiarativo in TypeSpec per Microsoft 365 Copilot - Guida alle funzionalità degli agenti come la ricerca sul Web, l'integrazione con OneDrive, i messaggi di Teams e l'interprete del codice.
- Supporto dell'autenticazione in TypeSpec per Microsoft 365 Copilot: modelli di autenticazione e configurazioni di sicurezza per agenti e plug-in basati su TypeSpec.
- Creare agenti dichiarativi usando Microsoft 365 Agents Toolkit e TypeSpec : esercitazione dettagliata per la creazione di un agente dichiarativo usando TypeSpec e Agents Toolkit.
- Crea plug-in API con TypeSpec per Microsoft 365 Copilot - Guida alla creazione di plug-in API con operazioni REST, schede adattive e autenticazione.
- Inizia con un esempio : esempi forniti dalla community.
Contenuti correlati
- Panoramica di Microsoft 365 Agents Toolkit - Panoramica di Microsoft 365 Agents Toolkit disponibile a livello generale.
- Documentazione sul linguaggio TypeSpec - Guide e specifiche ufficiali del linguaggio TypeSpec