RAG エージェントの実装

ドキュメントをAIエージェントの知識ベースに統合し、その後データに基づいてアクションを実行する

作成するもの

製品マニュアルをコンテキストとして使用し、家電製品に関する質問に回答するとともに、リクエストに応じてメンテナンスタスクのリストを作成するAIエージェントを搭載したアプリ

このチュートリアルでは次の機能を使用します:

AI Abilities	Internal Connectors	Backend Functions
Knowledge base	Built-in Database	Webhooks

このチュートリアルにご協力いただいたパートナーの Otairo に大感謝！

環境のセットアップ

In the Squid Console, switch to the dev environment.

switch environment

Download the ai-home-maintenance code sample using the following command. Replace the placeholders with the values from your Squid application as shown in the console.

npx @squidcloud/cli init-sample ai-home-maintenance --template ai-home-maintenance --appId YOUR_SQUID_APP_ID --apiKey YOUR_SQUID_API_KEY --environmentId dev --squidDeveloperId YOUR_SQUID_DEVELOPER_ID --region YOUR_REGION

TIP

You can find your environment variables under: 'Application' -> 'Show env vars' as seen below:

switch environment

Open the project in the IDE of your choice.
Start the app locally by running the following command in the project folder:

npm run start

To view the app, navigate to localhost:PORT, where PORT is logged in the terminal. The address will likely be http://localhost:5173.

NOTE

アプリケーションは正常に起動しますが、次のステップを完了するまでは完全な機能は発揮されません。

AIエージェントの追加

各エージェントは異なるペルソナやユースケースを表しており、それぞれ独自の指示や能力が設定されています。

Squid Consoleで、Agent Studioタブに移動します。
Create New Agentをクリックしてエージェントを追加します。以下の詳細を入力してください:
- Agent ID: maintenance-scheduler
- Description: This is an agent for Squid AI's home maintenance tutorial (これは Squid AI のホームメンテナンス・チュートリアル用のエージェントです)
エージェントを作成するには Create をクリックします。
Instructionsフィールドに、以下の指示をエージェントに追加します:

Respond to queries about home maintenance documents. Only use the provided context to generate responses. Never respond based on your general knowledge. When applicable, list the source document used. If a question cannot be answered using the provided context, state that clearly and do not attempt to answer using general knowledge.

これらの指示は、AIエージェントにどのアクションを実行するかを伝えます。

次に、Agent Settingsタブに移動します。Set Agent to Publicまでスクロールし、この設定をオンに切り替えます。
これにより、セキュリティルールを記述せずにエージェントに公開アクセスが可能になります。

IMPORTANT

本番環境にデプロイする前に、適切なセキュリティルールが設定されていることを確認し、Publicアクセスが有効な状態でエージェントを実行しないでください。エージェントのセキュリティ確保については this reference を参照してください。

バックグラウンド知識の追加

知識ベース機能は、質問に回答する際にエージェントにコンテキストを提供します。コンテキストを追加することで、基盤となるAIモデルに含まれていない特定のトピックに対しても、関連性のある回答を提供できるようになります。

以下の家電製品マニュアルをPDFファイルとしてダウンロードします:

Oven:

https://media3.bosch-home.com/Documents/8001203758_A.pdf

Microwave:

https://media3.bosch-home.com/Documents/9001152447_B.pdf

Dishwasher:

https://media3.bosch-home.com/Documents/9001641455_A.pdf

Washer/dryer:

https://products-salsify.geappliances.com/image/upload/s--pdIsKW0u--/izid0w85hg3mbckeyyo1.pdf

また、オンラインでご自分の家電のマニュアルを検索し、コンテキストとして提供することも可能です。これにより、それらに関する質問をすることができます。

Add Abilitiesをクリックし、Knowledge Baseの下にあるFile能力を選択します。
4つのファイルそれぞれをアップロードします。アップロードには時間がかかる場合があります。エージェントは自動的にドキュメントから内容を抽出し、知識ベースにテキストを追加します。

Squidアプリケーションの探索

プロジェクトのルートディレクトリで次のコマンドを実行して、両方のサーバーを起動します:

npm run start

両方のサーバーが起動している状態で、ウェブブラウザから http://localhost:5173/ にアクセスしてください。これで、Squidアプリケーションの機能を探索する準備が整いました:

家電製品に関する質問を試してみてください。例として、次のように質問できます:

How do I clean my cooktop?

AIエージェントは、マニュアルから取得した詳細情報をチャットで回答します。

AIエージェントに家電製品のメンテナンスのためのタスクリストを作成するよう指示します:

Create a list of maintenance tasks.

しばらくすると、新しいタスクがアプリケーションの右側にリストとして表示されます。これは、AIエージェントがマニュアルをコンテキストとして利用し、メンテナンスタスクを作成した後、ご自身に代わってデータベースにタスクを書き込んだことを意味します。

いくつかのタスクを完了した後は、SquidのQuery with AI機能を使用してさらなる質問が可能です。この機能は、データベーススキーマの知識を活用して、プロンプトに基づいたクエリを生成します。

アプリの自動検出されたスキーマを保存するには、Squid Consoleにアクセスし、Connectorsタブに移動します。その後、built_in_db上の ... ボタンをクリックしてドロップダウンメニューを開き、Schema を選択してください。
Save Schemaをクリックして、アプリの自動検出されたスキーマを保存します。
いくつかのタスクにチェックを入れて完了済みとしてマークした後、AIエージェントに次の質問をしてみてください:

Which maintenance tasks have I completed?

AIエージェントはデータベースをクエリして、どの項目が完了しているかを確認できます。これは、AIエージェントがリアルタイムでデータベースクエリを生成できることを意味します！

AIエージェントは、より複雑な指示を認識し、対応することができます。例えば、次のようにAIエージェントに指示してみてください:

Look up in the manual to determine how often I should clean my washer-dryer lint filter. Based on that interval, if I run two loads of laundry a day, how often should I clean the filter?

AIエージェントは、洗濯乾燥機のlint filterをどの頻度で掃除すべきかを判断し、その間隔に基づいて質問に論理的な回答を返すことができます。

コードの確認

Squidを活用したAIエージェントによるフルスタックアプリの構築に成功しました！内部で何が起こっているのかご興味ありますか？このセクションではコードの詳細を見ていきます。

フロントエンドでのAIエージェントの設定

Squid React SDKのuseAiChatフックを使用して、以下のコードでAIエージェントに接続できます:

frontend/src/App.tsx
const { history, chat, complete } = useAiChat('maintenance-scheduler');

AIエージェントへの機能追加

Squid AIエージェントは、プロンプトに応じて異なるアクションを実行できます。これは、Squidバックエンドで@aiFunctionデコレーターを用いて関数を指定し、その関数をプロンプトの一部としてoptionsパラメータに渡すことによって実現されます。

例えば、以下のAI関数は、家電製品マニュアルから作成されたメンテナンスタスクのリストを生成し、logMaintenanceScheduleInternal()関数を使用してそのタスクをビルトインデータベースに書き込みます:

backend/src/service/example-service.ts
  @aiFunction(
  'If someone asks for a list of maintenance tasks, run this function. This function creates a maintenance task for a list of tasks. Pass each created task to this function. If the user asks how to complete a specific task, then do not run this function. !Important: if a user asks questions about **existing** tasks in the database, then do not run this function.',
  [
    {
      name: 'task',
      description: 'the task to complete',
      type: 'string',
      required: true,
    },
    {
      name: 'interval',
      description: 'the frequency or interval at which the task needs to be done',
      type: 'string',
      required: true,
    },
    {
      name: 'appliance',
      description:
        'the appliance that requires the given maintenance. Provide the manufacturer name of the appliance, along with the type of appliance',
      type: 'string',
      required: true,
    },
  ],
)
async
createTaskItem(params
:
{
  task: string;
  interval: string;
  appliance: string
}
)
{
  const { task, interval, appliance } = params;
  await this.logMaintenanceScheduleInternal({ task, interval, appliance, completed: false });
}

注: @aiFunctionデコレーターは、関数の目的を記述するパラメータを含んでいます。AIエージェントはこの情報を使用して、いつ関数を呼び出すかを判断します。

2つ目のAI関数は、プロンプトに基づいてデータベースから情報を取得します:

backend/src/service/example-service.ts
  @aiFunction(
  " !Important: Call this function when a client prompt requests information about the **existing** tasks in their database. This function queries the database for tasks that meet the client's request. Include the exected query in your response",
  [
    {
      name: 'prompt',
      description: 'the request from the client',
      type: 'string',
      required: true,
    },
  ],
)
async
checkTasksAI(params
:
{
  prompt: string
}
):
Promise < string > {
  const { prompt } = params;
  const response = await this.squid.ai().executeAiQuery('built_in_db', prompt);
  return `${response.answer} \n ${response.executedQuery}`;
}

フロントエンドでは、以下のコードで各プロンプトに対して関数が渡されます:

frontend/src/App.tsx
chat(question, { functions: ['checkTasksAI', 'createTaskItem'] }); // Add functions in the second parameter

その後、AIエージェントはプロンプトに応じて関数を実行するタイミングを判断します。

AI関数の詳細については、AI functions documentation をご覧ください。

次のステップ

おめでとうございます！ドキュメントを読み、質問に回答し、ドキュメントの内容に基づいてデータベースに書き込み、さらにクライアントプロンプトに基づいてデータベースから読み取るAIエージェントをアプリケーションに追加しました。

Squid AIエージェントの詳細については、documentation をご覧ください。
Squidのリアルタイムデータ機能の詳細については、Client SDK documentation をご覧ください。
ご自身のデータソースに接続する方法については、Database connectors documentation をご覧ください。

ドキュメントをAIエージェントの知識ベースに統合し、その後データに基づいてアクションを実行する​

作成するもの​

環境のセットアップ​

AIエージェントの追加​

バックグラウンド知識の追加​

Squidアプリケーションの探索​

コードの確認​

フロントエンドでのAIエージェントの設定​

AIエージェントへの機能追加​

次のステップ​