SharePoint

SharePoint サイトのドキュメントを、Squid AI agent 向けの検索可能なナレッジとしてインデックス化

SharePoint connector の機能

SharePoint connector は、組織の SharePoint ドキュメント ライブラリからドキュメントをナレッジベースに読み込み、Squid AI agent がそのコンテンツを使用して質問に回答できるようにします。

• インデックス化するドキュメントまたはフォルダを選択できます。フォルダをインデックス化すると、その中のすべてのファイルが再帰的にインデックス化されます。
• Squid はインデックス化されたコンテンツを自動的に同期し、変更、追加、削除されたファイルを 10 分ごとに取り込みます。
• SharePoint connector に接続された AI agent は、インデックス化されたコンテンツをセマンティック検索し、インデックス化されたドキュメントを一覧表示できます。
• Squid は SharePoint 独自の権限を尊重できるため、agent は会話中のユーザーが SharePoint で開けるドキュメントのみを取得します。ソース権限の尊重を参照してください。
• アクセスは読み取り専用です。Squid が SharePoint サイトに書き込むことはありません。

Microsoft Entra app registration の作成

connector は、application permissions を持つ app registration を使用して認証します（ユーザーごとのサインインは不要です）。

1. Azure Portal で、App registrations に移動し、New registration をクリックします。

2. 作成後、Overview タブから Application (client) ID と Directory (tenant) ID を控えます。

3. Certificates & secrets で新しい client secret を作成し、その値を保存します。Client secret には有効期限があります（デフォルトでは 6 か月、最長 24 か月）。secret の期限が切れると、同期は通知なく停止します。追跡可能な有効期限を選択し、それまでに Squid Console で connector を新しい secret に更新してください。

4. API permissions で、サイトとファイルへの読み取りアクセスを付与する Microsoft Graph のapplication permissions（Sites.Read.All と Files.Read.All）を追加し、admin consent を付与します。agent に SharePoint の権限を尊重させるには、各ドキュメントの共有先を Squid が解決できるよう、ディレクトリのユーザーとグループへの読み取りアクセスも app registration に付与してください。

Squid application への SharePoint connector の追加

1. Squid Console の Connectors タブに移動します。

2. Available Connectors をクリックします。

3. SharePoint connector を見つけ、Add Connector を選択します。

4. 次の設定詳細を指定します。

Connector ID: コード内で connector を一意に識別する文字列です。後から変更することはできません。

Client ID: app registration の Application (client) ID。

Tenant ID: app registration の Directory (tenant) ID。

Client Secret: 作成した client secret。これは Squid secret として安全に保存されます。

ドキュメントのインデックス化

ドキュメントは @squidcloud/sharepoint-client package を使用してプログラムでインデックス化します。ドキュメントまたはフォルダは、SharePoint の site ID、drive ID、item ID で指定します。

npm install @squidcloud/sharepoint-client

import { SharePointClient, encodeSharePointLocation } from '@squidcloud/sharepoint-client';

const sharepoint = new SharePointClient(squid, 'SHAREPOINT_CONNECTOR_ID');

// ドキュメントまたはフォルダ全体をインデックス化（再帰的）
const errors = await sharepoint.indexDocumentOrFolder({
  siteId: 'SITE_ID',
  driveId: 'DRIVE_ID',
  itemId: 'ITEM_ID',
});

// インデックス化されたすべての項目を一覧表示
const documents = await sharepoint.listIndexedDocuments();

// 一覧表示された ID により、ドキュメントまたはフォルダをインデックスから削除
await sharepoint.unindexDocumentOrFolder(documents[0].id);

// ...または、その場所をエンコードして直接指定
await sharepoint.unindexDocumentOrFolder(encodeSharePointLocation('SITE_ID', 'DRIVE_ID', 'ITEM_ID'));

インデックス化後、ドキュメントはバックグラウンド同期により自動的に最新の状態に保たれます。

インデックス化ステータスの確認

ドキュメントまたはフォルダをインデックス化した後、各ファイルがインデックス化されたか、まだ待機中か、失敗したか、スキップされたかを確認できます。Squid client で squid.admin().integrations().getPathStatus() を呼び出します。この呼び出しには API key で認証された Squid instance が必要なため、this.squid がすでに認証されている backend code から実行してください。frontend にステータスを表示するには、呼び出しを executable でラップして client から呼び出し、API key が browser に渡らないようにします。

Backend

Backend code

import { executable, SquidService } from '@squidcloud/backend';
import { ConnectorPathStatusResult } from '@squidcloud/client';

export class SharePointStatusService extends SquidService {
  @executable()
  async checkSharePointPath(path: string): Promise<ConnectorPathStatusResult> {
    // this.squid は application の API key で認証されています
    return await this.squid.admin().integrations().getPathStatus('SHAREPOINT_CONNECTOR_ID', path);
  }
}

client から executable を呼び出す前に、backend を deploy または起動してください。手順については Executables を参照してください。

Frontend

Client code

import type { ConnectorPathStatusResult } from '@squidcloud/client';

// `squid` は初期化済みの Squid client です
const result: ConnectorPathStatusResult = await squid.executeFunction('checkSharePointPath', 'Reports');

// ほとんどの connector type は path status をサポートしていません。これはエラーではありません。
if (!result.supported) {
  console.log('This connector does not support path status');
} else {
  for (const entry of result.entries ?? []) {
    console.log(entry.name, entry.classification, entry.errorMessage ?? '');
  }

  if (result.truncated) {
    console.log('More matches exist. Search a more specific path to narrow the results.');
  }
}

Frontend から直接呼び出す（非推奨）

getPathStatus() は client SDK method のため、executable を記述せずに呼び出せます。この呼び出しには API key が必要であるため、application の API key を使用して client を初期化する必要があります。

警告

これは user-facing application には推奨されません。API key は Squid application への完全なアクセスを付与し、browser や mobile app に含めた key はユーザーに抽出される可能性があります。internal admin tool や script などの信頼できる環境でのみ使用し、それ以外のすべてのケースでは上記の executable approach を使用してください。

Client code

import { Squid } from '@squidcloud/client';

// API key は application への完全なアクセスを付与します。エンドユーザーに絶対に配布しないでください。
const squid = new Squid({
  appId: 'YOUR_APP_ID',
  region: 'YOUR_REGION', // 例: 'us-east-1.aws'
  environmentId: 'dev',
  squidDeveloperId: 'YOUR_SQUID_DEVELOPER_ID', // non-prod environment でのみ必要
  apiKey: 'YOUR_API_KEY',
});

const result = await squid.admin().integrations().getPathStatus('SHAREPOINT_CONNECTOR_ID', 'Reports');

if (!result.supported) {
  console.log('This connector does not support path status');
} else {
  for (const entry of result.entries ?? []) {
    console.log(entry.name, entry.classification, entry.errorMessage ?? '');
  }
}

client が API key で認証されていない場合、呼び出しは失敗します。

path には、フォルダ（そのフォルダ、そのファイル、および配下にネストされたすべてに一致）、ファイル名、または Reports/good.txt のようなフルパスを指定できます。先頭および末尾のスラッシュは無視されます。Reports という名前のフォルダは、兄弟フォルダの Reports-old には一致しません。

結果

getPathStatus(integrationId, path) は ConnectorPathStatusResult を返します。

フィールド	型	説明
supported	boolean	connector type が path status をサポートしない場合は false。
knowledgeBaseId	string（optional）	判断可能な場合に、この connector がインデックス化するナレッジベース。
entries	ConnectorPathStatusEntry[]	一致するファイルとフォルダ。supported が false の場合は存在しません。
truncated	boolean（optional）	entries で返される 50 件より多くの一致がある場合は true。

各 entry には以下のフィールドがあります。

フィールド	型	説明
documentId	string	ドキュメントに対する connector の ID。
name	string	ファイルまたはフォルダ名。
type	'file' | 'folder'	entry がファイルかフォルダかを示します。
folderPath	string（optional）	ドキュメントがインデックス化された経由のフォルダ。
classification	string	下表のいずれかの値。
errorMessage	string（optional）	failed および skipped entry に対する、直近の失敗メッセージ。
lastIndexedDate	Date（optional）	ドキュメントが最後に正常にインデックス化された日時。
contextId	string（optional）	ファイルのナレッジベース context ID。
kbStatus	object（optional）	ファイルに対するナレッジベース独自のステータス: status（no_record、in_progress、completed、または failed）に加え、optional の errorMessage、errorCode、updatedAt。

Classification	意味
indexed	ファイルはインデックス化されています。
staged	ファイルはインデックス化待ちです。
failed	ファイルのインデックス化に失敗しました。errorMessage を確認してください。
skipped	たとえばファイルが大きすぎる、または type がサポートされていないため、意図的に除外されました。
folder_tracked	entry はフォルダです。フォルダ自体にはインデックス化ステータスはありません。

エラー

• integration ID が既存の connector に一致しない場合、getPathStatus() は Integration not found を throw します。
• Squid instance が API key で認証されていない場合、呼び出しは失敗します。
• 単一ファイルのナレッジベース status を取得できない場合、その entry の kbStatus は undefined のままとなり、ほかの entry は引き続き返されます。

AI agent での SharePoint connector の使用

No-code Studio

1. Squid Console の Studio タブに移動します。

2. Create AI Agent をクリックします。

3. agent ID と説明を指定します。たとえば、"docs-agent" と "This agent answers questions using our SharePoint documents" のように設定します。

4. Add Abilities をクリックし、Storage セクションまでスクロールして、先ほど作成した SharePoint connector を選択します。

5. agent がこの connection をどのように使用するかの説明を入力します。たとえば、"Call this when a user asks about content stored in SharePoint." とします。

6. Test をクリックし、インデックス化したドキュメントに関する質問を agent にしてみてください。

Squid SDK の使用

Squid SDK で AI agent を作成する場合は、ask() function の connectedIntegrations option に SharePoint connector を追加して接続します。

TypeScript

await this.squid
  .ai()
  .agent('AGENT_ID')
  .ask('What does our expense policy say about travel?', {
    connectedIntegrations: [
      {
        integrationId: 'SHAREPOINT_CONNECTOR_ID',
        integrationType: 'sharepoint',
        description: 'Call this connector to search our SharePoint documents',
      },
    ],
  });

Python

await squid.ai().agent('AGENT_ID').ask(
    'What does our expense policy say about travel?',
    options={
        'connectedIntegrations': [
            {
                'integrationId': 'SHAREPOINT_CONNECTOR_ID',
                'integrationType': 'sharepoint',
                'description': 'Call this connector to search our SharePoint documents',
            }
        ]
    },
)