RAGエージェントを実装する

ドキュメントをあなたのAIエージェントのナレッジベースに統合し、その後データに対してアクションを実行する

作成するもの

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

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

AI能力	内部コネクタ	バックエンド機能
ナレッジベース	Built-in Database	Webhooks

このチュートリアルにご協力いただいたパートナーの皆様、Otairo に心より感謝いたします！

Environment setup

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

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

Add the AI agent

各エージェントは異なるペルソナまたはユースケースを表しており、それぞれ固有の指示と能力によって区別されます。

Squid Consoleで、Agent Studioタブに移動します。
Create New Agentをクリックしてエージェントを追加します。以下の詳細を入力してください：
- Agent ID: maintenance-scheduler
- Description: This is an agent for Squid AI's home maintenance tutorial
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 をご参照ください。

Add background knowledge

ナレッジベース機能は、質問に回答する際にエージェントへ文脈情報を提供します。文脈を追加することで、基盤となる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つのファイルをそれぞれアップロードします。アップロード中は少々お待ちください。エージェントは自動的にドキュメントから内容を抽出し、テキストをナレッジベースに追加します。

Explore your Squid application

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

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エージェントは、どのくらいの頻度でフィルターを掃除すべきかを判断し、その情報をもとに合理的な回答を提供します。

View the code

Squidによって支えられたAIエージェント搭載のフルスタックアプリケーションの構築に成功しました！内部で何が起こっているのか気になりますか？このセクションでは、コードの詳細を掘り下げていきます。

Configuring the AI agent on the frontend

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

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

Adding functionality to the AI agent

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 をご覧ください。

Next steps

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

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

ドキュメントをあなたのAIエージェントのナレッジベースに統合し、その後データに対してアクションを実行する​

作成するもの​

Environment setup​

Add the AI agent​

Add background knowledge​

Explore your Squid application​

View the code​

Configuring the AI agent on the frontend​

Adding functionality to the AI agent​

Next steps​