mcp-create-declarative-agent

---
mode: 'agent'
tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems']
description: 'MCP サーバーの統合、認証、ツール選択、設定により、Microsoft 365 Copilot 向けの宣言型エージェントを作成する'
model: 'gpt-4.1'
tags: [mcp, m365-copilot, declarative-agent, model-context-protocol, api-plugin]
---

# Microsoft 365 Copilot 向け MCP ベースの宣言型エージェントの作成

Model Context Protocol (MCP) サーバーと統合し、外部システムとデータにアクセスする Microsoft 365 Copilot 向けの完全な宣言型エージェントを作成します。

## 要件

Microsoft 365 Agents Toolkit を使用して、以下のプロジェクト構造を生成します：

### プロジェクト設定
1. **Agents Toolkit 経由で宣言型エージェントをスカフォルド**
2. **MCP サーバーを指す MCP アクションを追加**
3. **MCP サーバーからインポートするツールを選択**
4. **認証を設定** (OAuth 2.0 または SSO)
5. **生成されたファイルをレビュー** (manifest.json, ai-plugin.json, declarativeAgent.json)

### 生成される主要ファイル

**appPackage/manifest.json** - プラグイン参照を含む Teams アプリマニフェスト：
```json
{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
  "manifestVersion": "devPreview",
  "version": "1.0.0",
  "id": "...",
  "developer": {
    "name": "...",
    "websiteUrl": "...",
    "privacyUrl": "...",
    "termsOfUseUrl": "..."
  },
  "name": {
    "short": "Agent Name",
    "full": "Full Agent Name"
  },
  "description": {
    "short": "Short description",
    "full": "Full description"
  },
  "copilotAgents": {
    "declarativeAgents": [
      {
        "id": "declarativeAgent",
        "file": "declarativeAgent.json"
      }
    ]
  }
}
```

**appPackage/declarativeAgent.json** - エージェント定義：
```json
{
  "$schema": "https://aka.ms/json-schemas/copilot/declarative-agent/v1.0/schema.json",
  "version": "v1.0",
  "name": "Agent Name",
  "description": "Agent description",
  "instructions": "You are an assistant that helps with [specific domain]. Use the available tools to [capabilities].",
  "capabilities": [
    {
      "name": "WebSearch",
      "websites": [
        {
          "url": "https://learn.microsoft.com"
        }
      ]
    },
    {
      "name": "MCP",
      "file": "ai-plugin.json"
    }
  ]
}
```

**appPackage/ai-plugin.json** - MCP プラグインマニフェスト：
```json
{
  "schema_version": "v2.1",
  "name_for_human": "Service Name",
  "description_for_human": "Description for users",
  "description_for_model": "Description for AI model",
  "contact_email": "support@company.com",
  "namespace": "serviceName",
  "capabilities": {
    "conversation_starters": [
      {
        "text": "Example query 1"
      }
    ]
  },
  "functions": [
    {
      "name": "functionName",
      "description": "Function description",
      "capabilities": {
        "response_semantics": {
          "data_path": "$",
          "properties": {
            "title": "$.title",
            "subtitle": "$.description"
          }
        }
      }
    }
  ],
  "runtimes": [
    {
      "type": "MCP",
      "spec": {
        "url": "https://api.service.com/mcp/"
      },
      "run_for_functions": ["functionName"],
      "auth": {
        "type": "OAuthPluginVault",
        "reference_id": "${{OAUTH_REFERENCE_ID}}"
      }
    }
  ]
}
```

**/.vscode/mcp.json** - MCP サーバー設定：
```json
{
  "serverUrl": "https://api.service.com/mcp/",
  "pluginFilePath": "appPackage/ai-plugin.json"
}
```

## MCP サーバー統合

### サポート対象の MCP エンドポイント
MCP サーバーは以下を提供する必要があります：
- **サーバーメタデータ** エンドポイント
- **ツールリスト** エンドポイント (利用可能な機能を公開)
- **ツール実行** エンドポイント (関数呼び出しを処理)

### ツール選択
MCP からインポートする場合：
1. サーバーから利用可能なツールを取得
2. 含めるべき特定のツールを選択 (セキュリティ/シンプルさのため)
3. ツール定義は ai-plugin.json で自動生成

### 認証タイプ

**OAuth 2.0 (静的登録)**
```json
"auth": {
  "type": "OAuthPluginVault",
  "reference_id": "${{OAUTH_REFERENCE_ID}}",
  "authorization_url": "https://auth.service.com/authorize",
  "client_id": "${{CLIENT_ID}}",
  "client_secret": "${{CLIENT_SECRET}}",
  "scope": "read write"
}
```

**シングルサインオン (SSO)**
```json
"auth": {
  "type": "SSO"
}
```

## レスポンスセマンティクス

### データマッピングを定義
`response_semantics` を使用して API レスポンスから関連フィールドを抽出します：

```json
"capabilities": {
  "response_semantics": {
    "data_path": "$.results",
    "properties": {
      "title": "$.name",
      "subtitle": "$.description",
      "url": "$.link"
    }
  }
}
```

### Adaptive Cards を追加 (オプション)
ビジュアルカードテンプレートを追加するには、`mcp-create-adaptive-cards` プロンプトを参照してください。

## 環境設定

認証情報用に `.env.local` または `.env.dev` を作成します：

```env
OAUTH_REFERENCE_ID=your-oauth-reference-id
CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret
```

## テストと展開

### ローカルテスト
1. **Agents Toolkit でエージェントをプロビジョニング**
2. **デバッグを開始** して Teams にサイドロード
3. https://m365.cloud.microsoft/chat で Microsoft 365 Copilot でテスト
4. プロンプトが表示されたら認証
5. 自然言語を使用してエージェントにクエリを実行

### 検証
- ai-plugin.json でのツールインポートを確認
- 認証設定を確認
- 公開された各機能をテスト
- レスポンスデータマッピングを検証

## ベストプラクティス

### ツール設計
- **集中した関数**: 各ツールは 1 つのことを得意とすべき
- **明確な説明**: モデルが各ツールを使用すべき時を理解するのを支援
- **最小スコープ**: エージェントが必要とするツールのみをインポート
- **説明的な名前**: アクション指向の関数名を使用

### セキュリティ
- **本番環境では OAuth 2.0 を使用**
- **環境変数にシークレットを保存**
- **MCP サーバー側でインプットを検証**
- **必要な最小限の権限にスコープを制限**
- **OAuth 登録に参照 ID を使用**

### 指示
- **エージェントの目的と機能について具体的に記述**
- **成功時とエラー時の両方の動作を定義**
- **該当する場合は指示でツールを明示的に参照**
- **ユーザーに対しエージェントが何ができるか/できないかについての期待値を設定**

### パフォーマンス
- **必要に応じて MCP サーバー側でレスポンスをキャッシュ**
- **可能な場合は操作をバッチ処理**
- **長時間実行される操作のタイムアウトを設定**
- **大規模データセットの結果をページネーション**

## MCP サーバーの一般的な例

### GitHub MCP サーバー
```
URL: https://api.githubcopilot.com/mcp/
Tools: search_repositories, search_users, get_repository
Auth: OAuth 2.0
```

### Jira MCP サーバー
```
URL: https://your-domain.atlassian.net/mcp/
Tools: search_issues, create_issue, update_issue
Auth: OAuth 2.0
```

### カスタムサービス
```
URL: https://api.your-service.com/mcp/
Tools: サービスが公開するカスタムツール
Auth: OAuth 2.0 または SSO
```

## ワークフロー

ユーザーに以下を質問します：
1. どの MCP サーバーを統合していますか (URL)？
2. Copilot に公開すべきツールは何ですか？
3. サーバーがサポートしている認証方法は何ですか？
4. エージェントの主要な目的は何ですか？
5. レスポンスセマンティクスまたは Adaptive Cards が必要ですか？

その後、以下を生成します：
- 完全な appPackage/ 構造 (manifest.json, declarativeAgent.json, ai-plugin.json)
- mcp.json 設定
- .env.local テンプレート
- プロビジョニングとテスト手順

## トラブルシューティング

### MCP サーバーが応答しない
- サーバー URL が正しいことを確認
- ネットワーク接続を確認
- MCP サーバーが必要なエンドポイントを実装していることを確認

### 認証に失敗
- OAuth 認証情報が正しいことを確認
- 参照 ID が登録と一致することを確認
- スコープが正しくリクエストされていることを確認
- OAuth フローを独立してテスト

### ツールが表示されない
- mcp.json が正しいサーバーを指していることを確認
- インポート時にツールが選択されたことを確認
- ai-plugin.json に正しい関数定義があることを確認
- サーバーが変更された場合はアクションを再取得

### エージェントがクエリを理解しない
- declarativeAgent.json の指示をレビュー
- 関数の説明が明確であることを確認
- response_semantics が正しいデータを抽出していることを確認
- より具体的なクエリでテスト