AIエージェントの構築方法

Squid の client SDK を使って、永続的な指示、ナレッジベース、接続ツール、マルチエージェントのワークフローを備えたカスタムAIエージェントを構築します。

なぜ Squid でAIエージェントを構築するのか

アプリにAI機能を追加するには通常、LLM API、コンテキスト取得用のベクトルデータベース、tool-calling のロジック、会話メモリ、セキュリティルールをつなぎ合わせる必要があります。各パーツごとに統合作業が発生します。

Squid はこれらすべてを統合されたプラットフォームで扱います。指示と能力を持つエージェントを定義し、データソースやツールに接続し、単一のSDKを通じて対話します。Squid がプロンプト構築、コンテキスト取得、メモリ、オーケストレーションを管理するため、あなたは作りたい体験に集中できます。

仕組み

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

Squid ではAIエージェントに使用するLLMを選択でき、用途に最適なものを見つけられます。以下のLLMプロバイダは標準で利用できます。

また、AI connector を追加することで、追加のプロバイダにも接続できます。これにより、セルフホストモデル（例: Ollama, vLLM）、AWS Bedrock モデル、またはその他の OpenAI-compatible endpoint を利用できます。

エージェントの構築

エージェントは、AIワークフローにおける独自の人格（persona）や設定を表します。各エージェントは異なる persona／ユースケースのようなもので、独自の指示と能力のセットによって区別されます。この設計により、特定のエージェントに応じたカスタマイズされた応答をAIから引き出せます。

Note

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

エージェントの Upsert

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

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

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

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

エージェントの削除

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

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

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

モデルの更新

エージェントが使用するLLMモデルを変更するには、updateModel() を呼び出します。

Client code
await squid.ai().agent('banking-copilot').updateModel('claude-sonnet-4-6');

モデルは vendor のモデル名（例: 'gpt-4o', 'claude-sonnet-4-6', 'gemini-2.0-flash'）または、Ollama、AWS Bedrock、あるいは任意の OpenAI-compatible endpoint といった追加プロバイダ向けの integration-based model を指定できます。

Client code
await squid.ai().agent('banking-copilot').updateModel({
  integrationId: 'my-ollama',
  model: 'llama3',
});

ask() や chat() 呼び出し時に model オプションを使って、リクエスト単位でモデルを上書きすることもできます。詳細は Ask Options を参照してください。

エージェントの説明の設定

エージェントの人間が読める説明（description）を設定または更新するには、setAgentDescription() メソッドを使用します。このメソッドは説明のみを更新し、他のエージェント設定には影響しません。

Client code
await squid
  .ai()
  .agent('banking-copilot')
  .setAgentDescription(
    'Assists customer support staff with banking and finance questions',
  );

upsert() を使って、他のすべてのエージェント値と一緒に description を一括設定することもできます。ただし upsert() はエージェント設定全体を置き換えるため、含まれていないフィールドはクリアされます。

指示（Instructions）

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

指示の追加

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

Client 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）

コンテキストは、質問に答える際にどの知識を参照するかをエージェントに伝えるもので、Agent Studio における Knowledge Base 能力と同じです。コンテキストを追加することで、基盤となるAIモデルに含まれない特定トピックについても、関連性の高い回答を返せます。

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

ナレッジベースの作成

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

はじめに、vendor の embedding model を使って新しいナレッジベースを作成します。

Client code
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',
  metadataFields: [],
});

connector ID、モデル名、dimensions を含むオブジェクトを渡すことで、integration-based embedding model も利用できます。設定手順は OpenAI Compatible Embedding connector を参照してください。

Client code
await squid.ai().knowledgeBase('banking-knowledgebase').upsertKnowledgeBase({
  description: 'This Knowledge Base contains information on card data',
  name: 'banking knowledgebase',
  embeddingModel: {
    integrationId: 'my-embeddings',
    model: 'text-embedding-3-small',
    dimensions: 1536,
  },
  chatModel: 'gpt-4o',
  metadataFields: [],
});

コンテキストの Upsert

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

upsertContext() メソッドは context ID を受け取れます。context ID を指定すると、後で変更したいときにコンテキストへアクセスしやすくなります。

Client code
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() を使って、コンテキストの配列を upsert できます。

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

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

setAgentOptionInPath() を使って、他のエージェント設定に影響を与えずにエージェントに1つ以上のナレッジベースへのアクセス権を付与します。description は、各ナレッジベースを参照すべきタイミングをエージェントに伝えます。

Client code
await squid
  .ai()
  .agent('banking-copilot')
  .setAgentOptionInPath('connectedKnowledgeBases', [
    {
      knowledgeBaseId: 'banking-knowledgebase',
      description: 'Use for information on credit cards',
    },
  ]);

すべてのナレッジベースを切断するには、空配列を渡します。

Client code
await squid
  .ai()
  .agent('banking-copilot')
  .setAgentOptionInPath('connectedKnowledgeBases', []);

upsert() を使って、他のすべてのエージェント値と一緒に connected knowledge bases を一括設定することもできます。ただし upsert() はエージェント設定全体を置き換えるため、含まれていないフィールドはクリアされます。

ナレッジベースの結果に含まれる document metadata をエージェントに渡すには、エージェントオプションまたはリクエスト単位で includeMetadata を true にします。

Client code
await squid.ai().agent('banking-copilot').ask('Tell me about our credit cards', {
  includeMetadata: true,
});

コンテキストの種類

サポートされるコンテキストは text と file の2種類です。

Text コンテキストは、コンテキストを含む文字列から作成します。

Client code
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 コンテキストは、upsertContext() の第2引数として File オブジェクトを渡して作成します。ファイルは Squid にアップロードされ、その内容からコンテキストが作成されます。

Client code
const file = new File([contextBlob], 'CreditCardList.pdf', { type: 'application/pdf' });

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

Note

コンテキストは任意の長さにできます。ただし LLM のプロンプトには文字数制限があるため、実際にユーザーの問い合わせとともに含まれるのはコンテキストの一部のみになる場合があります。プロンプト構築時、Squid は提供されたコンテキストのうちユーザーの質問に最も関連性の高い部分を判断して取り込みます。

コンテキストの取得

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

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

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

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

コンテキストの削除

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

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

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

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

AIナレッジベースのコンテキストを追加または更新する際、任意でコンテキストの metadata を提供できます。metadata はオブジェクトで、キーの値は string、number、boolean 型にできます。metadata を追加すると、コンテキストに関する追加情報を持たせられ、エージェントとの対話時に利用できます。次の例では、PDF をコンテキストとして追加し、2つの key/value を metadata として付与しています。

Client code
const file = new File([contextBlob], 'CreditCardList.pdf', { type: 'application/pdf' });

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

その後、filtering context with metadata section に示すように、AIエージェントと chat する際に metadata を使用できます。

エージェントとの対話

エージェントを作成したら、質問したりプロンプトを与えたりする準備が整います。

`ask()` で完全なレスポンスを取得

ask() メソッドを使ってプロンプトを送信し、完全なレスポンスを文字列として受け取ります。

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

注釈（Annotations）付きのレスポンスを取得

askWithAnnotations() を使うと、レスポンスに加えて file annotations（例: 生成された画像やドキュメント）も受け取れます。

Client code
const { responseString, annotations } = await squid.ai().agent('banking-copilot').askWithAnnotations('Generate a comparison chart of our credit cards');

`chat()` でレスポンスをストリーミング

chat() メソッドを使うと、トークン単位でレスポンスをストリーミングできます。これは、トークンが到着するたびに累積レスポンスを emit する RxJS Observable<string> を返し、UIでリアルタイム応答を表示するのに最適です。

Client code
import { Subscription } from 'rxjs';

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

const subscription: Subscription = stream.subscribe({
  next: (accumulatedResponse) => {
    // Each emission contains the full response so far
    console.log(accumulatedResponse);
  },
  complete: () => {
    console.log('Response complete');
  },
  error: (err) => {
    console.error('Error:', err);
  },
});

chat() メソッドは、（voiceOptions を除き）ask() と同じ options を受け取り、さらにトークン間にわずかな遅延を入れて自然なタイピング効果を与える smoothTyping オプション（デフォルトは true）を追加で利用できます。

Ask Options

ask() と chat() はどちらも、リクエストを設定するための任意の options パラメータを受け取ります。利用可能なオプションの完全な一覧とデフォルト値は、API reference documentation を参照してください。

Client code
await squid.ai().agent('banking-copilot').ask('Which credit card is best for students?', {
  maxOutputTokens: 4096,
  temperature: 0.7,
  model: 'claude-sonnet-4-6',
});

メモリとチャット履歴

デフォルトでは、エージェントはセッション内の過去メッセージを記憶します。memoryOptions でこの挙動を制御できます。

Client code
const response = await squid
  .ai()
  .agent('banking-copilot')
  .ask('What did I ask earlier?', {
    memoryOptions: {
      memoryMode: 'read-write', // 'none' | 'read-only' | 'read-write'
      memoryId: 'user-123-session', // Unique ID for this conversation
      expirationMinutes: 60, // How long to keep the history
    },
  });

'none': 履歴を使用しません。各プロンプトは独立して回答されます。
'read-only': エージェントは過去メッセージを参照できますが、新しいメッセージは保存しません。
'read-write': エージェントは履歴を読み書きします（デフォルト挙動）。

memoryId は会話を識別します。リクエスト間で同じ memoryId を使うと同一会話が継続します。memory ID はチャット履歴へのアクセスを許可するため、access token と同等のセキュリティで取り扱ってください。

指定した会話の過去メッセージを取得するには getChatHistory() を使用します。

Client code
const messages = await squid.ai().agent('banking-copilot').getChatHistory('user-123-session');

レスポンス形式

responseFormat を使って、エージェントのレスポンス形式を制御します。

Client code
// Get a JSON response
const json = await squid.ai().agent('banking-copilot').ask('List our credit cards with their fees', {
  responseFormat: 'json_object',
});

// Get a response that strictly conforms to a JSON schema (Anthropic models)
const structured = await squid
  .ai()
  .agent('banking-copilot')
  .ask('Analyze the sentiment of this review', {
    model: 'claude-sonnet-4-6',
    responseFormat: {
      type: 'json_schema',
      schema: {
        type: 'object',
        properties: {
          sentiment: { type: 'string', enum: ['positive', 'negative', 'neutral'] },
          confidence: { type: 'number' },
        },
        required: ['sentiment', 'confidence'],
      },
    },
  });

利用可能な形式:

'text'（デフォルト）: プレーンテキストのレスポンス。
'json_object': モデルが有効なJSONを返そうとします。
{ type: 'json_schema', schema: ... }: 提供したJSON schemaにレスポンスが準拠することを保証する Structured output。現在は Anthropic モデルでサポートされています。

プロンプトにファイルを含める

fileUrls を使って、プロンプトの一部として画像やドキュメントを渡します。

Client code
const response = await squid
  .ai()
  .agent('banking-copilot')
  .ask('What does this document say?', {
    fileUrls: [
      {
        id: 'doc-1',
        type: 'document',
        purpose: 'context',
        url: 'https://example.com/statement.pdf',
        description: 'Customer bank statement',
      },
    ],
  });

各 file URL には id（リクエスト内で一意）、type（'image' または 'document'）、および purpose が必要です。

'context': ファイルはプロンプトに直接含まれ、AIが参照します。
'tools': ファイルは tool/function call の結果の一部として返されます。

リクエスト単位でモデルを上書き

単一リクエストに対して、エージェントのデフォルトモデルを上書きします。

Client code
const response = await squid.ai().agent('banking-copilot').ask('Summarize this data', {
  model: 'gpt-4o',
});

その他のオプション

Option	Type	Default	Description
`maxTokens`	`number`	Model max	Squid がモデルに送信できる最大 input tokens
`maxOutputTokens`	`number`	-	モデルが生成すべき最大 tokens
`temperature`	`number`	`0.5`	サンプリング温度（0-1）
`timeoutMs`	`number`	`240000`	リクエストのタイムアウト（ミリ秒）
`instructions`	`string`	-	エージェントのデフォルト指示に追記される追加指示
`guardrails`	`object`	-	リクエスト単位で guardrail settings を上書き
`disableContext`	`boolean`	`false`	このリクエストではナレッジベースのコンテキストをスキップ
`includeReference`	`boolean`	`false`	レスポンスにソース参照を含める
`reasoningEffort`	`string`	-	`'minimal'`, `'low'`, `'medium'`, または `'high'`（reasoning models 用）
`useCodeInterpreter`	`string`	`'none'`	`'llm'` で Python のコード実行を有効化（OpenAI と Gemini のみ）
`executionPlanOptions`	`object`	-	エージェントが行動前に計画を立てることを有効化

Metadata を使って Knowledge base のコンテキストをフィルタリング

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

次の例では、metadata の "company" が "Bank of America" に等しいコンテキストのみを含むようフィルタリングします。

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

サポートされる 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 を使って特定のユースケースに対応し、より一貫したレスポンスを生成できます。

エージェントに Functions を追加

setAgentOptionInPath() を使ってエージェントに AI functions を紐づけられます。このメソッドは function リストのみを更新し、他のエージェント設定には影響しません。

Client code
await squid
  .ai()
  .agent('banking-copilot')
  .setAgentOptionInPath('functions', ['getCreditLimit']);

function リストを更新するには、新しい function セットで setAgentOptionInPath() を再度呼び出します。空配列を渡すと全 functions が削除されます。upsert() を使って他のすべてのエージェント値と一緒に functions を一括設定することもできますが、upsert() はエージェント設定全体を置き換える点に注意してください。

Ask 時に Functions を渡す

または、functions オプションでリクエスト単位に AI function 名を渡せます。これはそのリクエストに限り、エージェントに保存された function リストを上書きします。

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

AI functions の詳細は、ドキュメントを参照してください。AI functions を使ったサンプルアプリについては、このAIエージェントチュートリアルを確認してください。

Connected Agents

Agents は他の agents にタスクを委譲でき、マルチエージェントのワークフローを実現します。connected agent は呼び出し可能な tool として親エージェントに現れ、親エージェントが「サブエージェントのほうがユーザー要求の特定部分に適している」と判断した場合に呼び出されます。

Connected Agents の設定

updateConnectedAgents() を使って、このエージェントに接続された agent のリストを設定します。description は、各 connected agent にいつ委譲すべきかを親エージェントに伝えます。

Client code
await squid.ai().agent('banking-copilot').updateConnectedAgents([
  {
    agentId: 'fraud-detection-agent',
    description: 'Call this agent when the user asks about suspicious transactions or potential fraud',
  },
]);

すべての agents を切断するには、空配列を渡します。

Client code
await squid.ai().agent('banking-copilot').updateConnectedAgents([]);

Ask 時に Connected Agents を渡す

connected agents はリクエスト単位でも指定でき、保存済みの設定を上書きします。

Client code
const response = await squid
  .ai()
  .agent('banking-copilot')
  .ask('Is this transaction suspicious?', {
    connectedAgents: [
      {
        agentId: 'fraud-detection-agent',
        description: 'Call this agent for fraud analysis',
      },
      {
        agentId: 'compliance-agent',
        description: 'Call this agent for regulatory compliance checks',
      },
    ],
  });

デフォルトでは、ネストされた agent 呼び出しは最大5階層まで再帰できます。quotas オプションで調整できます。

Client code
const response = await squid
  .ai()
  .agent('banking-copilot')
  .ask('Analyze this portfolio', {
    quotas: { maxAiCallStackSize: 3 },
  });

Connected Integrations

Agents はデータソースや外部サービスに接続でき、プロンプトへ回答する一環として、データベースへのクエリ、API 呼び出し、SaaS ツールとの連携が可能になります。

Connected Integrations の設定

setAgentOptionInPath() を使って、他のエージェント設定に影響を与えずにエージェントに connectors へのアクセス権を付与します。

Client code
await squid
  .ai()
  .agent('banking-copilot')
  .setAgentOptionInPath('connectedIntegrations', [
    {
      integrationId: 'my-postgres',
      integrationType: 'postgres',
      description: 'Use this database to look up customer account information',
    },
  ]);

description は、この integration を使うタイミングをエージェントが理解する助けになります。integrationType は Squid Console で設定した connector のタイプと一致している必要があります。

すべての integrations を切断するには、空配列で setAgentOptionInPath() を呼び出します。upsert() を使って他のすべてのエージェント値と一緒に connected integrations を一括設定することもできますが、upsert() はエージェント設定全体を置き換える点に注意してください。

Ask 時に Connected Integrations を渡す

connected agents と同様、integrations もリクエスト単位で指定できます。

Client code
const response = await squid
  .ai()
  .agent('banking-copilot')
  .ask('What are my recent transactions?', {
    connectedIntegrations: [
      {
        integrationId: 'my-postgres',
        integrationType: 'postgres',
        description: 'Customer transaction database',
      },
    ],
  });

Execution Planning

複数の tools、connected agents、または integrations を伴う複雑なタスクでは、execution planning を有効にできます。有効化すると、エージェントはまず実行するアクションの計画を作成してから、それを実行します。

Client code
const response = await squid
  .ai()
  .agent('banking-copilot')
  .ask('Compare our credit card offerings with competitor rates', {
    executionPlanOptions: {
      enabled: true,
      reasoningEffort: 'high', // 'minimal' | 'low' | 'medium' | 'high'
      allowClarificationQuestions: true, // Let the agent ask follow-up questions
    },
  });

必要に応じて、executionPlanOptions 内の model フィールドで、planning ステップ用に別のモデルを指定できます。

ステータス更新の監視

エージェントが tool calls、connected agents、または integrations を含む複雑なリクエストを処理する際、WebSocket を通じてリアルタイムのステータス更新を監視できます。

Client code
const statusUpdates = squid.ai().agent('banking-copilot').observeStatusUpdates();

statusUpdates.subscribe({
  next: (status) => {
    console.log(`[${status.title}] ${status.body}`);
  },
});

返される Observable は、エージェントが実行する各ステップを説明する title と body フィールドを持つ AiStatusMessage オブジェクトを emit します。

エラーハンドリング

よくあるエラー

Error	Cause	Solution
Agent not found	存在しない agent ID に対して `delete()`、`get()`、または他メソッドを呼び出した	まず `get()` を呼んで agent ID の存在を確認する、または `upsert()` でエージェント作成を確実にする
Context not found	存在しない context ID で `deleteContext()` または `getContext()` を呼び出した	削除または取得前に `listContexts()` で context ID を確認する
Request timeout	エージェント処理が `timeoutMs`（デフォルト: 4分）を超えた	options で `timeoutMs` を増やす、プロンプトを簡素化する、接続ツール数を減らす
Embedding model cannot be modified	既存ナレッジベースの `embeddingModel` を変更しようとした	代わりに、望む embedding model を使って新しいナレッジベースを作成する

Streaming でのエラー処理

chat() を使用する場合、エラーは Observable の error callback 経由で渡されます。

Client code
const stream = squid.ai().agent('banking-copilot').chat('Analyze this data');

stream.subscribe({
  next: (response) => console.log(response),
  error: (err) => {
    console.error('Agent error:', err.message);
  },
  complete: () => console.log('Done'),
});

ベストプラクティス

指示（Instructions）

指示は簡潔で直接的に保ちます。エージェントの役割と、すべきこと／すべきでないことを記述してください。
指示は事実（factual content）ではなく行動ルール（トーン、スコープ、レスポンススタイル）に使い、事実はナレッジベースに入れてください。
デプロイ前に Agent Studio の Test chat 機能を使って、指示変更をテストしてください。

ナレッジベース（Knowledge Bases）

ナレッジベースを接続するときは、説明的な description を使用してください。特に複数接続時、エージェントは description を手がかりに参照先を決めます。
大きなドキュメントはトピックごとに、焦点を絞ったナレッジベースへ分割してください。適切なコンテキスト選択のシグナルが強まります。
コンテキストに metadata を追加して、クエリ時のフィルタリングを可能にし、レスポンスのノイズを減らしてください。

マルチエージェント（Multi-Agent）ワークフロー

各 connected agent に、明確で具体的な description を付けてください。曖昧な description は誤った委譲につながります。
エージェント間の暴走的な再帰呼び出しを避けるため、quotas.maxAiCallStackSize を妥当な上限に設定してください。
複雑な multi-step タスクには executionPlanOptions を使用し、エージェントが実行前にアプローチを推論できるようにしてください。

パフォーマンス

体感速度が重要なユーザー向けの対話では chat() を使用してください。Streaming により、完全なレスポンスを待つのではなく、到着したトークンが順次表示されます。
ナレッジベースのコンテキストが不要なリクエストでは disableContext: true を設定してレイテンシを削減します。
会話履歴が不要なステートレスな単発リクエストには memoryOptions.memoryMode: 'none' を使用してください。

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

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

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

Agent API Keys

Agent API Keys は、Agent アクション呼び出し時に、よりきめ細かなセキュリティを提供できます。詳細は Agent API Keys ドキュメントを参照してください。

Squid の client SDK を使って、永続的な指示、ナレッジベース、接続ツール、マルチエージェントのワークフローを備えたカスタムAIエージェントを構築します。​

なぜ Squid でAIエージェントを構築するのか​

仕組み​

エージェントの構築​

エージェントの Upsert​

エージェントの削除​

モデルの更新​

エージェントの説明の設定​

指示（Instructions）​

指示の追加​

コンテキスト（Context）​

ナレッジベースの作成​

コンテキストの Upsert​

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

コンテキストの種類​

コンテキストの取得​

コンテキストの削除​

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

エージェントとの対話​

ask() で完全なレスポンスを取得​

注釈（Annotations）付きのレスポンスを取得​

chat() でレスポンスをストリーミング​

Ask Options​

メモリとチャット履歴​

レスポンス形式​

プロンプトにファイルを含める​

リクエスト単位でモデルを上書き​

その他のオプション​

Metadata を使って Knowledge base のコンテキストをフィルタリング​

AI Functions​

エージェントに Functions を追加​

Ask 時に Functions を渡す​

Connected Agents​

Connected Agents の設定​

Ask 時に Connected Agents を渡す​

Connected Integrations​

Connected Integrations の設定​

Ask 時に Connected Integrations を渡す​

Execution Planning​

ステータス更新の監視​

エラーハンドリング​

よくあるエラー​

Streaming でのエラー処理​

ベストプラクティス​

指示（Instructions）​

ナレッジベース（Knowledge Bases）​

マルチエージェント（Multi-Agent）ワークフロー​

パフォーマンス​

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

Agent API Keys​

Squid の client SDK を使って、永続的な指示、ナレッジベース、接続ツール、マルチエージェントのワークフローを備えたカスタムAIエージェントを構築します。

なぜ Squid でAIエージェントを構築するのか

仕組み

エージェントの構築

エージェントの Upsert

エージェントの削除

モデルの更新

エージェントの説明の設定

指示（Instructions）

指示の追加

コンテキスト（Context）

ナレッジベースの作成

コンテキストの Upsert

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

コンテキストの種類

コンテキストの取得

コンテキストの削除

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

エージェントとの対話

`ask()` で完全なレスポンスを取得

注釈（Annotations）付きのレスポンスを取得

`chat()` でレスポンスをストリーミング

Ask Options

メモリとチャット履歴

レスポンス形式

プロンプトにファイルを含める

リクエスト単位でモデルを上書き

その他のオプション

Metadata を使って Knowledge base のコンテキストをフィルタリング

AI Functions

エージェントに Functions を追加

Ask 時に Functions を渡す

Connected Agents

Connected Agents の設定

Ask 時に Connected Agents を渡す

Connected Integrations

Connected Integrations の設定

Ask 時に Connected Integrations を渡す

Execution Planning

ステータス更新の監視

エラーハンドリング

よくあるエラー

Streaming でのエラー処理

ベストプラクティス

指示（Instructions）

ナレッジベース（Knowledge Bases）

マルチエージェント（Multi-Agent）ワークフロー

パフォーマンス

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

Agent API Keys