Compartir a través de

Introducción a TypeSpec para Microsoft 365 Copilot

TypeSpec para Microsoft 365 Copilot es un potente lenguaje específico del dominio (DSL) que permite a los desarrolladores crear agentes declarativos y complementos de API mediante una sintaxis limpia y expresiva. Basado en TypeSpec, este lenguaje especializado proporciona funciones y decoradores específicos de Microsoft 365 que simplifican el proceso de desarrollo para ampliar Microsoft 365 Copilot. TypeSpec actúa como alternativa a la creación manual de archivos de manifiesto JSON, lo que ofrece un enfoque más descriptivo para los desarrolladores con mayor productividad y mantenimiento.

TypeSpec para Microsoft 365 Copilot transforma cómo los desarrolladores crean soluciones de extensibilidad de Copilot proporcionando una capa de abstracción de alto nivel sobre esquemas JSON complejos y archivos OpenAPI. El lenguaje genera automáticamente los archivos de manifiesto y las configuraciones necesarios, lo que reduce el tiempo de desarrollo y minimiza los errores. Con su amplia compatibilidad con IntelliSense, seguridad de tipos y validación completa, TypeSpec permite a los desarrolladores centrarse en la creación de experiencias innovadoras con tecnología de inteligencia artificial en lugar de luchar con detalles de configuración.

Seguridad de tipos y experiencia para desarrolladores

TypeSpec para Microsoft 365 Copilot proporciona una experiencia de desarrollo fuertemente tipada que detecta errores en tiempo de compilación en lugar de en tiempo de ejecución. El lenguaje incluye una comprobación completa de tipos para todas las construcciones específicas de Microsoft 365 Copilot, lo que garantiza que los agentes declarativos y los complementos de API estén configurados correctamente antes de la implementación. Esta seguridad de tipos se extiende a todos los aspectos de la definición del agente, desde metadatos básicos hasta configuraciones de funcionalidad complejas y definiciones de operaciones de API.

La experiencia del desarrollador se ha mejorado gracias a la amplia compatibilidad con IntelliSense en Visual Studio Code y Visual Studio, lo que proporciona comentarios en tiempo real, finalización automática y documentación insertada. El lenguaje se integra perfectamente con microsoft 365 Agents Toolkit, que ofrece un flujo de trabajo de desarrollo completo desde la creación hasta la implementación. Los mensajes de error son claros y accionables, lo que ayuda a los desarrolladores a identificar y resolver problemas rápidamente durante el desarrollo.

Creación simplificada de agentes y complementos

TypeSpec simplifica drásticamente el proceso de creación de agentes declarativos y complementos de API reemplazando configuraciones JSON detalladas por una sintaxis intuitiva basada en decorador. En lugar de crear manualmente archivos de manifiesto complejos, los desarrolladores pueden usar decoradores semánticos como @agent, @instructionsy @capabilities para definir sus agentes. Este enfoque reduce la probabilidad de errores de configuración y hace que el código base sea más fácil de mantener y legible.

Cuando se trabaja con superficies de API complejas, TypeSpec destaca donde los archivos openAPI tradicionales se vuelven difíciles de administrar y difíciles de administrar. Las especificaciones de OpenAPI grandes con cientos de puntos de conexión, esquemas anidados complejos y patrones de autenticación complejos pueden ser difíciles de crear, mantener y comprender. TypeSpec aborda estos puntos de dolor proporcionando abstracciones de nivel superior que generan automáticamente las especificaciones de OpenAPI subyacentes. Los desarrolladores pueden centrarse en definir la lógica de negocios y el comportamiento de la API mediante la sintaxis expresiva de TypeSpec, mientras que el compilador controla los detalles tediosos del cumplimiento de OpenAPI, la validación de esquemas y la administración entre referencias.

El lenguaje proporciona decoradores integrados para todas las funcionalidades de Microsoft 365 Copilot, incluida la búsqueda web, la integración de OneDrive y SharePoint, los mensajes de Teams, el intérprete de código y mucho más. Los complementos de API se benefician de la generación automática de especificaciones de OpenAPI, donde las operaciones TypeSpec se convierten sin problemas en definiciones de API REST. Esta automatización elimina la necesidad de mantener documentación de API independiente y garantiza la coherencia entre las definiciones de TypeSpec y los contratos de API resultantes.

Generación y validación automáticas de manifiestos

Una de las características más eficaces de TypeSpec para Microsoft 365 Copilot es su capacidad para generar automáticamente archivos de manifiesto válidos a partir de las definiciones de TypeSpec. El compilador de lenguaje analiza el código TypeSpec y genera los manifiestos JSON adecuados para agentes declarativos y complementos de API, lo que garantiza que se ajustan a los requisitos de esquema más recientes. Este proceso de generación incluye una validación completa, detectando errores de configuración comunes antes de que lleguen a producción.

La generación automática se extiende más allá de la creación básica de manifiestos para incluir configuraciones complejas, como tarjetas adaptables, configuración de autenticación y metadatos específicos de la funcionalidad. TypeSpec valida todas las referencias, garantiza el enlace de datos adecuado para las tarjetas adaptables y comprueba que todas las propiedades necesarias están presentes. Esta validación se produce durante el proceso de compilación, proporcionando comentarios inmediatos a los desarrolladores y evitando la implementación de configuraciones no válidas.

Ejemplos

Estos son ejemplos prácticos que muestran TypeSpec para Microsoft 365 Copilot sintaxis:

Agente declarativo básico

@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 funcionalidades

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;
}

Complemento de API con operaciones

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

using TypeSpec.Http;
using Microsoft.M365Copilot;

@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;
}

Introducción

¿Listo para empezar a compilar con TypeSpec para Microsoft 365 Copilot? Siga estos pasos:

Contenido relacionado

  • Last updated on