AIエージェントの作り方

Squid の SDK を使用すると、さまざまな機能を利用して AI エージェントをカスタマイズできます。永続的な指示とコンテキストの追加、チャットセッションの管理、AI ロジックのカスタマイズなどを行い、特定のユースケースに最適化されたカスタム AI エージェントを作成できます。

仕組み

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

Squid では AI エージェントに使用する LLM を選択でき、ユースケースに最適なものを選べます。現在利用可能な LLM プロバイダーは次のとおりです。

現在サポートされていない特定のモデルが必要ですか？要件についてご相談いただくため、ぜひお問い合わせください！

エージェントの構築

エージェントは、AI ワークフローにおける明確な「人格」または「設定」を表します。各エージェントは、それぞれ独自の指示と能力によって区別される、異なるペルソナまたはユースケースのようなものです。この設計により、特定のエージェントに応じて AI からの応答をカスタマイズできます。

Note

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

エージェントの Upsert

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

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

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

isPublic パラメータは、指定したエージェントのチャット機能が security rules を設定せずにアクセス可能かどうかを決定します。

エージェントの削除

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

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

この関数は、指定したエージェント ID に対応するエージェントが存在しない場合にエラーになります。

Instructions

Instructions は、エージェントがプロンプトに どのように 応答し、質問に回答するかのルールを設定します。直接的でシンプルにし、エージェントの目的を説明してください。Instructions はテキストブロックとして提供します。

Instructions の追加

AI エージェントの Instructions を追加または編集するには、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);

Context

Context は、質問に答える際にエージェントが参照する知識のソースを指定します。これは Agent Studio における Knowledge Base 能力と同じです。Context を追加すると、基盤となる AI モデルに含まれていない可能性がある特定トピックについても、関連する回答を提供できるようになります。

以下はシンプルなコード例ですが、追加できる Context はより複雑にできます。Context の良い例としては、コードドキュメント、製品マニュアル、業務運用（例：営業時間）、ユーザー固有データなどのリソースがあります。Context の種類を組み合わせて堅牢なナレッジベースを作成し、ユーザーが必要とする情報を提供できるようにできます。

Knowledge Base の作成

エージェントの Context を追加または更新するには、まず Knowledge Base を作成して接続する必要があります。

まず、新しい Knowledge Base を作成します。

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',
});

Context の Upsert

Knowledge Base に Context を追加するには、upsertContext() メソッドを使用し、Context とその type を渡します。

upsertContext() メソッドは context ID を受け取ります。context ID を指定すると、後で変更したいときに Context へより簡単にアクセスできます。

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() を使用して Context の配列を upsert できます。

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',
    },
  ]);

Knowledge Base をエージェントに接続する

agent.upsert メソッドを使用し、knowledge base ID と、エージェントがいつ Knowledge Base を参照すべきかの説明を指定して、エージェントに Knowledge Base へのアクセス権を与えます。

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',
      },
    ],
  },
});

Context の種類

サポートされている Context の種類は text と file の 2 つです。

Text Context は、Context を含む文字列で作成します。

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',
});

File Context は、upsertContext() メソッドの第 2 引数として File オブジェクトを渡して作成します。その後、ファイルは Squid にアップロードされ、ファイル内容から Context が作成されます。

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

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

Note

Context はどれだけ長くても構いませんが、LLM のプロンプトには文字数制限があるため、ユーザーの問い合わせと一緒に含められる Context は一部のみになる場合があります。プロンプトを構築する際、Squid は提供された Context のうち、ユーザーの質問に最も関連性の高い部分を判断して使用します。

Context の取得

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

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

特定の Context アイテムを取得するには、context ID を渡して getContext() メソッドを使用します。

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

Context の削除

Context エントリを削除するには、deleteContext() メソッドを使用します。

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

このメソッドは、指定した context ID に対するエントリがまだ作成されていない場合にエラーになります。

Context Metadata

AI Knowledge Base の Context を追加または更新する際に、任意で Context Metadata を指定できます。Metadata はオブジェクトで、キーの値は string、number、boolean の型を取れます。Metadata を追加すると Context に関する追加情報が提供され、エージェントとのやり取り時に利用できます。次の例では、PDF を Context として追加し、Metadata として 2 つの key/value ペアを提供しています。

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 で context をフィルタリングするセクションに示すように、AI エージェントとのチャットで metadata を使用できます。

エージェントとの対話

エージェントを作成したら、質問したりプロンプトを与えたりする準備ができています。目的の AI エージェントに対して ask() メソッドを使用します。

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

Ask Options

プロンプトに加えて、ask 関数は任意の options パラメータを受け取れます。このパラメータは AI エージェントを設定するためのさまざまなプロパティを提供します。利用可能な options とそのデフォルト値の一覧は、API reference documentation を参照してください。

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

Metadata を使って Knowledge base Context をフィルタリングする

Context に metadata を追加している場合、contextMetadataFilterForKnowledgeBase チャット option を使用して、AI エージェントが特定の Context のみを参照するように指示できます。フィルタ要件を満たす Context のみがクライアントのプロンプトへの応答に使用されます。

次の例は、"company" の metadata 値が "Bank of America" と等しいものだけを含めるように Context をフィルタリングします。

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
    },
    /* ... */
  });

次の metadata フィルタがサポートされています。

Filter	Description	Supported types
$eq	指定した値と等しい metadata 値を持つベクターに一致します	number, string, boolean
$ne	指定した値と等しくない metadata 値を持つベクターに一致します	number, string, boolean
$gt	指定した値より大きい metadata 値を持つベクターに一致します	number
$gte	指定した値以上の metadata 値を持つベクターに一致します	number
$lt	指定した値より小さい metadata 値を持つベクターに一致します	number
$lte	指定した値以下の metadata 値を持つベクターに一致します	number
$in	指定した配列に含まれる metadata 値を持つベクターに一致します	string, number
$nin	指定した配列に含まれない metadata 値を持つベクターに一致します	string, number
$exists	指定した metadata フィールドを持つベクターに一致します	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 agent チュートリアルをご覧ください。

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

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

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

Agent API Keys

Agent API Keys は、Agent アクションを呼び出す際により細かな粒度のセキュリティを提供できます。詳細は Agent API Keys のドキュメントをご覧ください。

仕組み​

エージェントの構築​

エージェントの Upsert​

エージェントの削除​

Instructions​

Instructions の追加​

Context​

Knowledge Base の作成​

Context の Upsert​

Knowledge Base をエージェントに接続する​

Context の種類​

Context の取得​

Context の削除​

Context Metadata​

エージェントとの対話​

Ask Options​

Metadata を使って Knowledge base Context をフィルタリングする​

AI Functions​

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

Agent API Keys​

仕組み