Общие сведения о TypeSpec для Microsoft 365 Copilot

TypeSpec для Microsoft 365 Copilot — это мощный язык DSL, который позволяет разработчикам создавать декларативные агенты и подключаемые модули API с помощью чистого выразительного синтаксиса. Этот специализированный язык, созданный на основе TypeSpec, предоставляет специальные декораторы Microsoft 365 и возможности, которые упрощают процесс разработки для расширения Microsoft 365 Copilot. TypeSpec служит альтернативой ручному созданию файлов манифеста JSON, предлагая более удобный для разработчиков подход с повышенной производительностью и удобством обслуживания.

TypeSpec для Microsoft 365 Copilot преобразует способы создания разработчиками решений расширяемости Copilot, предоставляя высокоуровневый уровень абстракции для сложных схем JSON и файлов OpenAPI. Язык автоматически создает необходимые файлы манифеста и конфигурации, сокращая время разработки и минимизируя ошибки. Благодаря богатой поддержке IntelliSense, безопасности типов и комплексной проверке TypeSpec позволяет разработчикам сосредоточиться на создании инновационных возможностей на основе ИИ, а не на подробной настройке.

Безопасность типов и взаимодействие с разработчиком

TypeSpec для Microsoft 365 Copilot предоставляет строго типизированный интерфейс разработки, который перехватывает ошибки во время компиляции, а не во время выполнения. Язык включает комплексную проверку типов для всех Microsoft 365 Copilot конструкций, гарантируя, что декларативные агенты и подключаемые модули API правильно настроены перед развертыванием. Этот тип безопасности распространяется на все аспекты определения агента, от базовых метаданных до сложных конфигураций возможностей и определений операций API.

Возможности разработчиков дополняются поддержкой IntelliSense в Visual Studio Code и Visual Studio, предоставляя обратную связь в режиме реального времени, автозавершение и встроенную документацию. Язык легко интегрируется с набором средств агентов Microsoft 365, предлагая полный рабочий процесс разработки от создания до развертывания. Сообщения об ошибках понятны и применимы, что помогает разработчикам быстро выявлять и устранять проблемы во время разработки.

Упрощенная разработка агентов и подключаемых модулей

TypeSpec значительно упрощает процесс создания декларативных агентов и подключаемых модулей API, заменяя подробные конфигурации JSON интуитивно понятным синтаксисом на основе декоратора. Вместо создания сложных файлов манифеста вручную разработчики могут использовать семантические декораторы, такие как @agent, @instructionsи @capabilities , для определения своих агентов. Такой подход снижает вероятность ошибок конфигурации и делает базу кода более доступной для обслуживания и чтения.

При работе со сложными поверхностями API TypeSpec отличается тем, что традиционные файлы OpenAPI становятся громоздкими и трудными в управлении. Крупные спецификации OpenAPI с сотнями конечных точек, сложными вложенными схемами и сложными шаблонами проверки подлинности могут быть сложными для разработки, обслуживания и понимания. TypeSpec устраняет эти проблемы, предоставляя абстракции более высокого уровня, которые автоматически создают базовые спецификации OpenAPI. Разработчики могут сосредоточиться на определении бизнес-логики и поведения API с помощью выразительного синтаксиса TypeSpec, в то время как компилятор обрабатывает утомительную информацию о соответствии OpenAPI, проверке схемы и управлении перекрестными ссылками.

Этот язык предоставляет встроенные декораторы для всех Microsoft 365 Copilot возможностей, включая поиск в Интернете, интеграцию OneDrive и SharePoint, сообщения Teams, интерпретатор кода и многое другое. Подключаемые модули API получают преимущества автоматического создания спецификаций OpenAPI, где операции TypeSpec легко преобразуются в определения REST API. Такая автоматизация устраняет необходимость в ведении отдельной документации ПО API и обеспечивает согласованность между определениями TypeSpec и результирующие контракты API.

Автоматическое создание и проверка манифеста

Одной из наиболее эффективных функций TypeSpec для Microsoft 365 Copilot является возможность автоматического создания допустимых файлов манифеста из определений TypeSpec. Компилятор языка анализирует код TypeSpec и создает соответствующие манифесты JSON для декларативных агентов и подключаемых модулей API, обеспечивая их соответствие последним требованиям схемы. Этот процесс создания включает комплексную проверку, перехватывая распространенные ошибки конфигурации, прежде чем они достигнут рабочей среды.

Автоматическое создание выходит за рамки базового создания манифеста и включает сложные конфигурации, такие как адаптивные карточки, параметры проверки подлинности и метаданные для конкретных возможностей. TypeSpec проверяет все ссылки, обеспечивает правильную привязку данных для адаптивных карточек и проверяет наличие всех необходимых свойств. Эта проверка выполняется во время процесса сборки, предоставляя разработчикам немедленную обратную связь и предотвращая развертывание недопустимых конфигураций.

Примеры

Ниже приведены практические примеры демонстрации синтаксиса TypeSpec для Microsoft 365 Copilot:

Базовый декларативный агент

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

Агент с возможностями

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

Подключаемый модуль API с операциями

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

Начало работы

Готовы приступить к сборке с помощью TypeSpec для Microsoft 365 Copilot? Выполните следующие действия:

Связанные материалы

  • Last updated on