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

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

アプリケーションにAIエージェントの力を取り入れたいものの、どこから始めればよいか分からない場合でも、SquidのAIチャットウィジェットなら数分で立ち上げられる手軽さがありつつ、ビジネスに固有のユーザー体験を提供できるほど強力です。以下の手順では、WebアプリにAIチャットウィジェットを追加するために必要なものをすべて案内します。

AI Agent のセットアップ

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

Note

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

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

エージェントを追加したら、続けて独自の instructions と knowledge を追加し、このエージェントをパーソナライズします。

Instructions: instructions は、エージェントがどのように応答するかのルールを提供します。instructions は、直接的でシンプルなガイドラインとして書くのが最も効果的です。例えば、Squid AI に簡潔に回答するよう指示したり、特定の種類の質問に対して特定の応答をするよう指示したりできます。
Knowledge base: knowledge base に追加された項目は、エージェントに追加の背景コンテキストを提供します。これにより、基盤となるAIモデルに含まれていない可能性のある特定トピックについても、関連性の高い回答ができるようになります。Knowledge はファイルまたは生テキストで追加できます。コンテキストの良い例としては、ドキュメント、製品マニュアル、業務運用（例: 営業時間）などがあります。

Test chat ボタンをクリックすると、独自のエージェントがメッセージにどう応答するかをテストできます。

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

Squid AI chat widget をウェブサイトに追加するには、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'
/>

custom elements を有効化する

フロントエンドフレームワークによっては、カスタムHTML要素の使用を許可するために追加の手順が必要です。以下は React と Angular における手順です。別のフロントエンドフレームワークを使用している場合は、ユースケースに応じて custom elements を有効化する方法を調べてください。

React: src ディレクトリ配下に次の declarations.d.ts ファイルを配置することで、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 widget が稼働します！

任意のカスタマイズ

Squid AI widget には、ユースケースに合わせてウィジェットをカスタマイズできる任意パラメータもあります。

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: ユーザーに送信される導入メッセージを制御します

次のテキストカスタマイズオプションも利用できます:

text-placeholder: ユーザーメッセージ入力のプレースホルダーを制御します（例: "Ask me anything..."）
text-thinking: AI agent が応答を生成中に表示されるテキストを制御します
text-thought-for: AI agent の chain of thought を表示する際に表示されるテキストを制御します。例: "Thought for...".
text-suggested-prompts: suggested prompts セクションのタイトルを制御します
text-suggested-prompts-description: suggested prompts セクションの説明文を制御します
text-milliseconds: ミリ秒のテキストを制御します
text-seconds: 秒のテキストを制御します
text-minutes: 分のテキストを制御します
powered-by-text: ウィジェット下部の "Powered by Squid" テキストを制御します
rtl-mode: アラビア語やヘブライ語などのRTL言語向けに right-to-left テキストモードを有効化するかどうかを示す boolean です。

Usage Sample:

Client code
<squid-chat-widget
  // ...
  rtl-mode="true"
  text-thinking={'Analyzing...'}
  text-thought-for={'Analyzed for...'}
  // ...
</squid-chat-widget>

squid-ai-functions: Squid AI function 名の文字列配列を指定し、クライアントのプロンプトに基づいてAI agent がアクションを実行できるようにします。Squid AI Functions の詳細は、AI Functions documentation を参照してください。
disable-history: 会話履歴を保持するか、無効化するかを示す boolean です。
chain-of-thought : データベースへのクエリ、レスポンス表示、AI function 呼び出しなど、AI agent の chain of thought を表示するかどうかを示す boolean です。例:

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

predefined-prompts:（文字列化された）JSON配列で、Squid chat widget 内でユーザーに表示されるプロンプト例のリストを定義します。ユーザーがAI agent に何を尋ねたり生成したりできるかをガイドします。例:

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 agent に渡されるオブジェクトです。ユーザーIDやプロジェクトIDなどの追加情報をAI agent に渡すのに使えます。これらは、エージェントから直接、またはAI functions 内でバックエンドから取得できます。AI agent にパラメータを渡す方法については、Passing parameters to the AI Function documentation を参照してください。
- instructions: このエージェントについてSquid Console で設定したデフォルトの instructions に**追記（append）**される文字列です。この特定のウィジェットインスタンス向けに追加コンテキストを与えたり、エージェントの挙動を変更したりできます。
- contextMetadataFilterForKnowledgeBase: knowledge base をクエリする際に適用するメタデータフィルターを定義するオブジェクトです。AI agent が回答時に使用するコンテキストを制限するのに使えます。コンテキストのメタデータフィルタリングについては、documentation を参照してください。

Example:

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で処理でき、用途に合わせたエージェント応答を実現できます。リクエストパラメータを送信でき、またリクエストボディからユーザープロンプトを取得できます。
Example:

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 Agent が使用したコンテキストへの参照を、レスポンスに含めるかどうかを示す boolean です。
squid-ai-query: "true" に設定すると、ウィジェットは squid-ai-integration-id をデータベース用 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文字列です。コンテキストのメタデータフィルタリングについては、documentation を参照してください。
enable-transcription: マイクアイコンを表示して、ユーザーがプロンプトを音声入力し自動的に文字起こしできるようにするかどうかを示す boolean です。
open-on-load: FABボタン付きウィジェットが、コンポーネントのレンダリング時に開いた状態にするかどうかを示す boolean です。
squid-ai-override-model: エージェントが使用するLLMモデルを上書きするためのオプションです。
class: ウィジェットの一般的なスタイリングには squid_chat_widget_dark と squid_chat_widget_light の2つのオプションがあります。より多くのカスタマイズは下の style セクションで利用できます。
style: HTML要素の style 属性を用いてウィジェットをスタイリングできます。width や height といった標準オプションに加え、Squid AI chat widget にはウィジェットのスタイルを制御するための複数の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 agent には、public と private の2つのアクセス制御モードがあります。

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

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

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

これにより、Squid backend はあなたの認証情報にアクセスできるようになります。次の例では、認証済みであればユーザーがすべてのAI agent とチャットできるようになります。

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

Note

Squid Console でAI agent を public に設定すると、@secureAiAgent ルールはバイパスされ、誰でもAI agent とチャットできるようになります。ただし、どのクライアントでもAI agent とチャットできる一方で、認証情報はSquid backendで引き続き利用可能であり、任意のAI functions に適用され得ます。つまり、public AI agent の機能の一部を引き続き保護できます。

認証情報はAI functions からもアクセスできるため、AI agent に紐づく各functionに対してきめ細かなアクセス制御を行えます。認証情報を利用して、クライアントがログインしていることを保証したり、クライアントのトークンに必要なカスタムクレームが存在するかを確認したり、認証情報に基づいてデータソースをクエリしたりできます。

次の例は、クライアントユーザーの認証情報にアクセスしてユーザーの Slack user ID を取得するものです。この user ID は、ユーザーがアクセスを許可されている Slack メッセージを検索するfunctionに渡されます。

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 chat widget をウェブサイトにデプロイする方法が分かりました。

Squid AI でできることをさらに知りたい場合は、Query with AI のような他の機能や、Squid SDKs を使用したさらなるカスタマイズオプションをご覧ください。

また、次のチュートリアルを含むサンプルも試せます:

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

AI Agent のセットアップ​

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

custom elements を有効化する​

任意のカスタマイズ​

アクセス制御​

次のステップ​