ウェブサイトにAIチャットウィジェットを追加する

業務価値をユーザーに簡単に理解してもらうため、AI搭載チャットウィジェットをウェブサイトに統合します。

もしアプリケーションにAIエージェントのパワーを組み込みたいが、どこから始めればよいか分からない場合、Squid の AIチャットウィジェットは、数分で立ち上げられるシンプルなオプションを提供すると同時に、あなたのビジネスに固有のカスタマイズされた体験をユーザーに提供できる十分な機能を備えています。以下の手順で、ウェブアプリにAIチャットウィジェットを追加するために必要なすべての情報を得ることができます。

AIエージェントのセットアップ

Squid Console に移動し、新しいアプリケーションを作成します。この Squid アプリケーションにあなたのAIウィジェットが含まれます。
Squid Console の Agent Studio タブに移動します。

Note

Squid は開発環境と本番環境の2種類のターゲット環境を提供しています。エージェントを動作させるためには、プロジェクト全体で同じターゲット環境を使用してください。エージェントは環境間で共有されません。Squid の環境についての詳細はこちらをご覧ください。

Create New Agent をクリックします。各AIエージェントは独自のインストラクションと機能を持つユニークな persona を持っており、特定の設定に応じたカスタマイズされたレスポンスを提供することができます。
Agent ID フィールドにエージェントの説明的な名前を入力します。
注意: このIDは後から変更できません。
例: "ACME business analyst"
将来の参照のために、エージェントが何を行うかの詳細な説明を追加します。
例: "Queries and emails my ACME home goods business data."
Create をクリックして新しいエージェントを初期化します。

エージェントを追加した後は、ご自身のインストラクションとナレッジを追加して、このエージェントをパーソナライズしてください。

Instructions: インストラクションは、エージェントがどのように応答するかのルールを提供します。インストラクションは、直接的でシンプルなガイドラインとして最も効果的に機能します。例えば、Squid AI に簡潔に回答させる、または特定の種類の質問に対して具体的なレスポンスを提供させるといった指示が良い例です。
Knowledge base: ナレッジベースに追加された項目はエージェントに追加の背景情報を提供します。これにより、基盤となるAIモデルに含まれていない特定のトピックに対しても、エージェントが適切な回答を行えるようになります。ナレッジはファイルまたは生のテキストを使用して追加できます。文脈に適した良い例として、ドキュメント、製品マニュアル、ビジネス運用（例: store hours）などが挙げられます。

Test chat ボタンをクリックして、あなたのユニークなエージェントがメッセージにどのように応答するかをテストすることができます。

AIチャットウィジェットをサイトに追加する方法

Squid AI チャットウィジェットをウェブサイトに追加するには、HTML の <head> または <body> セクションに以下を追加してください:

Client code
<script async src="https://widget.squid.cloud/widget.umd.js"></script>

ウェブサイトのHTMLコードにチャットウィジェットを埋め込む方法は2通りあります:

画面に表示される標準のチャットウィジェットには <squid-chat-widget /> を使用します。このHTML要素は、HTMLの <body> 内の任意の場所に配置可能な標準のブロック要素として機能します。
浮動アクションボタン付きでチャットの開閉を切り替えるウィジェットには <squid-chat-widget-with-fab-button /> を使用します。このHTML要素は、HTML の <body> 内の任意の場所に配置でき、浮動アクションボタンは画面の右下隅に表示されます。

ウィジェットの設定を完了するには、ウィジェットのHTML要素に以下の属性を追加してください。最初の5つのプレースホルダーはご自身のアプリケーションの値に置き換えてください。最初の4つの値は、Squid Console のアプリケーション概要ページの Backend Project セクションで Show env vars をクリックすることで確認できます:

Client code
<squid-chat-widget
  squid-app-id='YOUR_APP_ID'
  squid-region='YOUR_REGION' {/* example: 'us-east-1.aws' */}
  squid-environment-id='dev | prod' {/* one of 'dev' or 'prod' */}
  squid-developer-id='YOUR_DEVELOPER_ID' {/* Include the developer ID when running backend locally */}
  squid-ai-profile-id='AI_AGENT_ID' {/* The ID of the AI agent you created (step 4 above) */}
  squid-ai-integration-id='ai_agents'
/>

カスタムエレメントの有効化

一部のフロントエンドフレームワークでは、カスタムHTML要素の使用を許可するために追加の手順が必要です。以下は React と Angular における手順です。もし他のフロントエンドフレームワークを使用している場合は、使用ケースに合わせたカスタムエレメントの有効化方法を調査してください。

React: 以下の declarations.d.ts ファイルを src ディレクトリに配置することで、React で Squid AI HTML エレメントを有効化できます:

Client code
declare namespace JSX {
  interface IntrinsicElements {
    'squid-chat-widget-with-fab-button': any;
    'squid-chat-widget': any;
  }
}

Angular: 以下のコードを src/app/app.module.ts ファイルに配置することで、Angular でカスタムHTML要素を有効化できます:

Client code
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})

これで、ウェブサイト上に Squid AI Agent ウィジェットが動作するようになりました！

オプショナルなカスタマイズ

Squid AI ウィジェットには、使用ケースに合わせてウィジェットをカスタマイズするための任意のパラメーターも用意されています:

menu-items-json: title および slotName 属性を持つオブジェクトの配列を受け付けます。この配列は、ウィジェットの子要素として定義されるドロップダウンメニュー項目のタイトルと名前を記述します。ドロップダウンメニューはウィジェットの右上に表示されます。以下は JSX を用いた例です:

Client code
<squid-chat-widget
  // ...
  menu-items-json=[
{"title":"Contact us", "slotName":"contact"}]
>
<div slot="contact" >
  <form onSubmit={onSubmit}>
  <input type="email" />
  </form>
</div>
</squid-chat-widget>

header-title: ウィジェット上部のヘッダーのテキストを制御します。
intro-text: ユーザーに送信される導入メッセージを制御します。
squid-ai-functions: Squid AI の関数名の文字列配列を提供し、クライアントのプロンプトに基づいてAIエージェントがアクションを実行できるようにします。詳細は AI Functions documentation をご覧ください。
disable-history: 会話履歴を保持するか無効にするかを示すブール値です。
chain-of-thought : データベースへのクエリ、レスポンスの表示、AI関数の呼び出しなど、AIエージェントの思考プロセスを表示するかどうかを示すブール値です。例:

Client code
<squid-chat-widget chain-of-thought="true">
</squid-chat-widget>

predefined-prompts: (stringified) JSON配列で、ユーザーに表示される例示プロンプトのリストを定義します。これにより、ユーザーがAIエージェントに何を質問・生成できるかの指針を提供します。例:

Client code
<squid-chat-widget
  // ...
  predefined-prompts='[
    "Summarize the key insights from my data.",
    "Generate a chart showing monthly trends and export it as a PDF.",
    "Identify any unusual patterns or outliers in my dataset."
  ]'>
</squid-chat-widget>

squid-ai-connected-agents: 現在このエージェントに接続されているエージェントのリストです。これらのエージェントは、通信やタスクの委任に利用できます。例:

Client code
<squid-chat-widget
  // ...
  squid-ai-connected-agents='[
  {
    "agentId": "knowledge-agent",
    "description": "Call this agent when asked to retrieve data from the knowledge base"
  },
  {
    "agentId": "source-verification-agent",
    "description": "Call this agent when you need to verify sources of financial information"
  }
]'>
</squid-chat-widget>

squid-ai-chat-options: エージェントに渡される設定オプションのリスト:
- agentContext: AIエージェントにコンテキストとして渡されるオブジェクトです。ユーザーIDやプロジェクトIDなど、追加情報をエージェントに渡す際に使用できます。これらはバックエンドやAI関数内で直接取得可能です。パラメーターの渡し方の詳細は、Passing parameters to the AI Function documentation をご覧ください。
- instructions: Squid Consoleで設定されたこのエージェントのデフォルトインストラクションに追加する文字列です。追加の文脈を提供したり、特定のウィジェットインスタンスにおけるエージェントの動作を変更するために使用されます。
- contextMetadataFilterForKnowledgeBase: ナレッジベースを検索する際に適用するメタデータフィルターを定義するオブジェクトです。エージェントが質問に回答する際のコンテキストを制限するために使用できます。詳細は documentation をご覧ください。

例:

Client code
<squid-chat-widget
  // ...
  squid-ai-agent-chat-options='{{
    agentContext: { "context_key": "context_value" },
    instructions: `New instructions that append to the instructions for this agent defined in the agent studio.`,
    contextMetadataFilterForKnowledgeBase: {"knowledgebase-id": { "filter_id": "value" }},
  }}'>
  // ....
</squid-chat-widget>

squid-ai-custom-api-url: デフォルトのエージェント動作を上書きするURLエンドポイントです。これにより、ユーザープロンプトをカスタムバックエンドのWebhookでインターセプト・処理し、テーラーメイドのエージェントレスポンスを実現できます。リクエストパラメータを送信したり、リクエストボディからユーザープロンプトを取得することが可能です。
例:

Client code
<squid-chat-widget
  // ...
  squid-ai-custom-api-url="https://squidAppId-dev-squidDevId.us-east-1.aws.squid.cloud/webhooks/chat?projectId=YOUR_PROJECT_ID"
</squid-chat-widget>

Backend code
@webhook('chat')
async chat(request: WebhookRequest<ChatRequest>): Promise<ChatResponse> {
  const userPrompt = request.body.prompt;
  const projectId = request.queryParams["projectId"];
  // Custom logic to handle the user prompt and projectId
  // For example, you could log the prompt or modify it before further executing a workflow
  return { response: "success" };
}

include-reference: 回答に使用されたコンテキストの参照を含めるかどうかを示すブール値です。
squid-ai-query: このパラメーターを "true" に設定すると、ウィジェットは squid-ai-integration-id をデータベース用の統合IDとして定義します。このパラメーターを使用する場合、squid-ai-profile-id を "undefined" に設定してください。自然言語でデータソースにクエリする方法の詳細は、Query with AI documentation をご覧ください。
squid-ai-max-tokens: LLMに渡す最大トークン数です。この高度な機能により、レスポンスの品質やコストを調整できます。
squid-ai-temperature: 0から1のスケールでレスポンスのランダム性を制御します。
squid-ai-context-metadata-filter: コンテキストに適用するメタデータフィルターを示すJSON文字列です。詳細は documentation をご覧ください。
enable-transcription: ユーザーがプロンプトを音声入力し自動で文字起こしできるよう、マイクアイコンを含めるかどうかを示すブール値です。
open-on-load: コンポーネントのレンダリング時にFABボタン付きウィジェットを開いた状態にするかどうかを示すブール値です。
squid-ai-override-model: エージェントが使用するLLMモデルを上書きするために使用します。
class: ウィジェットの一般的なスタイリングには、squid_chat_widget_dark と squid_chat_widget_light の2種類のオプションがあります。より多くのカスタマイズオプションは下記の style セクションで利用できます。
style: ウィジェットはHTML要素の style 属性を用いてスタイル設定が可能です。width や height といった標準オプションに加え、Squid AI チャットウィジェットはウィジェットのスタイルを制御するための複数のCSS変数を提供します。以下は使用可能な変数のリストです:
- --squid-widget-ai-message-background-color
- --squid-widget-avatar-image-url
- --squid-widget-body-background-color
- --squid-widget-header-background-color
- --squid-widget-header-menu-button-background-color
- --squid-widget-header-menu-button-icon-url
- --squid-widget-header-menu-item-color
- --squid-widget-header-menu-item-hover-background-color
- --squid-widget-header-title-color
- --squid-widget-inline-code-background-color
- --squid-widget-inline-code-border-color
- --squid-widget-link-color
- --squid-widget-powered-by-color
- --squid-widget-textarea-background-color
- --squid-widget-textarea-border-color
- --squid-widget-textarea-text-color
- --squid-widget-textarea-submit-image-url
- --squid-widget-user-message-background-color
- --squid-widget-user-message-color
- --squid-widget-fab-background-color
- --squid-widget-fab-image-url
- --squid-widget-fab-close-image-url
- --widget-width

以下は、style パラメーターを用いた例です。あるいは、これらの変数を external CSS file で定義することもできます:

Client code
<squid-chat-widget
  //...
style = {
{
  '--squid-widget-header-background-color':'#fcba00',
  '--squid-widget-body-background-color':'#999999'
}}
/>

アクセス制御

AIエージェントには public と private の2種類のアクセス制御モードがあります。

Public なエージェントは誰でもアクセス可能です。Squid Console で Agent Studio タブに移動し、エージェントを選択して Agent Settings をクリックすることで、エージェントを public に設定できます。下にスクロールしてエージェントを public に切り替えてください。

エージェントが private に設定されている場合、ウィジェットへのアクセス管理が必要です。まず、auth provider を Squid に接続し、次にウィジェットの squid-auth-provider パラメーターに統合IDとクライアントのauthトークンを渡してください:

Client code
<squid-chat-widget
{/* ... */}
squid-auth-provider={JSON.stringify({
    integrationId: "AUTH_INTEGRATION_ID",
    token: "AUTH_TOKEN",
  })}
/>

これにより、Squid のバックエンドがあなたの認証情報にアクセスできるようになります。以下の例では、認証されているユーザーがすべてのAIエージェントとチャットできるように設定されています:

Backend code
@secureAiAgent('chat')
allowAccessToAgent(): boolean {
  return this.isAuthenticated();
}

Note

Squid Console でAIエージェントが public に設定されている場合、@secureAiAgent ルールはバイパスされ、誰でもAIエージェントとチャットできるようになります。ただし、どのクライアントもAIエージェントとチャットできる一方で、認証情報は引き続きSquidバックエンドで利用可能であり、どのAI関数にも適用されます。つまり、publicなAIエージェントの機能に対しても、ある程度のアクセス保護が可能です。

認証情報はAI関数内でもアクセス可能であり、各AIエージェントに付随する関数への細かなアクセス制御を行うことができます。認証情報を使用してクライアントがログインしていることを確認したり、クライアントのトークンに必要なカスタムクレームが含まれているかチェックしたり、認証情報に基づいてデータソースにクエリを実行したりできます。

以下の例は、クライアントの認証情報にアクセスしてユーザーの Slack ユーザーIDを取得する方法を示しています。このユーザーIDは、ユーザーがアクセスを許可されている Slack メッセージを検索する関数に渡されます:

Backend code
@aiFunction('', [
  {
    name: 'query',
    type: 'string',
    description: 'The search term to look for in Slack.',
    required: true,
  },
])
async querySlack(data: { query: string })
{
  const userId = this.getUserAuth().userId;
  const { slackUserId } = await this.squid.collection('slack_users')
    .doc({ userId: userId })
    .query()
    .dereference()
    .snapshot();
  if (!slackUserId) {
    return 'Not Authorized';
  }
  return await this.searchSlackMessages(query, slackUserId);
}

次のステップ

以上です！これで、ウェブサイトに Squid の強力な AI チャットウィジェットを展開する方法が分かりました。

Squid AI の可能性についてさらに知りたい場合は、Query with AI や Squid AI assistant といった他の機能やカスタマイズオプションもご覧ください。

また、以下のチュートリアルを含むサンプルも試すことができます:

業務価値をユーザーに簡単に理解してもらうため、AI搭載チャットウィジェットをウェブサイトに統合します。​

AIエージェントのセットアップ​

AIチャットウィジェットをサイトに追加する方法​

カスタムエレメントの有効化​

オプショナルなカスタマイズ​

アクセス制御​

次のステップ​