Squid AIエージェントにセキュリティを追加する

Auth0認証とバックエンド認可を利用してSquid AIエージェントをセキュアにします。

Squid AIを使用すると、提供するユニークなコンテキストやツールに基づいたリッチなAIエージェント体験を作成できます。Squidの堅牢なバックエンド機能を使えば、数行のコードでAIエージェントをセキュアにすることが可能です。

ルールは、ユースケースに合わせて基本的なものからカスタマイズされたものまで設定できます。@secureAiAgentデコレーターを使うことで、TypeScriptの関数を無限にカスタマイズ可能なAIエージェントのセキュリティソリューションに変えることができます。また、セキュリティ関数はTypeScriptで記述されるため、他の関数を更新するのと同様に簡単にセキュリティルールの作成、解釈、更新が可能です。

このチュートリアルでは、AIエージェントを作成しセキュアにするための「何をするか」と「なぜするか」について詳しく解説するので、最後まで進めることでSquid AIエージェントについて十分に理解できるようになります。

作成するもの

認証と認可によりチャットアクセスを制限したカスタムAIエージェント
Squid AIエージェントを動作させるReactフロントエンドアプリケーション

学べること

Squid AIエージェントの作成方法
AIエージェントにコンテキストを提供する方法
Squid AIエージェントをフロントエンドに組み込む方法
AIエージェントにセキュリティを追加するSquid Serviceの作成方法

必要なもの

The Squid CLI
Squid Consoleのアカウント
React用に設定されたsingle-page applicationを持つAuth0アカウント

Environment setup

In the Squid Console, switch to the dev environment.

switch environment

Download the ai-tutorial-secure-chat code sample using the following command. Replace the placeholders with the values from your Squid application as shown in the console.

npx @squidcloud/cli init-sample ai-tutorial-secure-chat --template ai-tutorial-secure-chat --appId YOUR_SQUID_APP_ID --apiKey YOUR_SQUID_API_KEY --environmentId dev --squidDeveloperId YOUR_SQUID_DEVELOPER_ID --region YOUR_REGION

TIP

You can find your environment variables under: 'Application' -> 'Show env vars' as seen below:

switch environment

Open the project in the IDE of your choice.
Start the app locally by running the following command in the project folder:

npm run start

To view the app, navigate to localhost:PORT, where PORT is logged in the terminal. The address will likely be http://localhost:5173.

Squid AIエージェントの追加

Squid ConsoleでAgent Studioタブを選択します。
Create New Agentをクリックしてエージェントを追加します。以下の内容を入力し、Createをクリックしてください:

Agent ID: squid-facts-chatbot
Description: This is an agent for Squid AI's secure chat tutorial.

AIエージェントのOverviewページで、Instructionsセクションに移動し、以下の指示を追加してください:

You're a friendly AI who shares random facts about squids and answers user questions about squids.
Important: Only answer based on the provided context.

エージェントのナレッジベースにsquidの事実を追加するには、Wikipediaの記事に移動し、ページをHTMLまたはPDFファイルとして保存します。次に、Agent OverviewページでAdd Abilitiesをクリックし、Knowledge Baseの下のFileアビリティを選択してファイルをアップロードします。このアビリティにより、エージェントは質問に回答する際にコンテキストを使用できます。

Note

LLMモデルは既にこのsquid情報を知っている可能性があります。実運用のアプリケーションでは、ユースケースに沿ったコンテキストを提供してください。

Auth0コネクタの追加

まだAuth0アプリケーションを作成していない場合は、まずAuth0アカウントを設定してください。

次に、Auth0 Dashboardに移動し、React用に設定されたsingle-page applicationを作成します。アプリケーションの設定で、Allowed Callback URLs、Allowed Logout URLs、Allowed Web Originsにhttp://localhost:5173を追加することを忘れないでください。

最後に、Applicationsサイドバー項目の下にあるAuth0 APIを作成し、APIのaudienceとしてsquid-aiを指定してください。
dev環境のSquid Consoleで、Connectorsタブを選択します。
Available connectorsタブをクリックし、Auth0コネクタを追加します。

Connector ID: auth0
Auth0 Domain: この値は、Auth0アプリケーションの設定で確認できます。
Audience: squid-ai またはAuth0 API作成時に入力した値

Add connectorをクリックします。

Auth0資格情報の追加

squid-facts/frontend/src/main.tsxに移動します。Auth0Providerコンポーネントがあり、設定が必要です。Auth0Providerコンポーネント内のプレースホルダーを、Auth0アプリケーションのドメインとクライアントIDに置き換えてください:

src/main.tsx
ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
  <Auth0Provider
    domain="AUTH0_DOMAIN"
    clientId="AUTH0_CLIENT_ID"
    authorizationParams={{
      redirect_uri: window.location.origin,
      audience: 'squid-ai',
    }}
  >
    <SquidContextProvider
      options={{
        appId: import.meta.env.VITE_SQUID_APP_ID,
        region: import.meta.env.VITE_SQUID_REGION,
        environmentId: import.meta.env.VITE_SQUID_ENVIRONMENT_ID,
        squidDeveloperId: import.meta.env.VITE_SQUID_DEVELOPER_ID,
      }}
    >
      <App />
    </SquidContextProvider>
  </Auth0Provider>
);

App.tsxファイルを開き、以下のインポートを追加してください:

src/App.tsx
import { useAuth0 } from '@auth0/auth0-react';
import { useSquid } from '@squidcloud/react';
import { useEffect, useState } from 'react';

これで、Auth0およびSquid Reactライブラリと標準のReact機能がインポートされます。

App関数内に以下のコードを追加してください:

// Get Auth0 authentication state.
const { user, isLoading, getAccessTokenSilently } = useAuth0();
const { setAuthProvider } = useSquid();

useEffect(() => {
  setAuthProvider({
    integrationId: 'auth0',
    getToken: () => user && getAccessTokenSilently(),
  });
  if (isLoading) return;
  if (!user) {
    setLoginMessage('You are logged out!');
    setToastOpen(true);
  } else {
    setLoginMessage('You are logged in!');
    setToastOpen(true);
  }
}, [user, isLoading, getAccessTokenSilently, setAuthProvider]);

if (isLoading) {
  return <span>Loading...</span>;
}

このコードは、Auth0からのAccessトークンをSquidバックエンドに渡すために、Squidアプリケーションで認証状態を設定します。

return文の中で、isAuthenticatedプロパティの値をfalseから!!userに変更してください:

src/App.tsx
<NavBar isAuthenticated={!!user} />

これにより、NavBarはログインボタンまたはログアウトボタンのどちらを表示すべきかが判別されます。

Checkpoint

現時点でApp.tsxに必要なコードはすべて追加済みです。最終的なファイルは以下の通りです:

src/App.tsx
import SquidFactsAI from './components/squid-facts-ai';
import './App.css';
import NavBar from './components/nav-bar';
import { useEffect, useState } from 'react';
import { useAuth0 } from '@auth0/auth0-react';
import { useSquid } from '@squidcloud/react';
import { Snackbar, Alert } from '@mui/material';

function App() {
  // Set state of toast message
  const [toastOpen, setToastOpen] = useState(false);
  const [loginMessage, setLoginMessage] = useState('');

  // Get Auth0 authentication state
  const { user, isLoading, getAccessTokenSilently } = useAuth0();
  const { setAuthProvider } = useSquid();

  useEffect(() => {
    setAuthProvider({
      integrationId: 'auth0',
      getToken: () => user && getAccessTokenSilently()
    });
    if (isLoading) return;
    if (!user) {
      setLoginMessage('You are logged out!');
      setToastOpen(true);
    } else {
      setLoginMessage('You are logged in!');
      setToastOpen(true);
    }
  }, [user, isLoading, getAccessTokenSilently, setAuthProvider]);


  if (isLoading) {
    return <span>Loading...</span>;
  }

  const handleToClose = () => {
    setToastOpen(false);
  };

  return (
    <>
      <NavBar isAuthenticated={!!user} />
      <img src="https://upload.wikimedia.org/wikipedia/commons/e/e1/Sepioteuthis_sepioidea_%28Caribbean_Reef_Squid%29.jpg" />
      <SquidFactsAI />
      <Snackbar
        open={toastOpen}
        onClose={handleToClose}
        autoHideDuration={6000}
      >
        <Alert severity="success">{loginMessage}</Alert>
      </Snackbar>
    </>
  );
}

export default App;

Squid AIエージェントの機能追加

src/componentsフォルダ内のsquid-facts-ai.tsxファイルを開き、return文にあるTextFieldコンポーネントとButtonコンポーネントを確認してください。ここはユーザーがAIエージェントに質問を送る部分です。また、チャット履歴を表示するための空のdivも存在します。次のインポートを追加してください:

src/components/squid-facts-ai.tsx
import Messages from './messages';
import { useAiChat } from '@squidcloud/react';

useAiChat関数により、クライアント側でSquid AIを使ってチャットできるようになります。

SquidFactsAI関数に以下のコードを追加してください:

src/components/squid-facts-ai.tsx
const { history, chat, complete, error } = useAiChat(
  'squid-facts-chatbot'
);

現在、askQuestion関数は単にquestionの値を空文字に設定していますが、実際に質問を送信していません。chat関数を追加して、AIエージェントに質問を送信してください:

src/components/squid-facts-ai.tsx
function askQuestion() {
  chat(question);
  setQuestion('');
}

空のdivにMessagesコンポーネントを追加してください:

src/components/squid-facts-ai.tsx
<div className="scrolling">
  <Messages messages={history} />
</div>

これにより、会話履歴がMessagesコンポーネントに渡され、表示されます。

Buttonコンポーネントを、チャット応答が完了するまで無効にし、さらにエラー発生時にエラーメッセージを表示するdivを追加してください:

src/components/squid-facts-ai.tsx
...
return (
...

<Button variant="contained" disabled={!complete} onClick={askQuestion}>
  Ask question
</Button>
{ error && <div>{error.toString()}</div>}

...
)

Checkpoint

これで、このコンポーネントのコードは完成です。以下がsquid-facts-ai.tsxファイルの全コードです:

src/components/squid-facts-ai.tsx
import { ChangeEvent, useState } from 'react';
import { TextField, Button } from '@mui/material';
import Messages from './messages';
import { useAiChat } from '@squidcloud/react';

const SquidFactsAI = () => {
  const [question, setQuestion] = useState('');
  const { history, chat, complete, error } = useAiChat(
    'squid-facts-chatbot'
  );

  function askQuestion() {
    chat(question);
    setQuestion('');
  }

  function questionChanged(e: ChangeEvent) {
    setQuestion((e.target as HTMLInputElement).value);
  }

  function checkKey(ele: React.KeyboardEvent<HTMLDivElement>) {
    if (ele.key === 'Enter') {
      askQuestion();
    }
  }

  return (
    <>
      <div className="scrolling">
        <Messages messages={history} />
      </div>
      <div className="question">
        <TextField
          fullWidth
          id="outlined-basic"
          label="Enter your question"
          variant="outlined"
          onChange={questionChanged}
          onKeyDown={(event) => checkKey(event)}
          value={question}
        />
        <Button variant="contained" disabled={!complete} onClick={askQuestion}>
          Ask question
        </Button>
        {error && <div>{error.toString()}</div>}
      </div>
    </>
  );
};

export default SquidFactsAI;

Messagesコンポーネントの設定

messages.tsxファイルを開き、以下のコードに置き換えてください:

src/components/squid-facts-ai.tsx
import { useEffect, useRef } from 'react';
import { ChatMessage } from '@squidcloud/react';

interface ChatHistoryProps {
  messages: ChatMessage[];
}

const Messages: React.FC<ChatHistoryProps> = ({ messages }) => {
  const messagesEndRef = useRef<HTMLDivElement>(null);

  const scrollToBottom = () => {
    messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
  };

  useEffect(() => {
    scrollToBottom();
  }, [messages]);

  return (
    <div className="messages">
      {messages.map(({ id, message, type }) => (
        <div key={id}>
          <span key={id}>
            <b>{type}:</b> {message}
          </span>
        </div>
      ))}
      <div ref={messagesEndRef} />
    </div>
  );
};

export default Messages;

このコードはチャットメッセージを表示します。ChatMessageのtypeはメッセージの送信者（userまたはAI）を示します。

SquidバックエンドでAIエージェントをセキュアにする

backendフォルダに移動します。ここにはSquidバックエンドのロジックが含まれています。src/service/ai-security-service.tsファイルを開き、以下のコードを追加してください:

backend/src/service/ai-security-service.ts
import { secureAiAgent, SquidService } from '@squidcloud/backend';

export class AiSecurityService extends SquidService {
  @secureAiAgent('squid-facts-chatbot')
  allowChat(): boolean {
    // or add custom authorization here
    return this.isAuthenticated();
  }
}

このコードにより、ユーザーが認証されている場合にのみAIエージェントとのチャットが許可されるSquid Serviceが作成されます。フロントエンドで呼び出したsetAuthProvider関数が、ユーザーの認証状態をバックエンドに伝えています。@secureAiAgentデコレーターはセキュリティルールを設定するために使用されています。この例では単にユーザーが認証済みかどうかを検証していますが、カスタマイズした認可ルールを追加することも可能です。例えば、データベースを照会してユーザーが許可されたユーザーリストに含まれているかを確認することができます。

詳細については、securityおよびauthenticationのドキュメントをご参照ください。

アプリの動作確認

バックエンドをローカルで実行するには、backendディレクトリ内で以下のコマンドを実行してください:

backend

squid start

別のターミナルウィンドウで、frontendディレクトリから以下のコマンドを実行してください:

frontend

npm run dev

この時、バックエンドとフロントエンドをそれぞれ実行する2つのターミナルウィンドウが開かれている状態になります。

アプリを表示するには、ターミナルに記載されたPORTに従ってlocalhost:PORTにアクセスしてください。通常、アドレスはhttp://localhost:5173となります。
AIエージェントに対してsquidに関する質問をしてみてください。応答は返ってこず、代わりに「unauthorized」のメッセージが表示されることに気づくでしょう。
アプリにログインし、再度質問を送信してみてください。すると、AIエージェントがチャットで応答します！

ログアウトとログインを繰り返して、質問を試し続けることができます。SquidバックエンドのSquid Serviceが認証済みユーザーのみアクセスを許可しているため、安心してアプリを利用できます。

以下はいくつかの試しの質問です:

Do squids have arms or tentacles?
What should I do if I encounter a squid?
What's your favorite fact about squids?
Tell me about the Onykia ingens.

お気に入りのsquidに関する質問や回答をDiscordまたはXのSquid Squadで共有してください。

結論

おめでとうございます！カスタマイズされたAIエージェントをアプリに追加し、Squid Backend SDKを使用してセキュリティを実装することに成功しました。ぜひ引き続き、AIエージェントに質問して、その知識の深さを体感してください！

次のステップ

認証済みユーザーにのみAIエージェントへのアクセスを限定する方法を理解したところで、以下の他の事項も試してみてください:

ユースケースに基づいて新しいAIエージェントを追加する。例えば、Squid AIエージェントはユーザーエンゲージメントの各部分（営業、サポート、プロダクトエキスパートなど）に対して異なるペルソナをサポートできます。
Squid Client SDKを使用してデータアクセス機能を有効にするため、Squid middle tierを利用してデータベースをフロントエンドに接続してください。
Squid AIエージェントをさらにセキュアにするための追加プロパティを検討してください。例えば、ユーザーに同意書に署名してもらう必要がある場合、同意状況をデータベースに記録し、バックエンドでユーザーがログイン済みでかつ同意書に署名しているかを確認することができます。

クリーンアップ

さらなる請求を避けるため、Squid ConsoleのアプリでOverviewタブを選択し、下部のDelete ApplicationまでスクロールしてSquidアプリを削除してください。

Auth0認証とバックエンド認可を利用してSquid AIエージェントをセキュアにします。​

作成するもの​

学べること​

必要なもの​

Environment setup​

Squid AIエージェントの追加​

Auth0コネクタの追加​

Auth0資格情報の追加​

Checkpoint​

Squid AIエージェントの機能追加​

Checkpoint​

Messagesコンポーネントの設定​

SquidバックエンドでAIエージェントをセキュアにする​

アプリの動作確認​

結論​

次のステップ​

クリーンアップ​

Auth0認証とバックエンド認可を利用してSquid AIエージェントをセキュアにします。

作成するもの

学べること

必要なもの

Environment setup

Squid AIエージェントの追加

Auth0コネクタの追加

Auth0資格情報の追加

Checkpoint

Squid AIエージェントの機能追加

Checkpoint

Messagesコンポーネントの設定

SquidバックエンドでAIエージェントをセキュアにする

アプリの動作確認

結論

次のステップ

クリーンアップ