Microsoft 365 Copilot の TypeSpec エージェント シナリオ

ヒント

推奨事項: サポートされているプロコード宣言型エージェントとプラグイン シナリオ用の Work IQ 開発ツール から始めます。 WIQD クイックスタートを参照してください。 Toolkit ベースの手順は、それらを必要とする既存のプロジェクトおよびワークフローで引き続き使用できます。 ツールを選択する前に 、機能とターゲット エクスペリエンスのサポート を確認します。WIQD はカスタム エンジン エージェントを対象としません。

このガイドでは、単純な基本エージェントから、複数の機能と認証方法を含む複雑な実装まで、Microsoft 365 Copilot 用の TypeSpec エージェントを作成する完全な例を示します。

機能を持たない基本エージェント

ユースケース: 外部統合や特別な機能を使用せずに、基本的な情報とあいさつを提供するシンプルなエージェント。

機能: このエージェントは、簡単な質問に答え、一般的な情報を提供し、基本的な会話を行うことができます。 外部 API へのアクセス、Web の検索、または Microsoft 365 データへのアクセスは必要ありません。

import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;

@agent("Basic Helper Agent", "A simple agent that provides basic information and assistance")
@instructions("""
  You are a helpful assistant that provides basic information and support.
  Be friendly, professional, and helpful in all interactions. Provide clear,
  concise answers to user questions. If you don't know something, be honest
  about your limitations and suggest alternative ways to find the information.
""")
namespace BasicHelperAgent {
  // No capabilities defined - agent relies only on built-in conversational abilities
}

複数の機能を持つエージェント

ユースケース: Web で情報を検索したり、organization の SharePoint コンテンツにアクセスしたり、organization 内の同僚に関する情報を検索したりできるナレッジ ワーカー アシスタント。

機能: このエージェントは、外部情報の Web 検索、ドキュメント検索のためのファイル アクセス、同僚とその連絡先情報を見つけるためのユーザー検索を組み合わせることで、ナレッジ ワーカーを支援します。 このパターンは、研究とコラボレーションのシナリオに適しています。

import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;

@agent("Knowledge Worker Assistant", "An intelligent assistant that helps with research, file management, and finding colleagues")
@instructions("""
  You are a knowledgeable research assistant specialized in helping knowledge workers
  find information efficiently. You can search the web for external research, access
  SharePoint documents for organizational content, and help locate colleagues within
  the organization. Always provide comprehensive research results, cite your sources,
  and suggest additional resources when relevant. When searching for people, respect
  privacy and only share publicly available organizational information.
""")
namespace KnowledgeWorkerAgent {
  // Web search capability for external research
  op webSearch is AgentCapabilities.WebSearch<Sites = [
    {
      url: "https://learn.microsoft.com";
    },
    {
      url: "https://www.microsoft.com";
    }
  ]>;

  // OneDrive and SharePoint access for document retrieval
  op oneDriveAndSharePoint is AgentCapabilities.OneDriveAndSharePoint<
    ItemsByUrl = [
      { url: "https://contoso.sharepoint.com/sites/IT" }
    ]
  >;

  // People search for finding colleagues
  op people is AgentCapabilities.People;
}

匿名 API アクションを使用するシンプルなエージェント

ユースケース: ユーザーが公共修理 API を使用してメンテナンスの問題を報告および追跡するのに役立つファシリティ管理エージェント。

機能: このエージェントを使用すると、ユーザーは施設の問題 (機器の破損、照明の問題など) を報告し、既存の修理要求のステータスをチェックできます。 修復 API は一般公開されており、認証を必要としないため、誰でも簡単に問題を報告できます。

import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";
import "./actions.tsp";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;
using TypeSpec.M365.Copilot.Actions;

@agent("Facilities Repair Agent", "Report and track facility maintenance issues and repair requests")
@instructions("""
  You are a facilities management assistant that helps employees report and track
  maintenance issues. You can help users submit new repair requests by gathering
  all necessary details (description, location, category, priority) and submit
  them to the facilities team. You can also check the status of existing repair
  tickets and provide updates on progress. Always be helpful in categorizing
  issues correctly and setting appropriate priority levels based on safety and
  business impact.
""")
namespace FacilitiesRepairAgent {
  op reportIssue is RepairsAPI.reportIssue;
  op getRepairStatus is RepairsAPI.getRepairStatus;
  op getOpenRepairs is RepairsAPI.getOpenRepairs;
}

API キー認証を使用した高度なエージェント

ユース ケース: API キー認証を使用して公開されている API を使用して、チームが施設のメンテナンス タスクを追跡および管理するのに役立つ修理管理エージェント。

機能: このエージェントは、メンテナンス チームに包括的な修復管理機能を提供します。 修理タスクの一覧表示、作成、更新、削除、担当者または説明による修理のフィルター処理、画像付きの豊富なカードベースの応答の提供を行うことができます。 API キー認証により、実際の API 統合パターンを示しながら、修理管理システムへのアクセスの制御が保証されます。

import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";
import "./actions.tsp";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;
using TypeSpec.M365.Copilot.Actions;

@agent("Repairs Hub Agent", "Smart repair management agent for tracking and coordinating facility maintenance tasks")
@instructions("""
  You are a specialized repairs management assistant that helps teams efficiently track,
  organize, and coordinate facility maintenance tasks. You excel at managing repair
  workflows including creating detailed repair tickets, assigning tasks to team members,
  tracking progress, and providing status updates. You can filter repairs by various
  criteria such as assignee, keywords in descriptions, or completion status. Always
  provide clear, organized information using tables and cards when displaying repair
  data. When creating repairs, gather all necessary details and confirm the information
  before submission. Help prioritize urgent repairs and ensure proper task assignment
  for optimal team productivity.
""")
@conversationStarter(#{
  title: "List repairs",
  text: "List all repairs"
})
@conversationStarter(#{
  title: "List Karin's repairs",
  text: "List all repairs assigned to Karin"
})
@conversationStarter(#{
  title: "Find oil repairs",
  text: "List all repairs that are about oil"
})
@conversationStarter(#{
  title: "Create repair",
  text: "Create a new repair and assign it to me"
})
namespace RepairsAgent {
  // Repair management operations
  op listRepairs is RepairsHub.listRepairs;
  op createRepair is RepairsHub.createRepair;
  op updateRepair is RepairsHub.updateRepair;
  op deleteRepair is RepairsHub.deleteRepair;
}

OAuth2 と GitHub API が統合された複雑なエージェント

ユースケース: 開発チームが GitHub リポジトリを管理し、問題を追跡し、プルリクエストを管理し、GitHub の包括的な API を使用してプロジェクト アクティビティを調整するのに役立つプロジェクト管理エージェント。

機能: このエージェントは、GitHub と統合するプロジェクト管理アシスタントとして機能し、開発チームがワークフローを合理化するのに役立ちます。 問題の作成と管理、プル リクエストのレビューとマージ、プロジェクトのマイルストーンの追跡、リポジトリ アクティビティに関する分析情報の提供を行うことができます。 OAuth2認証により、適切な権限でGitHubリポジトリへの安全なアクセスが保証され、チームは自然言語の対話を通じてプロジェクトを効率的に管理できます。

import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";
import "./actions.tsp";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;
using TypeSpec.M365.Copilot.Actions;

@agent("GitHub Project Manager", "Smart project management agent with GitHub integration for issue tracking, pull request management, and project coordination")
@instructions("""
  You are an intelligent project management assistant specialized in GitHub workflows
  and development team coordination. You excel at managing GitHub repositories including
  creating and tracking issues, reviewing pull requests, coordinating project milestones,
  and providing insights about development activity. You can help prioritize work,
  track progress, manage code reviews, and facilitate team collaboration through GitHub's
  project management features. Always consider development best practices, help maintain
  code quality through proper review processes, and provide actionable insights to
  improve team productivity and project delivery.
""")
namespace GitHubProjectManager {
  // GitHub API operations for project management
  op createIssue is GitHubAPI.createIssue;
  op getIssues is GitHubAPI.getIssues;
  op updateIssue is GitHubAPI.updateIssue;
  op getPullRequests is GitHubAPI.getPullRequests;
  op createPullRequest is GitHubAPI.createPullRequest;
  op mergePullRequest is GitHubAPI.mergePullRequest;
  op getProjectInsights is GitHubAPI.getProjectInsights;
}

概要

これらの例は、単純な TypeSpec エージェントから複雑な TypeSpec エージェントへの遷移を示しています。

各例は前の例に基づいており、機能、認証、カスタム アクションを追加して、実際のシナリオでより複雑なエージェントを作成する方法を示しています。