AI agent の構築方法

Squid の client SDK を使用して、永続的な指示、knowledge bases、接続された tools、multi-agent workflows を備えたカスタム AI agents を構築します。

Squid で AI Agent を構築する理由

アプリに AI 機能を追加するには、通常、LLM API、コンテキスト取得用の vector database、tool-calling ロジック、conversation memory、security rules を組み合わせる必要があります。それぞれの要素に個別の統合作業が必要です。

Squid は、これらすべてを統合プラットフォームで処理します。指示と能力を備えた agent を定義し、データソースや tools に接続し、単一の SDK を通じて対話できます。Squid が prompt construction、context retrieval、memory、orchestration を管理するため、作成したい体験に集中できます。

仕組み

内部的には、agents は Large Language Model (LLM) を使用してユーザーの質問への回答を生成します。ユーザーが質問すると、永続的な指示と最も関連性の高いコンテキストが prompt の一部として LLM に渡され、ユーザーにコンテキスト化された回答が提供されます。

Squid では AI agent に使用する LLM を選択できるため、ユースケースに最適なものを見つけられます。以下の LLM providers が標準で利用できます。

AI connector を追加することで、追加の providers に接続することもできます。これにより、self-hosted models（例: Ollama、vLLM）、AWS Bedrock models、またはその他の OpenAI-compatible endpoint を使用できます。

Agent の構築

agent は、AI workflow における明確な personality や設定を表します。各 agent は、独自の指示と能力のセットによって区別される、異なる persona やユースケースのようなものです。この設計により、特定の agent に応じて AI からカスタマイズされた応答を得られます。

Note

以下の例では、Squid の SDKs を使用して agent を作成する方法を示します。Squid platform と SDKs を使用した開発に慣れていない場合は、fullstack development についてのドキュメントをお読みください。

Agent の Upsert

AI agent をプログラムで作成または更新するには、upsert() メソッドを使用し、作成または更新する agent ID を指定します。

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

agent を挿入するときは、agent が使用する model を示す model フィールドを持つ options オブジェクトを渡します。

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

Agent の削除

既存の agent を削除するには、delete() メソッドを使用します。

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

指定された agent ID の agent が存在しない場合、この関数はエラーになります。

Model の更新

agent が使用する LLM model を変更するには、updateModel() を呼び出します。

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

model には、vendor model name（例: 'gpt-5.5'、'claude-sonnet-5'、'gemini-3.6-flash'）または、Ollama、AWS Bedrock、任意の OpenAI-compatible endpoint など追加 providers 用の integration-based model を指定できます。

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

'claude-code' や 'codex' などの CLI agent model を選択して、長時間実行される tool-driven agentic asks を実行することもできます。

ask() または chat() を呼び出す際に、model option を使用して request ごとに model を上書きすることもできます。詳細は Ask Options を参照してください。

Agents と Resources の一覧表示

squid.ai() client は、アプリで定義されているすべてのものに対する discovery methods を公開します。

TypeScript	Python	Returns
`listAgents()`	`list_agents()`	すべてのエージェントとその設定
`listKnowledgeBases()`	`list_knowledge_bases()`	すべてのKnowledge Base
`listChatModels()`	`list_chat_models()`	利用可能なチャットモデル。非推奨のベンダーモデルを含めるには `includeDeprecated: true` を渡します。
`listFunctions()`	`list_functions()`	登録済みの AI functions

TypeScript
Python

Client code
const agents = await squid.ai().listAgents();
const models = await squid.ai().listChatModels({ includeDeprecated: false });

Client code
agents = await squid.ai().list_agents()
models = await squid.ai().list_chat_models(include_deprecated=False)

各メソッドは、以下の内容を含む records の配列を返します。

Agents (AiAgent): id、createdAt、updatedAt、description、isPublic、auditLog、および options（agent の完全な構成。model と接続された knowledge bases、integrations、functions を含む）。
Knowledge bases (AiKnowledgeBase): id、name、description、embeddingModel、chatModel、metadataFields、createdAt、updatedAt。connector syncs によって作成された knowledge bases には、追加の sync bookkeeping fields が含まれる場合があります。
Chat models (ModelIdSpec): modelId（model selection として渡す文字列）、displayName、description、および source（'vendor'、'connector'、または 'custom'）。Integration-based models には integrationId が含まれ、非推奨 models には calls がルーティングされる active model を示す replacedBy が含まれます。
AI functions (AiFunctionMetadata): serviceFunction（ServiceName:functionName）、description、および params（それぞれ name、type、description、required を含む）。Connector-provided functions には attributes.integrationType が含まれ、internal とフラグ付けされた entries は直接使用を意図していません。

Agent Description の設定

agent の人間が読みやすい説明を設定または更新するには、setAgentDescription() メソッドを使用します。これは他の agent configuration に影響を与えずに、description のみを更新します。

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

または、upsert() を使用して、description を他のすべての agent values と一緒に 1 回の呼び出しで設定できます。upsert() は agent configuration 全体を置き換えるため、含まれていないフィールドはクリアされることに注意してください。

Instructions

Instructions は、agent が prompts にどのように応答し、質問に答えるかのルールを設定します。直接的でシンプルにし、agent の目的を説明する必要があります。Instructions はテキストブロックとして提供されます。

Instructions の追加

AI agent に instructions を追加または編集するには、updateInstructions() メソッドを使用し、instruction data を文字列として渡します。

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

Connected Knowledge Bases

Knowledge bases は、agent が質問に回答する際に参照する検索可能なコンテキストを保存します。knowledge base を作成し、その context と metadata を管理するには、Knowledge Bases documentation を参照してください。

Knowledge Base を Agent に接続する

他の agent configuration に影響を与えずに agent が 1 つ以上の knowledge bases にアクセスできるようにするには、setAgentOptionInPath() を使用します。description は、各 knowledge base をいつ参照すべきかを agent に伝えます。

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

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

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

upsert() を使用して、接続された knowledge bases を他のすべての agent values と一緒に 1 回の呼び出しで設定することもできます。upsert() は agent configuration 全体を置き換えるため、含まれていないフィールドはクリアされることに注意してください。

各 connected knowledge base entry は、以下のフィールドをサポートします。

Field	Type	Required	Description
`knowledgeBaseId`	`string`	Yes	接続するKnowledge Base
`description`	`string`	Yes	このKnowledge Baseをいつ参照すべきかをエージェントに伝えます
`includeMetadata`	`boolean`	No	エージェントに提供される検索結果にドキュメントmetadataを含めます。省略した場合は非推奨のask単位 `includeMetadata` オプション（デフォルトは `true`）にフォールバックします。metadataを除外するには明示的に `false` を設定してください。
`enableMetadataInspection`	`boolean`	No	このKnowledge Baseのmetadataフィールド値を列挙・検索するツールをエージェントに与えます。デフォルトは `false`。詳細は agent-driven metadata filtering を参照してください。

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

ask-level の includeMetadata option は引き続き機能しますが、per-knowledge-base flag の使用が推奨されており、非推奨です。

Search Modes と Spreadsheets

knowledge base search tool により、agent は query ごとに retrieval mode を選択できます。knowledge base の backend がサポートする内容に応じて、'vector'（semantic）、'keyword'（IDs や error codes など正確な tokens に最適）、または 'hybrid' を選択します。Keyword search を参照してください。

接続された knowledge base に spreadsheet files が含まれている場合、agent には querySpreadsheetsWithAi tool も提供されます。これは取得された summaries に依存するのではなく、アップロードされた files に対して Python を実行することで、正確な回答（counts、sums、lookups、files 間の comparisons）を計算します。Spreadsheet Files を参照してください。

Agent と対話する

agent が作成されたら、質問をしたり prompts を与えたりする準備が整います。

`ask()` で完全な Response を取得する

ask() メソッドを使用して prompt を送信し、完全な response を文字列として受け取ります。

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

Annotations 付きで Responses を取得する

askWithAnnotations() を使用して、response と file annotations（例: generated images や documents）を受け取ります。

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

`chat()` で Responses を Streaming する

chat() メソッドを使用して、responses を token ごとに streaming します。これは RxJS Observable<string> を返し、各 token が到着するたびに蓄積された response を emit します。UI で real-time responses を表示するのに最適です。

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() メソッドは、ask() と同じ options（voiceOptions を除く）に加えて、自然なタイピング効果のために tokens 間にわずかな遅延を追加する smoothTyping option（既定値は true）を受け取ります。

Ask Options

ask() と chat() はどちらも、request を構成するための任意の options パラメーターを受け取ります。利用可能な 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',
});

Memory と Chat History

既定では、agents は session 内の以前の messages を記憶します。この動作を制御するには 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': 履歴は使用されません。各 prompt は独立して回答されます。
'read-only': agent は過去の messages を参照できますが、新しいものは保存しません。
'read-write': agent は履歴を読み書きします（既定の動作）。

memoryId は conversation を識別します。requests 間で同じ memoryId を使用すると、同じ conversation が継続されます。memory IDs は chat history へのアクセスを許可するため、access tokens と同じレベルのセキュリティで扱ってください。

指定された conversation の過去の messages を取得するには、getChatHistory() を使用します。

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

Response Format

responseFormat を使用して agent の response format を制御します。

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

利用可能な formats:

'text'（既定）: Plain text response。
'json_object': model は有効な JSON を返そうとします。
{ type: 'json_schema', schema: ... }: 提供された JSON schema に response が準拠することを保証する structured output。vendor chat models（Anthropic、OpenAI、Gemini、Grok）でサポートされています。schema は model の provider に送信され、その schema に decoding が制約されるため、response は schema と完全に一致し、再検証する必要はありません。

provider が schema を拒否した場合、provider 自身の diagnostic を含む 400 として返されます。protocol が schema をまったく運べない models は、要求された形状なしで回答するのではなく、STRUCTURED_OUTPUT_NOT_SUPPORTED で request を拒否します。これは CLI agent models と custom @llmService 経由で提供される models に適用されます。その場合は 'json_object' を使用し、prompt で形状を説明してください。

integration-based model の場合、schema が尊重されるかどうかは integration の背後にある provider に依存します。provider をまたいで動作する 1 つの回答が必要な場合は 'json_object' に fallback してください。

Prompt に Files を含める

fileUrls を使用して、images または documents を prompt の一部として渡します。

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（request ごとに一意）、type（'image' または 'document'）、および purpose が必要です。

'context': file は AI が参照できるように prompt に直接含まれます。
'tools': file は tool/function call result の一部として返されます。

fileName（任意）も設定できます。これは model がその file を参照するための名前を与え、URL path に拡張子がない場合は file extension も提供します。

Spreadsheet files（.csv、.tsv、.xlsx、.xlsm、.xls、.xlsb）は特別に処理されます。添付された各 spreadsheet について、agent はその file に対して Python を実行して質問に答える tool を受け取るため、lookups と aggregations は実際の cell values から計算されます。Spreadsheets は file extension によって認識されます。extension は fileName から取得され、fileName がない場合は query string を無視した URL path から取得されます。そのため、.xlsx?signature=... で終わる signed URL は追加設定なしで検出されます。URL path 自体に extension がない場合（例: opaque download endpoint）は fileName を設定してください。

Client code
const response = await squid
  .ai()
  .agent('banking-copilot')
  .ask('What was the total revenue in Q2?', {
    fileUrls: [
      {
        id: 'sales-1',
        type: 'document',
        purpose: 'context',
        url: downloadUrl, // path has no file extension
        fileName: 'sales.xlsx',
      },
    ],
  });

Request ごとに Model を上書きする

単一の request について agent の default model を上書きします。

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

Additional Options

Option	Type	Default	Description
`maxTokens`	`number`	Model max	Squid が model に送信できる最大 input tokens
`maxOutputTokens`	`number`	-	model が生成する最大 tokens
`temperature`	`number`	`0.5`	Sampling temperature（0-1）
`timeoutMs`	`number`	`240000`	request timeout（milliseconds）
`instructions`	`string`	-	agent の default instructions に追加される追加 instructions
`guardrails`	`object`	-	request ごとに guardrail settings を上書き
`disableContext`	`boolean`	`false`	この request で knowledge base context をスキップ
`includeReference`	`boolean`	`false`	response に source references を含める
`reasoningEffort`	`string`	-	`'minimal'`、`'low'`、`'medium'`、または `'high'`（reasoning models 用）
`useCodeInterpreter`	`string`	`'none'`	Python code execution を有効にするには `'llm'`（OpenAI と Gemini のみ）
`executionPlanOptions`	`object`	-	agent が実行前に計画することを有効化

Metadata で Context を Filtering する

context に metadata を追加している場合、contextMetadataFilterForKnowledgeBase chat option を使用して、AI agent に特定の contexts のみを参照するよう指示できます。filter requirement を満たす contexts のみが、client prompt への応答に使用されます。

次の例では、metadata value "company" が "Bank of America" と等しい contexts のみを含めるようにフィルタリングします。

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

サポートされる filter operators の完全な一覧、$and と $or を使用した filters の組み合わせ、agents が独自に filters を構築する方法については、Filtering Knowledge Base Context with Metadata を参照してください。

AI Functions

Squid AI Agents は、AI functions を使用して、特定のユースケースを処理し、より一貫した responses を作成できます。

Agent に Functions を追加する

setAgentOptionInPath() を使用して AI functions を agent に関連付けられます。これは他の agent configuration に影響を与えずに function list のみを更新します。

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

function list を更新するには、新しい functions のセットで setAgentOptionInPath() を再度呼び出します。空の配列を渡すとすべての functions が削除されます。upsert() を使用して functions を他のすべての agent values と一緒に 1 回の呼び出しで設定することもできますが、upsert() は agent configuration 全体を置き換えることに注意してください。

Ask 時に Functions を渡す

または、functions option を使用して request ごとに AI function names を渡します。これにより、その request について agent に保存されている function list が上書きされます。

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 agent tutorial を確認してください。

Connected Agents

Agents は tasks を他の agents に委任でき、multi-agent workflows を実現します。connected agent は、parent agent がユーザーの request の特定部分を処理するのに sub-agent が最適だと判断した場合に呼び出せる callable tool として表示されます。

Connected Agents の構成

この agent に接続する agents の一覧を設定するには、updateConnectedAgents() を使用します。description は、各 connected agent にいつ委任するかを parent 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 を渡す

request ごとに 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',
      },
    ],
  });

既定では、nested agent calls は最大 5 レベルまで再帰できます。これは quotas option を使用して調整できます。

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

Connected Integrations

Agents はデータソースや外部サービスに接続できるため、prompt に回答する一環として databases に query したり、APIs を呼び出したり、SaaS tools と対話したりできます。

Connected Integrations の構成

他の agent configuration に影響を与えずに agent が connectors にアクセスできるようにするには、setAgentOptionInPath() を使用します。

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 をいつ使用するかを agent が理解するのに役立ちます。integrationType は Squid Console で構成された connector の type と一致している必要があります。

すべての integrations を切断するには、空の配列で setAgentOptionInPath() を呼び出します。upsert() を使用して connected integrations を他のすべての agent values と一緒に 1 回の呼び出しで設定することもできますが、upsert() は agent configuration 全体を置き換えることに注意してください。

Ask 時に Connected Integrations を渡す

connected agents と同様に、integrations も request ごとに指定できます。

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 を含む複雑な tasks では、execution planning を有効にできます。有効にすると、agent は実行前にまず取るべき actions の計画を作成します。

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 step に別の model を任意で指定できます。

ステータス更新の観測

agent が tool calls、connected agents、または integrations を含む複雑な request を処理する際、WebSocket 経由で real-time status updates を監視できます。

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

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

返される Observable は、agent が行う各 step を説明する title と body fields を持つ AiStatusMessage objects を emit します。

Title はエージェントが実行しているステップの種類を示します。たとえば、通常の knowledge base search は Accessing Knowledge Base を報告し、knowledge graph のナビゲーションは Querying Knowledge Base Graph を、literal text scan は Searching Knowledge Base Text を報告するため、chat UI はそれぞれを独立したステップとして表示できます。

observeStatusUpdates() は optional な job ID も受け取ります。observeStatusUpdates(jobId) はその特定の request の更新のみを emit するため、CLI agent model の実行など、単一の長時間実行される ask を追跡する場合に便利です。引数なしの場合は、エージェントのすべての status updates を emit します。

Agent Revisions

agent configuration へのすべての変更は、自動的に revision を記録します。agent の作成は created revision を記録し、各更新（upsert()、updateModel()、updateInstructions()、setAgentOptionInPath() を含む）は updated を記録し、agent の削除は最後の状態を保持する最終的な deleted revision を記録します。設定は不要です。

Revisions の一覧表示

agent の完全な履歴を新しい順に取得するには、listRevisions() を使用します。

TypeScript
Python

Client code
const { revisions } = await squid.ai().agent('banking-copilot').listRevisions();
console.log(revisions[0].revisionNumber, revisions[0].action);

Client code
revisions = await squid.ai().agent('banking-copilot').list_revisions()
print(revisions[0]['revisionNumber'], revisions[0]['action'])

各 revision には以下が含まれます。

Field	Type	Description
`agentId`	`string`	この revision が属するエージェント
`revisionNumber`	`number`	変更ごとにインクリメントされる連番
`action`	`'created' \| 'updated' \| 'deleted'`	この revision のトリガーとなった変更
`createdAt`	`Date`	revision が記録された日時
`agentSnapshot`	`AiAgent`	revision 時点でのエージェント設定全体のスナップショット

個別の change description はありません。何が変わったかを確認するには、連続する snapshots を比較します（Squid Console がこれを行います）。

Revisions の復元と削除

restoreRevision() を使用して、agent を以前の revision に復元します。

TypeScript
Python

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

Client code
await squid.ai().agent('banking-copilot').restore_revision(3)

復元は非破壊的です。現在の状態がまず新しい revision として保存され、その後 agent の configuration が snapshot に置き換えられます。履歴は増えるだけなので、restore 自体も取り消せます。deleted revision は復元できません。

単一の revision を完全に削除するには、deleteRevision() を使用します。

TypeScript
Python

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

Client code
await squid.ai().agent('banking-copilot').delete_revision(3)

完全な method signatures は TypeScript と Python の reference docs にあります。

revisions を視覚的に閲覧することもできます。Squid Console の agent page には Revisions tab があり、各 revision で何が変更されたかが表示され、restore と delete actions を実行できます。

Audit Log

configuration revisions とは別に、各 agent は実行時の呼び出しに関する audit log を保持します。これには user prompt、tool と integration calls、knowledge base searches、final response、token usage が含まれます。

logging は agent の auditLog フィールドで制御され、新しい agents では既定で有効です。console で切り替えるか、upsert() に含めて切り替えます。

TypeScript
Python

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

Client code
await squid.ai().agent('banking-copilot').upsert(
    is_public=True,
    audit_log=False,
    options={'model': 'gpt-5.5'},
)

log の読み取りは console 機能です。Squid Console の agent page で Audit Log tab を開きます。log entries は SDK 経由では公開されません。

Error Handling

Common Errors

Error	Cause	Solution
Agent not found	存在しない agent ID に対して `delete()`、`get()`、またはその他の methods を呼び出している	まず `get()` を呼び出して agent ID が存在することを確認するか、`upsert()` を使用して agent が作成されるようにします
Context not found	存在しない context ID で `deleteContext()` または `getContext()` を呼び出している	削除または取得する前に `listContexts()` を使用して context ID を確認します
Request timeout	agent が構成済みの `timeoutMs`（既定: 4 minutes）より長くかかっている	options で `timeoutMs` を増やす、prompt を簡素化する、または connected tools の数を減らします
Embedding model cannot be modified	既存の knowledge base の `embeddingModel` を変更しようとしている	代わりに目的の embedding model で新しい knowledge base を作成します

Streaming での Errors の処理

chat() を使用する場合、errors は 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'),
});

Best Practices

Instructions

instructions は簡潔かつ直接的に保ちます。agent の役割と、何をすべきか（またはすべきでないか）を説明します。
factual content ではなく、behavioral rules（tone、scope、response style）に instructions を使用します。factual content は代わりに knowledge bases に入れます。
デプロイ前に Agent Studio の Test chat 機能を使用して、instructions の変更をテストします。

Knowledge Bases

knowledge bases を接続する際は、わかりやすい description values を使用します。description は、特に複数が接続されている場合に、agent がどの knowledge base を参照するかを判断する方法です。

knowledge base content と metadata の構造化に関するガイダンスについては、knowledge base best practices を参照してください。

Multi-Agent Workflows

各 connected agent に明確で具体的な description を与えます。曖昧な descriptions は誤った delegation につながります。
agents 間で runaway recursive calls が発生しないように、quotas.maxAiCallStackSize を妥当な limit に設定します。
複雑な multi-step tasks では、agent が行動前に approach について推論できるように executionPlanOptions を使用します。

Performance

perceived speed が重要な user-facing interactions では chat() を使用します。Streaming は完全な response を待つのではなく、tokens が到着した時点で表示します。
request に knowledge base context が不要な場合は、latency を減らすために disableContext: true を設定します。
conversation history を必要としない stateless な one-off requests では、memoryOptions.memoryMode: 'none' を使用します。

Agent を保護する

Squid Client SDK を使用して agents を作成し chatting を有効にする際、データを保護することは非常に重要です。AI agent とそれらで行われる chats には機密情報が含まれる可能性があるため、不正な使用や変更を防ぐためにアクセスと更新を制限することが不可欠です。

AI agent の保護について学ぶには、Securing AI agents documentation を確認してください。

Agent API Keys

Agent API Keys は、Agent actions を呼び出す際に、より細かなレベルの security を提供できます。詳細については、Agent API Keys documentation を参照してください。

Squid の client SDK を使用して、永続的な指示、knowledge bases、接続された tools、multi-agent workflows を備えたカスタム AI agents を構築します。​

Squid で AI Agent を構築する理由​

仕組み​

Agent の構築​

Agent の Upsert​

Agent の削除​

Model の更新​

Agents と Resources の一覧表示​

Agent Description の設定​

Instructions​

Instructions の追加​

Connected Knowledge Bases​

Knowledge Base を Agent に接続する​

Search Modes と Spreadsheets​

Agent と対話する​

ask() で完全な Response を取得する​

Annotations 付きで Responses を取得する​

chat() で Responses を Streaming する​

Ask Options​

Memory と Chat History​

Response Format​

Prompt に Files を含める​

Request ごとに Model を上書きする​

Additional Options​

Metadata で Context を Filtering する​

AI Functions​

Agent に Functions を追加する​

Ask 時に Functions を渡す​

Connected Agents​

Connected Agents の構成​

Ask 時に Connected Agents を渡す​

Connected Integrations​

Connected Integrations の構成​

Ask 時に Connected Integrations を渡す​

Execution Planning​

ステータス更新の観測​

Agent Revisions​

Revisions の一覧表示​

Revisions の復元と削除​

Audit Log​

Error Handling​

Common Errors​

Streaming での Errors の処理​

Best Practices​

Instructions​

Knowledge Bases​

Multi-Agent Workflows​

Performance​

Agent を保護する​

Agent API Keys​

Squid の client SDK を使用して、永続的な指示、knowledge bases、接続された tools、multi-agent workflows を備えたカスタム AI agents を構築します。

Squid で AI Agent を構築する理由

仕組み

Agent の構築

Agent の Upsert

Agent の削除

Model の更新

Agents と Resources の一覧表示

Agent Description の設定

Instructions

Instructions の追加

Connected Knowledge Bases

Knowledge Base を Agent に接続する

Search Modes と Spreadsheets

Agent と対話する

`ask()` で完全な Response を取得する

Annotations 付きで Responses を取得する

`chat()` で Responses を Streaming する

Ask Options

Memory と Chat History

Response Format

Prompt に Files を含める

Request ごとに Model を上書きする

Additional Options

Metadata で Context を Filtering する

AI Functions

Agent に Functions を追加する

Ask 時に Functions を渡す

Connected Agents

Connected Agents の構成

Ask 時に Connected Agents を渡す

Connected Integrations

Connected Integrations の構成

Ask 時に Connected Integrations を渡す

Execution Planning

ステータス更新の観測

Agent Revisions

Revisions の一覧表示

Revisions の復元と削除

Audit Log

Error Handling

Common Errors

Streaming での Errors の処理

Best Practices

Instructions

Knowledge Bases

Multi-Agent Workflows

Performance

Agent を保護する

Agent API Keys