Introducción a TypeSpec para Microsoft 365 Copilot

TypeSpec para Microsoft 365 Copilot es un lenguaje específico de dominio (DSL) que puede usar para crear agentes declarativos y complementos de API con una sintaxis limpia y expresiva. Creado sobre la base de TypeSpec, este lenguaje especializado proporciona decoradores y capacidades específicos de Microsoft 365 que simplifican el proceso de desarrollo para ampliar Microsoft 365 Copilot. TypeSpec sirve como una alternativa a la creación manual de archivos de manifiesto JSON, lo que ofrece un enfoque más fácil de usar para los desarrolladores con mayor productividad y facilidad de mantenimiento.

TypeSpec para Microsoft 365 Copilot proporciona 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 necesarias, lo que reduce el tiempo de desarrollo y minimiza los errores. Con la compatibilidad con IntelliSense, la seguridad de tipos y la validación completa, puede centrarse en el comportamiento del agente en lugar de en los detalles de configuración.

Sugerencia

Work IQ Dev Tools (versión preliminar) y Microsoft 365 Agents Toolkit proporcionan flujos de trabajo relacionados con el código. Para elegir en función de su capacidad, ruta de paquete y experiencia de destino, consulte Elegir herramientas de desarrollo para el complemento.

Seguridad de tipos y experiencia del desarrollador

TypeSpec para Microsoft 365 Copilot proporciona una experiencia de desarrollo fuertemente tipada que detecta errores en tiempo de compilación en lugar de tiempo de ejecución. El lenguaje incluye una comprobación de tipos completa 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 aprovisionarlos. Esta seguridad de tipos se extiende a todos los aspectos de la definición del agente, desde los metadatos básicos hasta las configuraciones de capacidad complejas y las definiciones de operaciones de la API.

La compatibilidad de IntelliSense con Visual Studio Code y Visual Studio proporciona información en tiempo real, finalización automática y documentación en línea. El lenguaje se integra con Microsoft 365 Agents Toolkit, ofreciendo un flujo de trabajo de desarrollo completo desde la creación hasta el aprovisionamiento y la publicación. Los mensajes de error son claros y prácticos, lo que le ayuda a identificar y resolver problemas rápidamente durante el desarrollo.

Creación simplificada de agentes y complementos

TypeSpec simplifica el proceso de creación de agentes declarativos y complementos API al reemplazar las configuraciones JSON detalladas con una sintaxis intuitiva basada en decoradores. En lugar de crear manualmente archivos de manifiesto complejos, puedes usar decoradores semánticos como @agent, @instructions, y @capabilities para definir tus 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 API complejas, TypeSpec ayuda donde los archivos OpenAPI tradicionales se vuelven difíciles de manejar y difíciles de administrar. Las grandes especificaciones de OpenAPI con cientos de puntos finales, esquemas anidados complejos y patrones de autenticación intrincados pueden ser difíciles de crear, mantener y comprender. TypeSpec aborda estos puntos débiles al proporcionar abstracciones de nivel superior que generan automáticamente las especificaciones subyacentes de OpenAPI. Puede centrarse en definir la lógica empresarial y el comportamiento de la API mediante la sintaxis expresiva de TypeSpec, mientras que el compilador maneja los detalles del cumplimiento de OpenAPI, la validación del esquema y la gestión de referencias cruzadas.

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 OpenAPI, donde las operaciones de TypeSpec se convierten en definiciones de API REST. Esta automatización elimina la necesidad de mantener documentación de API separada y garantiza la coherencia entre las definiciones de TypeSpec y los contratos de API resultantes.

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

TypeSpec para Microsoft 365 Copilot genera automáticamente archivos de manifiesto válidos a partir de las definiciones de TypeSpec. El compilador del lenguaje analiza el código de TypeSpec y genera los manifiestos JSON adecuados para los agentes declarativos y los 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 exhaustiva, detectando errores de configuración comunes antes de que lleguen a la 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 adaptativas, configuraciones de autenticación y metadatos específicos de la capacidad. TypeSpec valida todas las referencias, garantiza un enlace de datos adecuado para las tarjetas adaptables y comprueba que estén presentes todas las propiedades necesarias. Esta validación se produce durante el proceso de compilación, por lo que recibe comentarios inmediatos y no aprovisiona configuraciones no válidas.

Ejemplos

Estos son algunos ejemplos prácticos que demuestran la sintaxis de TypeSpec para Microsoft 365 Copilot:

Agente declarativo básico

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 capacidades

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

Introducción

Para empezar a crear con TypeSpec para Microsoft 365 Copilot, consulte los siguientes recursos:

Contenido relacionado

  • Se actualizó por última vez el