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

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

あなたのアプリケーションにAIエージェントの力を取り入れたいが、どこから始めればよいか分からない場合、SquidのAIチャットウィジェットは、数分でセットアップできる手軽さと、あなたのビジネスに固有のカスタマイズされた体験をユーザーに提供できる十分なパワーの両方を備えています。以下のステップに従えば、ウェブアプリにAIチャットウィジェットを追加するために必要なすべての情報が得られます。

AIエージェントの設定

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

Note

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

Create New Agent をクリックします。各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モデルに含まれていない特定のトピックに関しても適切な回答を返すことが可能になります。Knowledgeはファイルや生テキストを使用して追加できます。文脈における良い例としては、documentation、product manuals、及びbusiness operations (例: 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: Reactでは、以下の declarations.d.ts ファイルを src ディレクトリに配置することで、Squid AI HTML要素を有効化できます:

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

Angular: Angularでは、以下のコードを src/app/app.module.ts ファイルに配置することでカスタム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エージェントがアクションを実行できるようにします。Squid AI Functionsの詳細については、AI Functions documentationをご覧ください。
disable-history: 会話履歴を保持するか無効にするかを示すboolean値です。
include-reference: AIエージェントがクエリに回答する際に使用したコンテキストへの参照を応答に含めるかどうかを示すboolean値です。
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: ユーザーがプロンプトを話し、それを自動的に文字起こしするためのマイクアイコンを含めるかどうかを示すboolean値です。
open-on-load: コンポーネントがレンダリングされる際に、FABボタン付きウィジェットを開いた状態にするかどうかを示すboolean値です。
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パラメーターを使用した例です。あるいは、これらの変数をexternal CSS fileで定義することもできます:

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をクリックしてエージェントをパブリックに設定できます。下にスクロールしてエージェントをパブリックに切り替えてください。

エージェントがプライベートに設定されている場合は、ウィジェットへのアクセス管理を行う必要があります。まず、connecting your auth provider を使用してSquidに認証プロバイダーを接続し、その後、統合IDとクライアントの認証トークンをウィジェットの squid-auth-provider パラメーターに渡します:

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エージェントをパブリックに設定した場合、@secureAiAgent ルールはバイパスされ、誰でもAIエージェントとチャットすることが可能になります。しかし、どのクライアントもAIエージェントとチャットできる一方で、認証情報はSquidバックエンドで利用可能であり、どのAIファンクションにも適用されるため、パブリックな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チャットウィジェットをサイトに追加する方法​

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

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

アクセス制御​

次のステップ​