TypeSpec para Microsoft 365 Copilot visão geral

TypeSpec para Microsoft 365 Copilot é uma poderosa linguagem específica de domínio (DSL) que permite que os desenvolvedores criem agentes declarativos e plug-ins de API usando uma sintaxe limpa e expressiva. Criada com base no TypeSpec, essa linguagem especializada fornece decoradores e recursos específicos do Microsoft 365 que simplificam o processo de desenvolvimento para estender o Microsoft 365 Copilot. O TypeSpec serve como uma alternativa à criação manual de arquivos de manifesto JSON, oferecendo uma abordagem mais amigável ao desenvolvedor com produtividade e capacidade de manutenção aprimoradas.

O TypeSpec para Microsoft 365 Copilot transforma a forma como os desenvolvedores criam soluções de extensibilidade do Copilot, fornecendo uma camada de abstração de alto nível sobre esquemas JSON complexos e arquivos OpenAPI. A linguagem gera automaticamente os arquivos e configurações de manifesto necessários, reduzindo o tempo de desenvolvimento e minimizando erros. Com seu avançado suporte IntelliSense, segurança de tipo e validação abrangente, o TypeSpec permite que os desenvolvedores se concentrem na criação de experiências inovadoras baseadas em IA, em vez de lutar com detalhes de configuração.

Segurança de tipo e experiência do desenvolvedor

O TypeSpec para Microsoft 365 Copilot fornece uma experiência de desenvolvimento fortemente tipada que captura erros em tempo de compilação em vez de em tempo de execução. A linguagem inclui verificação de tipo abrangente para todas as construções específicas do Microsoft 365 Copilot, garantindo que seus agentes declarativos e plug-ins de API estejam configurados corretamente antes da implantação. Essa segurança de tipo se estende a todos os aspectos da definição do agente, desde metadados básicos até configurações complexas de recursos e definições de operação de API.

A experiência do desenvolvedor é aprimorada por meio do suporte avançado do IntelliSense no Visual Studio Code e no Visual Studio, fornecendo comentários em tempo real, preenchimento automático e documentação embutida. A linguagem se integra perfeitamente ao Microsoft 365 Agents Toolkit, oferecendo um fluxo de trabalho de desenvolvimento completo, desde a criação até a implantação. As mensagens de erro são claras e acionáveis, ajudando os desenvolvedores a identificar e resolver problemas rapidamente durante o desenvolvimento.

Criação simplificada de agentes e plug-ins

O TypeSpec simplifica drasticamente o processo de criação de agentes declarativos e plug-ins de API, substituindo configurações JSON detalhadas por sintaxe intuitiva baseada em decorador. Em vez de criar manualmente arquivos de manifesto complexos, os desenvolvedores podem usar decoradores semânticos como @agent, @instructions, e @capabilities para definir seus agentes. Essa abordagem reduz a probabilidade de erros de configuração e torna a base de código mais fácil de manter e legível.

Ao trabalhar com superfícies de API complexas, o TypeSpec se destaca onde os arquivos OpenAPI tradicionais se tornam difíceis de manejar e difíceis de gerenciar. Grandes especificações OpenAPI com centenas de pontos de extremidade, esquemas aninhados complexos e padrões de autenticação intrincados podem ser difíceis de criar, manter e entender. O TypeSpec aborda esses pontos problemáticos fornecendo abstrações de nível superior que geram automaticamente as especificações OpenAPI subjacentes. Os desenvolvedores podem se concentrar na definição da lógica de negócios e do comportamento da API usando a sintaxe expressiva do TypeSpec, enquanto o compilador lida com os detalhes tediosos da conformidade com OpenAPI, validação de esquema e gerenciamento de referência cruzada.

A linguagem fornece decoradores internos para todos os recursos do Microsoft 365 Copilot, incluindo pesquisa na Web, integração com OneDrive e SharePoint, mensagens do Teams, interpretador de código e muito mais. Os plug-ins de API se beneficiam da geração automática de especificações OpenAPI, em que as operações TypeSpec são convertidas perfeitamente em definições de API REST. Essa automação elimina a necessidade de manter uma documentação de API separada e garante a consistência entre suas definições de TypeSpec e os contratos de API resultantes.

Geração e validação automáticas de manifesto

Um dos recursos mais poderosos do TypeSpec para Microsoft 365 Copilot é a capacidade de gerar automaticamente arquivos de manifesto válidos de suas definições de TypeSpec. O compilador de linguagem analisa seu código TypeSpec e produz os manifestos JSON apropriados para agentes declarativos e plug-ins de API, garantindo que eles estejam em conformidade com os requisitos de esquema mais recentes. Esse processo de geração inclui validação abrangente, detectando erros comuns de configuração antes que eles atinjam a produção.

A geração automática vai além da criação básica de manifesto para incluir configurações complexas, como cartões adaptáveis, configurações de autenticação e metadados específicos de funcionalidade. O TypeSpec valida todas as referências, garante a vinculação de dados adequada para cartões adaptáveis e verifica se todas as propriedades necessárias estão presentes. Essa validação ocorre durante o processo de compilação, fornecendo comentários imediatos aos desenvolvedores e evitando a implantação de configurações inválidas.

Exemplos

Aqui estão exemplos práticos que demonstram o TypeSpec para a sintaxe do Microsoft 365 Copilot:

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

Plugin de API com operações

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

Introdução

Pronto para começar a criar com o TypeSpec para Microsoft 365 Copilot? Siga estas etapas:

Conteúdo relacionado

  • Last updated on