メインコンテンツまでスキップ

AIエージェントの作り方

SquidのSDKを利用することで、さまざまな機能を使用してAIエージェントをカスタマイズできます。永続的な命令やコンテキストを追加し、チャットセッションを管理し、AIロジックをカスタマイズするなど、特定のユースケースに合わせたカスタムAIエージェントを作成できます。​

仕組み​

内部的には、エージェントはLarge Language Model (LLM) を使用して、ユーザーの質問に対する回答を生成します。ユーザーが質問すると、永続的な命令と最も関連性の高いコンテキストがプロンプトの一部としてLLMに渡され、文脈に沿った回答が提供されます。

Squidでは、AIエージェント用のLLMを選択でき、ユースケースに最適なものを見つけることが可能です。現在、以下のLLMプロバイダーが利用可能です:

現在サポートされていない特定のモデルが必要な場合は、ぜひこちらからお問い合わせください！

エージェントの構築​

エージェントは、AIワークフローのための独自のパーソナリティやセットアップを表します。各エージェントは、それぞれ固有の命令と機能によって区別される異なるペルソナまたはユースケースのようなものです。この設計により、特定のエージェントに合わせたカスタマイズされた回答をAIから得ることができます。

注意

以下の例は、SquidのSDKを利用してエージェントを作成する方法を示しています。SquidプラットフォームやSDKを使用した開発に不慣れな場合は、こちらのドキュメントでフルスタック開発についてお読みください。

エージェントのアップサート​

プログラムでAIエージェントを作成または更新するには、作成または更新するエージェントIDを指定してupsert()メソッドを使用します:

Backend code
await squid
  .ai()
  .agent('banking-copilot')
  .upsert({
    options: {
      model: 'gpt-4o',
    },
    isPublic: true,
  });

エージェントを挿入する際は、エージェントが使用するモデルを示すmodelフィールドを含むoptionsオブジェクトを渡します。

isPublicパラメータは、指定されたエージェントのチャット機能にセキュリティルールを設定せずにアクセスできるかどうかを決定します。

エージェントの削除​

既存のエージェントを削除するには、delete()メソッドを使用します:

Backend code
await squid.ai().agent('banking-copilot').delete();

指定されたエージェントIDに該当するエージェントが存在しない場合、この関数はエラーを返します。

命令​

命令は、エージェントがプロンプトに応答し、質問に回答する方法のルールを定義します。これらは直接的かつシンプルであるべきで、エージェントの目的を説明します。命令はテキストブロックとして提供されます。

命令の追加​

AIエージェントへの命令を追加または編集するには、updateInstructions()メソッドを使用し、命令データを文字列として渡します。

Backend code
const instruction =
  'You are a helpful copilot that assists customer support staff by providing answers to their questions about banking and finance products.';
await squid.ai().agent('banking-copilot').updateInstructions(instruction);

コンテキスト​

コンテキストは、エージェントが質問に回答する際に参照する知識を指定し、Agent StudioのKnowledge Base機能と同じ役割を果たします。コンテキストを追加することで、基盤のAIモデルに含まれない特定のトピックに関する関連回答を、エージェントが提供できるようになります。

以下はシンプルなコード例ですが、追加するコンテキストはもっと複雑なものにすることも可能です。良いコンテキストの例としては、コードドキュメント、製品マニュアル、業務情報（例: 営業時間）やユーザー固有のデータなどが挙げられます。コンテキストの種類を組み合わせることで、ユーザーが必要とする情報を提供できる堅牢なナレッジベースを、AIエージェントのために構築できます。

ナレッジベースの作成​

エージェントのコンテキストを追加または更新するには、まずナレッジベースを作成して接続する必要があります。

まず、新しいナレッジベースを作成します

await squid.ai().knowledgeBase('banking-knowledgebase').upsertKnowledgeBase({
  description: 'This Knowledge Base contains information on card data',
  name: 'banking knowledgebase',
  embeddingModel: 'text-embedding-3-small',
  chatModel: 'gpt-4o',
});

コンテキストのアップサート​

ナレッジベースにコンテキストを追加するには、コンテキストとそのタイプを渡してupsertContext()メソッドを使用します。

upsertContext()メソッドはコンテキストIDを受け取ります。コンテキストIDを指定することで、後で変更する際にそのコンテキストへより簡単にアクセスできます。

const data = `Platinum Mastercard® Fair Credit, No annual fee. Flexible due dates...`;

await squid.ai().knowledgeBase('banking-knowledgebase').upsertContext({
  type: 'text',
  title: 'Credit Card Info',
  text: data,
  contextId: 'credit-cards',
});

また、upsertContexts()を使用して、複数のコンテキストの配列を一括でアップサートすることもできます。

const creditCard1 = `Platinum Mastercard® Fair Credit, No annual fee. Flexible due dates...`;
const creditCard2 = `Gold Mastercard®, $50 annual fee. Due dates once a month...`;

await squid
  .ai()
  .knowledgeBase('banking-knowledgebase')
  .upsertContexts([
    {
      type: 'text',
      title: 'Credit Card 1 Info',
      text: creditCard1,
      contextId: 'credit-cards1',
    },
    {
      type: 'text',
      title: 'Credit Card 2 Info',
      text: creditCard2,
      contextId: 'credit-cards2',
    },
  ]);

ナレッジベースをエージェントに接続する​

エージェントにナレッジベースへのアクセスを許可するには、agent.upsertメソッドを使用し、ナレッジベースIDとエージェントがナレッジベースを参照するタイミングの説明を提供します。

const agentData = await squid.ai().agent('banking-copilot').get();
await squid.ai().agent('banking-copilot').upsert({
  options: {
    connectedKnowledgeBases: [
      ...agentData.options.connectedKnowledgeBases ?? [],
      {
        knowledgeBaseId: 'banking-knowledgebase',
        description: 'Use for information on credit cards',
      },
    ],
  },
});

コンテキストのタイプ​

サポートされているコンテキストのタイプは2種類です: text と file。

テキストコンテキストは、コンテキストを含む文字列で作成されます:

const data = `Platinum Mastercard® Fair Credit, No annual fee. Flexible due dates...`;

await squid.ai().knowledgeBase('banking-knowledgebase').upsertContext({
  type: 'text',
  title: 'Credit Card Info',
  text: data,
  contextId: 'credit-cards',
});

ファイルコンテキストは、upsertContext()メソッドの第二引数としてFileオブジェクトを提供して作成されます。ファイルはSquidにアップロードされ、その内容からコンテキストが作成されます。

const file = {
  blob: contextBlob,
  fileName: 'CreditCardList.pdf',
};

await squid.ai().knowledgeBase('banking-knowledgebase').upsertContext(
  {
    type: 'file',
    contextId: 'credit-cards',
  },
  file
);
注意

コンテキストの長さは自由ですが、LLMプロンプトには文字数制限があるため、実際にはユーザーの問い合わせ時にコンテキストの一部しか含まれない場合があります。プロンプトを作成する際、Squidは提供されたコンテキストの中からユーザーの質問に最も関連性の高い部分を選択します。

コンテキストの取得​

すべてのコンテキストの一覧を取得するには、listContexts()メソッドを使用します。このメソッドは、contextIdを含むエージェントコンテキストオブジェクトの配列を返します:

await squid.ai().knowledgeBase('banking-knowledgebase').listContexts();

特定のコンテキスト項目を取得するには、コンテキストIDを渡してgetContext()メソッドを使用します:

await squid.ai().knowledgeBase('banking-knowledgebase').getContext('credit-cards');

コンテキストの削除​

コンテキストのエントリを削除するには、deleteContext()メソッドを使用します:

await squid.ai().knowledgeBase('banking-knowledgebase').deleteContext('credit-cards');

指定されたコンテキストIDに対してエントリがまだ作成されていない場合、このメソッドはエラーを返します。

コンテキストのメタデータ​

AIナレッジベースのコンテキストを追加または更新する際に、任意でコンテキストメタデータを提供することができます。メタデータは、キーがstring、number、またはbooleanの型を持つオブジェクトです。メタデータを追加することで、エージェントとやり取りする際に利用できる、コンテキストに関する追加情報を提供できます。以下の例は、PDFをコンテキストとして追加し、2組のキー/バリューをメタデータとして提供する例です:

const data = {
  blob: contextBlob,
  fileName: 'CreditCardList.pdf',
};

await squid
  .ai()
  .knowledgeBase('banking-knowledgebase')
  .upsertContext(
    {
      contextId: 'credit-cards',
      type: 'file',
      metadata: { company: 'Bank of America', year: 2023 },
    },
    file
  );

その後、metadataによるコンテキストのフィルタリングセクションに記載されているように、チャット時にメタデータを利用できます。

エージェントとの対話​

エージェントが作成されたら、質問やプロンプトの入力を開始できます。目的のAIエージェントでask()メソッドを使用してください。

const response = await squid
  .ai()
  .agent('banking-copilot')
  .ask('Which credit card is best for students?');

askオプション​

プロンプトに加えて、ask関数は任意のoptionsパラメータを受け取ることができます。このパラメータは、AIエージェントの構成に関するさまざまなプロパティを提供します。利用可能なオプションとそのデフォルト値の完全なリストについては、APIリファレンスドキュメントを参照してください。

await squid
  .ai()
  .agent('banking-copilot')
  .ask('Which credit card is best for students?', {
    chatId: 'my-chat',
    maxTokens: 4096,
    disableHistory: true,
    /* ... */
  });

メタデータによるナレッジベースコンテキストのフィルタリング​

コンテキストにメタデータを追加している場合、contextMetadataFilterForKnowledgeBaseチャットオプションを利用して、AIエージェントに特定のコンテキストのみを参照するよう指示することができます。フィルター条件を満たすコンテキストのみが、クライアントのプロンプトに対して使用されます。

以下の例では、メタデータのcompanyの値がBank of Americaと等しいコンテキストのみをフィルタリングしています:

await squid
  .ai()
  .agent('banking-copilot')
  .ask('Which Bank of America credit card is best for students?', {
    contextMetadataFilterForKnowledgeBase: {
      ["banking-knowledgebase"]: {company: { $eq: 'Bank of America' }, // filter context using metadata
    },
    /* ... */
  });

サポートされているメタデータフィルターは以下の通りです:

FilterDescriptionSupported types
$eq指定された値と等しいメタデータ値を持つベクトルと一致するnumber, string, boolean
$ne指定された値と等しくないメタデータ値を持つベクトルと一致するnumber, string, boolean
$gt指定された値より大きいメタデータ値を持つベクトルと一致するnumber
$gte指定された値以上のメタデータ値を持つベクトルと一致するnumber
$lt指定された値より小さいメタデータ値を持つベクトルと一致するnumber
$lte指定された値以下のメタデータ値を持つベクトルと一致するnumber
$in指定された配列内に含まれるメタデータ値を持つベクトルと一致するstring, number
$nin指定された配列に含まれないメタデータ値を持つベクトルと一致するstring, number
$exists指定されたメタデータフィールドが存在するベクトルと一致するboolean

AI Functions​

Squid AI Agentsは、特定のユースケースを処理し、より一貫性のある回答を生成するためにAI Functionsを活用できます。AI Functionsを使用するには、optionsパラメータのfunctions属性に、使用するAI Functionの名前を配列として渡します:

const response = await squid
  .ai()
  .agent('banking-copilot')
  .ask('What is my current credit limit?', {
    functions: ['AI_FUNCTION_NAME_1', 'AI_FUNCTION_NAME_2'],
  });

AI Functionsの詳細については、ドキュメントをご覧ください。AI Functionsを使用した例のアプリケーションについては、こちらのAIエージェントチュートリアルを確認してください.

エージェントのセキュリティ​

エージェントの作成やチャット機能を有効にするためにSquid Client SDKを使用する際、データのセキュリティ確保は非常に重要です。AIエージェントやそれを通じたチャットには機密情報が含まれる可能性があるため、不正な使用や変更を防ぐためにアクセスや更新を制限することが不可欠です。

AIエージェントのセキュリティについては、Securing AI agentsのドキュメントを参照してください。

エージェントAPIキー​

エージェントAPIキーは、エージェントのアクションを呼び出す際に、より細かいレベルのセキュリティを提供できます。詳細については、Agent API Keysのドキュメントをご覧ください.