TypeSpec for Microsoft 365 Copilot の概要

TypeSpec for Microsoft 365 Copilot は、クリーンで表現力豊かな構文を持つ宣言型エージェントと API プラグインを作成するために使用できるドメイン固有言語 (DSL) です。 TypeSpec を基盤として構築されたこの特殊な言語は、Microsoft 365 Copilot を拡張するための開発プロセスを合理化する Microsoft 365 固有のデコレーターと機能を提供します。 TypeSpec は、JSON マニフェスト ファイルを手動で作成する代わりに機能し、生産性と保守性が向上した、より開発者に優しいアプローチを提供します。

TypeSpec for Microsoft 365 Copilot は、複雑な JSON スキーマと OpenAPI ファイルに対して高レベルの抽象化レイヤーを提供します。 この言語は、必要なマニフェスト ファイルと構成を自動的に生成し、開発時間を短縮し、エラーを最小限に抑えます。 IntelliSense のサポート、型の安全性、包括的な検証により、構成の詳細ではなく、エージェントの動作に集中できます。

ヒント

Work IQ Dev Tools (プレビュー) と Microsoft 365 Agents Toolkit は、関連するプロコード ワークフローを提供します。 機能、パッケージ ルート、ターゲット エクスペリエンスに基づいて選択するには、「 プラグインの開発ツールの選択」を参照してください。

型の安全性と開発者エクスペリエンス

TypeSpec for Microsoft 365 Copilot は、実行時ではなくコンパイル時にエラーをキャッチする厳密に型指定された開発エクスペリエンスを提供します。 この言語には、すべての Microsoft 365 Copilot 固有のコンストラクトに対する包括的な型チェックが含まれており、プロビジョニング前に宣言型エージェントと API プラグインが正しく構成されていることを確認します。 この型の安全性は、基本的なメタデータから複雑な機能構成や API 操作定義まで、エージェント定義のすべての側面にまで及びます。

Visual Studio Code および Visual Studio での IntelliSense サポートにより、リアルタイムのフィードバック、オートコンプリート、およびインライン ドキュメントが提供されます。 この言語は Microsoft 365 Agents Toolkit と統合されており、作成からプロビジョニング、公開までの完全な開発ワークフローを提供します。 エラー メッセージは明確で実用的であり、開発中に問題を迅速に特定して解決するのに役立ちます。

エージェントとプラグインの作成の簡素化

TypeSpec は、冗長な JSON 構成を直感的なデコレータ ベースの構文に置き換えることで、宣言型エージェントと API プラグインを作成するプロセスを簡素化します。 複雑なマニフェスト ファイルを手動で作成する代わりに、 @agent、 @instructions、 @capabilities などのセマンティック デコレーターを使用してエージェントを定義できます。 この方法により、構成エラーの可能性が減り、コードベースの保守と読み取りが容易になります。

複雑な API サーフェスを扱う場合、従来の OpenAPI ファイルが扱いにくく管理が困難になった場合に TypeSpec が役立ちます。 何百ものエンドポイント、複雑なネストされたスキーマ、複雑な認証パターンを含む大規模なOpenAPI仕様は、作成、保守、理解が困難な場合があります。 TypeSpec は、基礎となる OpenAPI 仕様を自動的に生成する高レベルの抽象化を提供することで、これらの問題点に対処します。 TypeSpec の表現力豊かな構文を使用してビジネス ロジックと API の動作を定義することに集中し、コンパイラは OpenAPI コンプライアンス、スキーマ検証、相互参照管理の詳細を処理できます。

この言語は、Web 検索、OneDrive と SharePoint の統合、Teams メッセージ、コード インタープリターなど、すべての Microsoft 365 Copilot 機能の組み込みデコレーターを提供します。 API プラグインは、TypeSpec 操作が REST API 定義に変換される自動 OpenAPI 仕様生成の恩恵を受けます。 この自動化により、個別の API ドキュメントを維持する必要がなくなり、TypeSpec 定義と結果の API コントラクト間の一貫性が確保されます。

マニフェストの自動生成と検証

TypeSpec for Microsoft 365 Copilot は、TypeSpec 定義から有効なマニフェスト ファイルを自動的に生成します。 言語コンパイラは TypeSpec コードを分析し、宣言型エージェントと API プラグインに適切な JSON マニフェストを生成して、それらが最新のスキーマ要件に準拠していることを確認します。 この生成プロセスには包括的な検証が含まれており、一般的な構成エラーが本番環境に入る前にキャッチします。

自動生成は、基本的なマニフェストの作成を超えて、アダプティブ カード、認証設定、機能固有のメタデータなどの複雑な構成を含むまで拡張されています。 TypeSpec は、すべての参照を検証し、アダプティブ カードの適切なデータ バインディングを保証し、すべての必須プロパティが存在することを確認します。 この検証はビルド プロセス中に行われるため、フィードバックを即座に取得でき、無効な構成をプロビジョニングしません。

例

以下は、Microsoft 365 Copilot 構文の TypeSpec を示す実用的な例です:

基本的な宣言型エージェント

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 for Microsoft 365 Copilot の構築を開始するには、次のリソースを参照してください。

関連コンテンツ

  • 最終更新: