Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
TypeSpec для Microsoft 365 Copilot — это доменно-ориентированный язык (DSL), который можно использовать для создания декларативных агентов и плагинов API с простым выразительным синтаксисом. Этот специализированный язык, созданный на основе TypeSpec, предоставляет специфичные для Microsoft 365 декораторы и возможности, которые упрощают процесс разработки для расширения Microsoft 365 Copilot. TypeSpec служит альтернативой ручному созданию файлов манифеста JSON, предлагая более удобный для разработчиков подход с повышенной производительностью и удобством обслуживания.
TypeSpec для Microsoft 365 Copilot предоставляет высокоуровневый уровень абстракции для сложных схем JSON и файлов OpenAPI. Язык автоматически создает необходимые файлы манифеста и конфигурации, сокращая время разработки и минимизируя ошибки. Благодаря поддержке IntelliSense, безопасности типов и комплексной проверке вы можете сосредоточиться на поведении агента, а не на деталях конфигурации.
Совет
Рекомендуется: Начните с Work IQ Dev Tools для поддерживаемых сценариев декларативного агента и плагинов для кода. См. краткое руководство по WIQD. Инструкции на основе набора средств остаются доступными для существующих проектов и рабочих процессов, для которых они требуются. Перед выбором инструмента проверьте поддержку возможностей и целевого интерфейса : WIQD не нацелен на агентов пользовательской подсистемы.
Безопасность ввода и взаимодействие с разработчиками
TypeSpec для Microsoft 365 Copilot обеспечивает строго типизированный интерфейс разработки, который обнаруживает ошибки во время компиляции, а не во время выполнения. Язык включает комплексную проверку типов для всех конструкций Microsoft 365 Copilot, гарантируя, что ваши декларативные агенты и плагины API правильно настроены перед их подготовкой. Безопасность этого типа распространяется на все аспекты определения агента, от базовых метаданных до сложных конфигураций возможностей и определений операций API.
Поддержка IntelliSense в Visual Studio Code и Visual Studio обеспечивает обратную связь в режиме реального времени, автозаполнение и встроенную документацию. В пошаговых руководствах по TypeSpec в этой документации используется набор средств агентов Microsoft 365 для компиляции, подготовки и публикации. Эти процедуры по-прежнему доступны; рекомендация WIQD не означает, что WIQD поддерживает тот же рабочий процесс TypeSpec. Сообщения об ошибках понятны и требуют действий, помогая быстро выявлять и устранять проблемы во время разработки.
Упрощенное создание агентов и плагинов
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:
Базовый декларативный агент
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
}
Агент с возможностями
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 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;
}
Начало работы
Чтобы начать сборку с помощью TypeSpec для Microsoft 365 Copilot, см. следующие ресурсы:
-
Декораторы для TypeSpec для Microsoft 365 Copilot - справочник по декораторам Microsoft 365 Copilot, включая
@agent,@instructions@capabilitiesи многое другое. - Возможности декларативного агента в TypeSpec для Microsoft 365 Copilot — руководство по возможностям агента, таким как веб-поиск, интеграция с OneDrive, сообщения Teams и интерпретатор кода.
- Поддержка аутентификации в TypeSpec для Microsoft 365 Copilot - Шаблоны аутентификации и конфигурации безопасности для агентов и плагинов на основе TypeSpec.
- Создание декларативных агентов с помощью набора инструментов агентов Microsoft 365 и TypeSpec — пошаговое руководство по созданию декларативного агента с помощью TypeSpec и набора средств агентов.
- Создание плагинов API с помощью TypeSpec для Microsoft 365 Copilot — руководство по созданию плагинов API с операциями REST, адаптивными карточками и проверкой подлинности.
- Начните с примера (примеры, предоставленные сообществом).
См. также:
- Обзор набора средств агентов Microsoft 365 — обзор общедоступного набора средств агентов Microsoft 365.
- Языковая документация TypeSpec - Официальные языковые спецификации и руководства TypeSpec