TypeSpec para Microsoft 365 Copilot visão geral

TypeSpec for Microsoft 365 Copilot é uma linguagem específica de domínio (DSL) que você pode usar para criar agentes declarativos e plug-ins de API com uma sintaxe limpo 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 fornece 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 o suporte IntelliSense, segurança de tipo e validação abrangente, você pode se concentrar no comportamento do agente e não nos detalhes de configuração.

Dica

As Ferramentas de Desenvolvimento do Work IQ (versão prévia) e o Kit de Ferramentas de Agentes do Microsoft 365 fornecem fluxos de trabalho de código profissional relacionados. Para escolher com base em sua funcionalidade, rota de pacote e experiência de destino, consulte Escolher ferramentas de desenvolvimento para seu plug-in.

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 de provisioná-los. 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.

O suporte do IntelliSense no Visual Studio Code e no Visual Studio fornece comentários em tempo real, preenchimento automático e documentação embutida. A linguagem se integra ao Microsoft 365 Agents Toolkit, oferecendo um fluxo de trabalho de desenvolvimento completo desde a criação até o provisionamento e publicação. As mensagens de erro são claras e acionáveis, ajudando você a identificar e resolve rapidamente problemas durante o desenvolvimento.

Criação simplificada de agentes e plug-ins

O TypeSpec simplifica 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, você pode 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 ajuda 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. Você pode 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 de 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 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

O TypeSpec para Microsoft 365 Copilot gera automaticamente arquivos de manifesto válidos a partir 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 associaçã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, para que você receba comentários imediatos e não provisione 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

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

Introdução

Para começar a criar com o TypeSpec para o Microsoft 365 Copilot, confira os seguintes recursos:

Conteúdo relacionado

  • Última atualização em