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

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

アプリケーションにAIエージェントの力を取り入れたいものの、どこから始めればよいかわからない場合、Squid のAIチャットウィジェットは、数分で立ち上げられる手軽さと、あなたのビジネスに固有のユーザー体験をカスタマイズして提供できる十分な強力さを兼ね備えた選択肢です。以下の手順では、WebアプリにAIチャットウィジェットを追加するために必要なものをすべて説明します。

AI Agent のセットアップ

Squid Console に移動し、新しい application を作成します。この Squid application にAIウィジェットが含まれます。
Squid Console の Agent Studio タブに移動します。

Note

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

Create New Agent をクリックします。各 AI agent は独自の persona（ペルソナ）を持ち、それぞれの instructions（指示）と abilities（能力）のセットによって区別されます。これにより、設定に応じて 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 はファイルまたは raw text で追加できます。コンテキストの例としては、ドキュメント、製品マニュアル、業務運用（例: 営業時間）などがあります。

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

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

Squid AI chat widget をWebサイトに追加するには、HTML の <head> または <body> セクションに以下を追加します。

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

チャットウィジェットをWebサイトの HTML に埋め込むには、2つの方法があります。

画面に表示される標準のチャットウィジェットには <squid-chat-widget /> を使用します。この HTML 要素は標準的なブロック要素として機能し、HTML の <body> 内の任意の場所に配置できます。
チャットを開閉する floating action button（FAB）付きのチャットウィジェットには <squid-chat-widget-with-fab-button /> を使用します。この HTML 要素は HTML の <body> 内の任意の場所に配置でき、FAB は画面右下に表示されます。

ウィジェットの設定を完了するために、以下の属性をウィジェットの HTML 要素に追加します。最初の5つのプレースホルダーは、あなたの application の値に置き換えてください。最初の4つの値は、Squid Console の application overview ページの 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 を有効にする

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

React: src ディレクトリ配下に次の declarations.d.ts ファイルを置くことで、React で Squid AI の HTML elements を有効にできます。

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 で custom HTML elements を有効にできます。

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 です。

使用例:

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

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

predefined-prompts:（stringified）JSON 配列で、ユーザーに表示する example prompts のリストを定義します。ユーザーがAI agentに何を質問/生成できるかをガイドするために、Squid chat widget に表示されます。例:

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: 現在この agent に接続されている agent のリストです。これらの agent はコミュニケーションやタスク委任に利用できます。例:

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: agent に渡される設定オプションのリストです。
- agentContext: コンテキストとして AI agent に渡されるオブジェクトです。ユーザーIDやプロジェクトIDなどの追加情報を AI agent に渡すために使用できます。これらは backend 側で agent から直接、または AI functions 内で取得できます。AI agent にパラメータを渡す方法の詳細は、Passing parameters to the AI Function documentationをご覧ください。
- instructions: Squid Console でこの agent に設定されたデフォルトの instructions に append（追記） される string です。この特定のウィジェットインスタンス向けに追加のコンテキストを与えたり、agent の振る舞いを変更したりするために使用できます。
- contextMetadataFilterForKnowledgeBase: knowledge base をクエリする際に適用する metadata filter を定義するオブジェクトです。これにより、AI agent が回答時に利用するコンテキストを制限できます。context metadata filtering の詳細は、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: デフォルトの agent の動作を上書きする URL endpoint です。ユーザープロンプトを intercept し、カスタム backend webhook を通して処理できるようにすることで、agent の応答を用途に合わせて調整できます。request params を送ることもでき、request body からユーザープロンプトを取得することもできます。
例:

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 に渡す token の最大数です。この高度な機能は、応答の品質とコストを変更するために使用できます。
squid-ai-temperature: 応答のランダム性（0〜1のスケール）です。
squid-ai-context-metadata-filter: コンテキストに適用する metadata filter を示す JSON string です。context metadata filtering の詳細は、documentationをご覧ください。
enable-transcription: マイクアイコンを表示して、ユーザーがプロンプトを話し、それを自動で文字起こしできるようにするかどうかを示す boolean です。
open-on-load: FAB button 付きウィジェットが、コンポーネントのレンダリング時に開いた状態にするかどうかを示す boolean です。
squid-ai-override-model: agent が使用する LLM model を上書きするためのオプションです。
class: ウィジェットには一般的なスタイリングとして squid_chat_widget_dark と squid_chat_widget_light の2つのオプションがあります。追加のカスタマイズオプションは、以下の style セクションで利用できます。
style: HTML 要素の style 属性を使ってウィジェットをスタイルできます。width や height のような標準オプションに加えて、Squid AI chat widget には複数の CSS variables があり、ウィジェットのスタイルを制御できます。利用可能な変数は以下のとおりです。
- --squid-widget-ai-message-background-color
- --squid-widget-avatar-image-url
- --squid-widget-body-background-color
- --squid-widget-header-background-color
- --squid-widget-header-title-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-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 を選択して Agent Settings をクリックすると、agent を public に設定できます。下へスクロールして、agent を public に切り替えてください。

agent が 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 があなたの auth credentials にアクセスできるようになります。以下の例では、認証済みであればユーザーがすべての AI agents とチャットできるようにしています。

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

Note

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

auth credentials は AI functions からもアクセスでき、AI agent に紐づく各 function への細かなアクセス制御を管理できます。auth credentials を使って、クライアントがログインしていることの確認、クライアント token に必要な custom claims が存在することの確認、credentials に基づくデータソースのクエリなどが可能です。

以下の例では、クライアントのユーザーcredentials にアクセスしてユーザーの Slack user ID を取得します。この user ID は、ユーザーがアクセスを許可されている Slack messages を検索する 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 をWebサイトにデプロイする方法がわかりました。

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

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

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

AI Agent のセットアップ​

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

custom elements を有効にする​

任意のカスタマイズ​

アクセス制御​

次のステップ​