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

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

Squid AI を使うと、あなたが提供する固有のコンテキストとツールに基づいた、リッチな AI agent 体験を作成できます。Squid の堅牢なバックエンド機能を使えば、わずか数行のコードで AI agent を保護できます。

ルールは、ユースケースに合わせて基本的にも高度にカスタマイズもできます。@secureAiAgent デコレーターを使用すると、TypeScript の関数を無限にカスタマイズ可能な AI agent のセキュリティソリューションに変えられます。さらに、セキュリティ関数は TypeScript で書かれるため、セキュリティルールの作成、解釈、更新は、他の関数を更新するのと同じくらい簡単です。

このチュートリアルでは、AI agent を作成して安全にするために必要な手順の「何を」「なぜ」を丁寧に説明します。最後には、Squid AI Agents について自信を持って理解できるようになるはずです。

作成するもの

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

学べること

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

必要なもの

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

環境セットアップ

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 をクリックして agent を追加します。次の詳細を入力し、Create をクリックします。

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

AI agent の 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）の豆知識を agent の knowledge base に追加するには、Wikipedia のイカの記事に移動し、ページを HTML または PDF ファイルとして保存します。次に Agent Overview ページで Add Abilities をクリックします。Knowledge Base の下にある File ability を選択し、ファイルをアップロードします。この ability により、agent は質問に答える際にコンテキストを使用できます。

Note

LLM モデルは、おそらくすでにこのイカ情報を知っています。あなた自身のアプリケーションでは、ユースケースに関連するコンテキストを提供します。

Auth0 connector を追加する

まだ Auth0 application を作成していない場合は、まず Auth0 アカウントをセットアップします。

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

最後に、squid-ai を API audience として Auth0 API（Applications サイドバー項目の配下）を作成します。
Squid Console の dev environment で、Connectors タブを選択します。
Available connectors タブをクリックして Auth0 connector を追加します

Connector ID: auth0
Auth0 Domain: この値は Auth0 application の settings で確認できます
Audience: squid-ai、または Auth0 API 作成時に入力した値

Add connector をクリックします。

Auth0 credentials を追加する

squid-facts/frontend/src/main.tsx に移動します。Auth0Provider コンポーネントがあり、設定が必要であることに注目してください。Auth0Provider コンポーネント内のプレースホルダーを、Auth0 application の domain と client 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 ファイルを開き、次の import を追加します。

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

これにより、Auth0 と Squid の React ライブラリ、および標準的な React の機能が import されます。

次のコードを 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>;
}

このコードは、Squid アプリケーションで auth provider を設定し、Auth0 の Access token を Squid バックエンドに渡します。

return 文で、isAuthenticated prop の値を false から !!user に変更します。

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

これにより NavBar に、表示すべきボタン（login ボタンか logout ボタンか）が伝わります。

チェックポイント

この時点で、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 agent に質問します。また、チャット履歴が表示される空の div コンポーネントもあります。次の import を追加します。

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 の値を空文字列に設定するだけで、実際には質問していません。askQuestion に chat 関数を追加して、AI agent に質問できるようにします。

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 コンポーネントの prop に渡され、そこで表示されます。

Button を更新して、チャット応答が完了するまで無効化されるようにします。さらに、AI agent 使用中にエラーが発生した場合にエラーメッセージを表示する 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 agent を保護する

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 agent とチャットできる Squid Service が作成されます。フロントエンドで呼び出した setAuthProvider 関数により、バックエンドにユーザーの認証ステータスが伝えられました。@secureAiAgent デコレーターはセキュリティルールを設定するために使用されます。この例ではユーザーが認証済みであることだけを検証していますが、カスタマイズした認可ルールを追加できます。たとえば、データベースにクエリして、ユーザーが許可されたユーザーリストの一員かどうかを確認できます。

security と authentication について、詳しくはドキュメントを参照してください。

アプリを試す

バックエンドをローカルで実行するには、backend ディレクトリで次のコマンドを実行します。

backend

squid start

別のターミナルウィンドウで、frontend ディレクトリから次のコマンドを実行します。

frontend

npm run dev

これで、ターミナルウィンドウが 2 つになります。1 つはバックエンド、もう 1 つはフロントエンドを実行しています。

アプリを表示するには、localhost:PORT に移動します。PORT はターミナルに表示されます。アドレスはおそらく http://localhost:5173 です。
AI agent にイカについて質問してみてください。応答が返ってこないことに気づくはずです。代わりに unauthorized のメッセージが表示されます。
アプリにログインして、もう一度質問してください。今度は AI agent がチャットしてくれます。

引き続き質問して、ログアウト/ログインしたときに何が起こるかも確認してみてください。バックエンドの 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.

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

まとめ

おめでとうございます！アプリにカスタマイズした AI agent を追加し、さらに Squid Backend SDK を使ってそれを保護しました。ぜひ質問を続けて、この AI agent がどれだけイカについて知っているか試してみてください！

次のステップ

AI agent へのアクセスを認証済みユーザーに制限する方法がわかったところで、次のようなことも試してみてください。

あなたのユースケースに基づいた新しい AI agent を追加する。たとえば Squid AI agents は、ユーザーエンゲージメントの各領域（営業、サポート、プロダクトエキスパートなど）ごとに異なる persona をサポートできます。
Squid middle tier を使ってデータベースをフロントエンドに接続し、Squid Client SDK を通じてデータアクセス機能を有効にする。
Squid AI Agent を保護する際の別のプロパティを考える。たとえば、ユーザーに事前に同意書への署名を求めたい場合があります。同意ステータスをデータベースに記録し、バックエンドでユーザーがログイン済みで同意書に署名していることを検証できます。

クリーンアップ

追加の課金を防ぐため、Squid Console でアプリの Overview タブを選択し、下にスクロールして Delete Application から Squid app を削除してください。

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

作成するもの​

学べること​

必要なもの​

環境セットアップ​

Squid AI Agent を追加する​

Auth0 connector を追加する​

Auth0 credentials を追加する​

チェックポイント​

Squid AI Agent の機能を追加する​

チェックポイント​

Messages コンポーネントをセットアップする​

Squid バックエンドで AI agent を保護する​

アプリを試す​

まとめ​

次のステップ​

クリーンアップ​

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

作成するもの

学べること

必要なもの

環境セットアップ

Squid AI Agent を追加する

Auth0 connector を追加する

Auth0 credentials を追加する

チェックポイント

Squid AI Agent の機能を追加する

チェックポイント

Messages コンポーネントをセットアップする

Squid バックエンドで AI agent を保護する

アプリを試す

まとめ

次のステップ

クリーンアップ