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

AI を搭載したチャットウィジェットをウェブサイトに統合し、ユーザーがあなたのビジネスの価値を簡単に理解できるようにします。

もし、アプリケーションに AI エージェントのパワーを取り入れたいが、どこから始めればよいかわからない場合、Squid の AI チャットウィジェットは数分で起動できるシンプルなオプションを提供すると同時に、ビジネスに固有のカスタマイズされた体験をユーザーに提供するほど強力です。以下のステップですべての必要な情報が提供され、あなたの Web アプリに AI チャットウィジェットを追加することができます。

AI エージェントの設定

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

Note

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

Create New Agent をクリックします。各 AI エージェントは独自の命令セットと能力によって区別される固有のペルソナを持っています。これにより、特定の設定に応じたカスタマイズされた応答が AI エージェントから提供されます。
Agent ID フィールドにエージェントの説明的な名前を入力します。注: この ID は後から変更することはできません。
例: "ACME business analyst"
将来の参照のために、エージェントが何をするのかの詳細な説明を追加します。
例: "Queries and emails my ACME home goods business data."
Create をクリックして、新しいエージェントを初期化します。

エージェントを追加した後は、あなた自身の指示や知識を追加して、このエージェントをパーソナライズしてください。

Instructions: instructions はエージェントがどのように応答するかのルールを提供します。指示は直接的でシンプルなガイドラインであるほど効果的です。例えば、Squid AI に簡潔に応答するよう指示したり、特定の種類の質問に対して特定の応答を返すよう指示することが考えられます。
Knowledge base: knowledge base に追加された項目は、エージェントに追加の背景情報を与えます。これにより、AI モデルに含まれていない特定のトピックについても関連する回答を提供できるようになります。知識はファイルまたは生テキストで追加できます。良い例としては、ドキュメント、製品マニュアル、ビジネスオペレーション（例: 店舗の営業時間）などが挙げられます。

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: React で Squid AI HTML 要素を有効にするには、src ディレクトリの下に以下の declarations.d.ts ファイルを配置します:

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

Angular: Angular でカスタム HTML 要素を有効にするには、src/app/app.module.ts ファイルに以下のコードを追加します:

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 function の名前の文字列の配列を指定し、あなたの AI エージェントがクライアントのプロンプトに基づいてアクションを実行できるようにします。Squid AI Functions の詳細については、AI Functions documentation をご覧ください。
disable-history: 会話履歴を保持するか無効にするかを示すブール値です。
chain-of-thought : データベースへのクエリ、応答の表示、AI function の呼び出しなど、エージェントの思考プロセスを表示するかどうかを示すブール値です。例:

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

predefined-prompts: ユーザーが AI エージェントに何を尋ねたり生成させたりできるかを案内するために、Squid チャットウィジェットに表示される例となるプロンプトのリスト (文字列化された JSON 配列) を定義します。例:

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: エージェントにコンテキストとして渡されるオブジェクトです。ユーザー ID やプロジェクト ID など、追加情報を AI エージェントに渡すために使用できます。これらはバックエンドまたは AI function 内で直接取得できます。AI エージェントにパラメータを渡す方法の詳細については、Passing parameters to the AI Function documentation をご覧ください。
- instructions: Squid Console のエージェントスタジオで定義されたデフォルトの指示に追記する文字列です。これを使用して、追加のコンテキスト情報を提供したり、この特定のウィジェットインスタンス用にエージェントの振る舞いを変更したりできます。
- contextMetadataFilterForKnowledgeBase: 知識ベースへのクエリ時に適用するメタデータフィルタを定義するオブジェクトです。これにより、質問に回答する際に AI エージェントが使用するコンテキストを制限できます。コンテキストメタデータフィルタリングの詳細については、こちらのドキュメントをご覧ください。

例:

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: AI エージェントがクエリに回答する際に使用したコンテキストへの参照を応答に含めるかどうかを示すブール値です。
squid-ai-query: "true" に設定すると、ウィジェットはあなたのデータベースに対する統合 ID として squid-ai-integration-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 文字列です。コンテキストメタデータフィルタリングの詳細については、こちらのドキュメントをご覧ください。
enable-transcription: ユーザーがプロンプトを話して自動で文字起こしできるようにするマイクアイコンを含めるかどうかを示すブール値です。
open-on-load: FAB ボタン付きウィジェットがコンポーネントのレンダリング時に開いているかどうかを示すブール値です。
squid-ai-override-model: エージェントが使用する LLM モデルを上書きするためのオプションです。
class: ウィジェットには、全体のスタイリングを行うための2つのオプション、squid_chat_widget_dark と squid_chat_widget_light があります。その他のカスタマイズオプションは下記の 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 パラメータを使用した例です。もしくは、これらの変数を外部 CSS ファイルに定義することもできます:

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

アクセス制御

AI エージェントには、パブリックとプライベートの2種類のアクセス制御モードがあります。

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

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

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

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

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

Note

Squid Console で AI エージェントをパブリックに設定すると、@secureAiAgent ルールをバイパスし、誰でも AI エージェントとチャットできるようになります。ただし、どんなクライアントでも AI エージェントとチャットできる場合でも、auth 資格情報は Squid バックエンド内で利用可能であり、AI functions に適用される可能性があります。つまり、パブリック AI エージェントでも、機能へのアクセスの一部を保護できます。

Auth 資格情報は AI functions 内でも利用可能であり、各 AI エージェントにアタッチされた関数への細かなアクセス管理を行うことができます。auth 資格情報を利用して、クライアントがログインしていることの確認、クライアントのトークンに必要なカスタムクレームが含まれているかのチェック、またはその資格情報に基づいてデータソースをクエリするなどが可能です。

以下の例は、クライアントのユーザー資格情報にアクセスし、ユーザーの Slack user 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 SDKs でのさらなるカスタマイズオプションをチェックしてみてください。

また、以下のチュートリアルを含むサンプルもお試しいただけます:

AI を搭載したチャット ウィジェットをウェブサイトに統合し、ユーザーがあなたのビジネスの価値を簡単に理解できるようにします。​

AI エージェントの設定​

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

カスタム要素の有効化​

オプションのカスタマイズ​

アクセス制御​

次のステップ​