Squid AI Agent にセキュリティを追加する

Auth0 認証とバックエンド認可を利用して Squid AI agent を保護します。

Squid AI を用いることで、提供するユニークなコンテキストとツールに基づいて、豊かな AI エージェント体験を構築できます。数行のコードを追加するだけで、Squid's robust backend functionality を利用して AI エージェントを保護することができます。

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

このチュートリアルでは、AI エージェントを作成して保護するために必要なステップの「何をするのか」と「なぜそれをするのか」について詳しく解説します。最後まで進めることで、Squid AI Agent の仕組みについて十分な理解が得られるでしょう。

作成するもの

チャットアクセスを制限するための認証と認可が設定されたカスタム AI エージェント
Squid AI Agent を実行するための React フロントエンドアプリケーション

習得できる内容

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

必要なもの

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

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 Agent の追加

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

Agent ID: squid-facts-chatbot
説明: 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 article on squids に移動して、ページを HTML または PDF ファイルとして保存します。次に、Agent Overview ページで Add Abilities をクリックします。Knowledge Base の下にある File ability を選択し、ファイルをアップロードします。この ability により、エージェントは質問に回答する際にコンテキストを使用することができます。

注意

LLM models はおそらく既にこの squid 情報を知っています。ご自身のアプリケーションでは、ユースケースに合わせた適切なコンテキストを提供することになります。

Auth0 コネクタの追加

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

次に、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 アプリケーションから取得した domain と clientId に置き換えます:

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';

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>;
}

return 文内で、isAuthenticated プロパティの値を false から !!user に変更します:

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

チェックポイント

この時点で、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 Agent の機能追加

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';

SquidFactsAI 関数内に以下を追加します:

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

現在、askQuestion 関数は question の値を空文字に設定するだけですが、実際には質問を送信していません。askQuestion に 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>

チャットのレスポンスが完了するまで Button を無効にするよう更新し、AI エージェント利用時にエラーが発生した場合はエラーメッセージを表示する div を追加します:

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

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

...
)

チェックポイント

これで、このコンポーネントのコードは完成です。以下は 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 に関する質問をしてみてください。回答が返ってこず、未認可のメッセージが表示されることに注意してください。
アプリにログインして再度質問してください。すると、AI エージェントがあなたとチャットします！

ログアウトや再ログインを試すなど、自由に質問して動作を確認してみてください。バックエンドの Squid Service が認可を処理するため、認証済みのユーザーのみがサービスにアクセスできることが保証されます。

試してみるための質問例:

イカには腕がありますか、それとも触手がありますか？
イカに遭遇した場合、どうすればよいですか？
イカに関するあなたのお気に入りの豆知識は何ですか？
Onykia ingens について教えてください。

あなたのお気に入りのイカに関する質問や回答を、Discord または X の Squid Squad と共有してください。

結論

おめでとうございます！このチュートリアルでは、アプリにカスタム AI エージェントを追加し、Squid Backend SDK を使用してそのエージェントを保護する方法を学びました。質問を続けて、この AI エージェントが squid についてどれだけ知識を持っているかを確認してください！

次のステップ

認証済みユーザーに対して AI エージェントのアクセスを制限する方法が分かったので、他にも以下のことを試してみてください:

ユースケースに基づいて新しい AI エージェントを追加する。例えば、Squid AI エージェントは、セールス、サポート、プロダクトエキスパートなど、ユーザーエンゲージメントの各側面に対して異なるペルソナをサポートできます。
Squid middle tier を使用してデータベースをフロントエンドに接続し、Squid Client SDK を通じてデータアクセス機能を有効にする。
Squid AI Agent を保護するためのその他のプロパティについても検討してみる。例えば、ユーザーに事前に同意書に署名してもらい、その同意状況をデータベースに記録し、バックエンドでログイン状態と同意書署名の有無を確認する、といった方法が考えられます。

後片付け

今後の請求を防ぐため、Squid Console の対象アプリの Overview タブで Delete Application を選択し、Squid アプリを削除してください。

Auth0 認証とバックエンド認可を利用して Squid AI agent を保護します。​

作成するもの​

習得できる内容​

必要なもの​

Environment setup​

Squid AI Agent の追加​

Auth0 コネクタの追加​

Auth0 資格情報の追加​

チェックポイント​

Squid AI Agent の機能追加​

チェックポイント​

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

Squid バックエンドで AI エージェントを保護する​

アプリを試してみる​

結論​

次のステップ​

後片付け​

Auth0 認証とバックエンド認可を利用して Squid AI agent を保護します。

作成するもの

習得できる内容

必要なもの

Environment setup

Squid AI Agent の追加

Auth0 コネクタの追加

Auth0 資格情報の追加

チェックポイント

Squid AI Agent の機能追加

チェックポイント

Messages コンポーネントの設定

Squid バックエンドで AI エージェントを保護する

アプリを試してみる

結論

次のステップ

後片付け