m365-agents-ts

補足資料の入手可能性

このカタログのコピーには、以下のインラインガイダンスが含まれていますが、次の補足資料のパスは含まれていません。これらは外部の前提条件であり、同梱ファイルではありません。

• <support-root>/references/acceptance-criteria.md

これらのパスに依存する手順を実行する前に、元の補足資料または既存のインストールを入手してください。このカタログには、確認済みのダウンロード元が記載されていません。各パスをそのインストールを基準に解決し、内容を確認して、該当するライセンスと実行要件を検証してください。必要なファイルが存在することを確認するまでは、コマンドを実行したり、参照先の手順に従ったと主張したりしないでください。不足しているスクリプトを捏造したり、同じ名前の無関係なファイルを同等のものとして扱ったりしないでください。ここに完全に記載されている独立した手順は、ユーザーが許可した範囲内で進められます。依存する手順は利用不可として報告してください。

Microsoft 365 Agents SDK (TypeScript)

Express ホスティング、AgentApplication によるルーティング、ストリーミング応答、Copilot Studio クライアント統合を備えた Microsoft 365 Agents SDK を使用して、Microsoft 365、Teams、Copilot Studio 向けのエンタープライズエージェントを構築します。

実装の前に

• microsoft-docs MCP を使用して、AgentApplication、startServer、CopilotStudioClient の最新の API シグネチャを確認してください。
• サンプルやテンプレートを組み込む前に、npm でパッケージのバージョンを確認してください。

インストール

npm install @microsoft/agents-hosting @microsoft/agents-hosting-express @microsoft/agents-activity
npm install @microsoft/agents-copilotstudio-client

環境変数

PORT=3978
AZURE_RESOURCE_NAME=<azure-openai-resource>
AZURE_API_KEY=<azure-openai-key>
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o-mini

TENANT_ID=<tenant-id>
CLIENT_ID=<client-id>
CLIENT_SECRET=<client-secret>

COPILOT_ENVIRONMENT_ID=<environment-id>
COPILOT_SCHEMA_NAME=<schema-name>
COPILOT_CLIENT_ID=<copilot-app-client-id>
COPILOT_BEARER_TOKEN=<copilot-jwt>

コアワークフロー：Express でホストする AgentApplication

import { AgentApplication, TurnContext, TurnState } from "@microsoft/agents-hosting";
import { startServer } from "@microsoft/agents-hosting-express";

const agent = new AgentApplication<TurnState>();

agent.onConversationUpdate("membersAdded", async (context: TurnContext) => {
  await context.sendActivity("Welcome to the agent.");
});

agent.onMessage("hello", async (context: TurnContext) => {
  await context.sendActivity(`Echo: ${context.activity.text}`);
});

startServer(agent);

Azure OpenAI を使用したストリーミング応答

import { azure } from "@ai-sdk/azure";
import { AgentApplication, TurnContext, TurnState } from "@microsoft/agents-hosting";
import { startServer } from "@microsoft/agents-hosting-express";
import { streamText } from "ai";

const agent = new AgentApplication<TurnState>();

agent.onMessage("poem", async (context: TurnContext) => {
  context.streamingResponse.setFeedbackLoop(true);
  context.streamingResponse.setGeneratedByAILabel(true);
  context.streamingResponse.setSensitivityLabel({
    type: "https://schema.org/Message",
    "@type": "CreativeWork",
    name: "Internal",
  });

  await context.streamingResponse.queueInformativeUpdate("starting a poem...");

  const { fullStream } = streamText({
    model: azure(process.env.AZURE_OPENAI_DEPLOYMENT_NAME || "gpt-4o-mini"),
    system: "You are a creative assistant.",
    prompt: "Write a poem about Apollo.",
  });

  try {
    for await (const part of fullStream) {
      if (part.type === "text-delta" && part.text.length > 0) {
        await context.streamingResponse.queueTextChunk(part.text);
      }
      if (part.type === "error") {
        throw new Error(`Streaming error: ${part.error}`);
      }
    }
  } finally {
    await context.streamingResponse.endStream();
  }
});

startServer(agent);

Invoke アクティビティの処理

import { Activity, ActivityTypes } from "@microsoft/agents-activity";
import { AgentApplication, TurnContext, TurnState } from "@microsoft/agents-hosting";

const agent = new AgentApplication<TurnState>();

agent.onActivity("invoke", async (context: TurnContext) => {
  const invokeResponse = Activity.fromObject({
    type: ActivityTypes.InvokeResponse,
    value: { status: 200 },
  });

  await context.sendActivity(invokeResponse);
  await context.sendActivity("Thanks for submitting your feedback.");
});

Copilot Studio クライアント（エンジンに直接接続）

import { CopilotStudioClient } from "@microsoft/agents-copilotstudio-client";

const settings = {
  environmentId: process.env.COPILOT_ENVIRONMENT_ID!,
  schemaName: process.env.COPILOT_SCHEMA_NAME!,
  clientId: process.env.COPILOT_CLIENT_ID!,
};

const tokenProvider = async (): Promise<string> => {
  return process.env.COPILOT_BEARER_TOKEN!;
};

const client = new CopilotStudioClient(settings, tokenProvider);

const conversation = await client.startConversationAsync();
const reply = await client.askQuestionAsync("Hello!", conversation.id);
console.log(reply);

Copilot Studio WebChat の統合

import { CopilotStudioWebChat } from "@microsoft/agents-copilotstudio-client";

const directLine = CopilotStudioWebChat.createConnection(client, {
  showTyping: true,
});

window.WebChat.renderWebChat({
  directLine,
}, document.getElementById("webchat")!);

ベストプラクティス

1. ルーティングには AgentApplication を使用し、ハンドラーの役割を一つに絞ってください。
2. 実行時間の長い完了処理には streamingResponse を優先し、finally ブロック内で endStream を呼び出してください。
3. シークレットをソースコードに含めず、環境変数またはセキュアストアからトークンを読み込んでください。
4. CopilotStudioClient インスタンスを再利用し、トークンプロバイダーでトークンをキャッシュしてください。
5. フィードバックをログに記録または永続化する前に、invoke ペイロードを検証してください。

参照ファイル

ファイル	内容
references/acceptance-criteria.md	インポートパス、ホスティングパイプライン、ストリーミング、Copilot Studio のパターン

参照リンク

リソース	URL
Microsoft 365 Agents SDK	https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/
JavaScript SDK の概要	https://learn.microsoft.com/en-us/javascript/api/overview/agents-overview?view=agents-sdk-js-latest
@microsoft/agents-hosting-express	https://learn.microsoft.com/en-us/javascript/api/%40microsoft/agents-hosting-express?view=agents-sdk-js-latest
@microsoft/agents-copilotstudio-client	https://learn.microsoft.com/en-us/javascript/api/%40microsoft/agents-copilotstudio-client?view=agents-sdk-js-latest
Copilot Studio との統合	https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/integrate-with-mcs
GitHub のサンプル	https://github.com/microsoft/Agents/tree/main/samples/nodejs

使用する場面

このスキルは、概要に記載されたワークフローまたはアクションを実行する場合に適用できます。

制限事項

• タスクが上記の説明にある範囲に明確に該当する場合に限り、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。