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

AI Agents と Agent API Keys のセキュリティ

@secureAiAgent デコレーターを使用して、特定の agent をセキュアにする関数であることを指定します。Agent API Keys を使うことでセキュリティメソッドをバイパスでき、App API Keys を不要にできます。​

Squid Client を使用して AI agents を作成し、チャットを有効化する際には、データのセキュリティが非常に重要です。AI agent およびそれらとのチャットには機密情報が含まれる可能性があるため、不正な利用や改ざんを防ぐために、アクセスと更新を制限することが不可欠です。

AI agent が public に設定されていない限り、アクセスはデフォルトで制限され、アクセス許可を設定する明示的なルールがないと動作しません。（ぜひ試してみてください！）

Squid には、セキュリティルールを設定するために利用できる @secureAiAgent デコレーターが用意されています。これらのルールは、不正なユーザーによる agent の更新や不正なチャットを防ぎ、データの整合性を保護します。

ヒント

AI agent をセキュアにする前に、セキュア対象の agent の public 設定が OFF に切り替わっていること、そして AI agent のセキュリティルール設定に必要となる backend のセットアップ が完了していることを確認してください。

チャットのセキュリティ​

チャットの権限を管理するには、@secureAiAgent デコレーターを使用します。すべてのユーザーが すべての agents に対してチャットできるようにするには、backend に次を追加します。

import { secureAiAgent, SquidService } from '@squidcloud/backend';

export class ExampleService extends SquidService {
  @secureAiAgent()
  allowChat(): boolean {
    return true;
  }
}

チャットを認証済みユーザーのみに制限するには、Squid backend の isAuthenticated() メソッドを使用します。このメソッドは、アクションを実行しようとしているクライアントが認証済みかどうかを示す boolean を返します。

@secureAiAgent()
allowChat(): boolean {
  return this.isAuthenticated();
}

ただし、すべての agents へのアクセスを一括で開放/遮断するのは範囲が広すぎるため、アクセスセキュリティを設定したい Agent ID を指定することを推奨します。
そのためには、AI agent の ID を @secureAiAgent デコレーターに渡します。

@secureAiAgent('AGENT_ID')

条件付きチェック​

API では、クライアントがクエリとともにさまざまな options を送信できます。これがロックダウンしたい対象になることがあります。

たとえば、クエリ options で、agent に設定されているものとは別の AI model を指定できます。これを禁止するには、このメソッドで options.model に値が与えられているかをチェックし、与えられている場合は失敗させます。

@secureAiAgent()
immutableModel(context: SecureAiAgentContext): boolean {
  if (context.options?.model !== undefined) {
    // Don't allow overriding the model that was configured for the agent.
    return false;
  }
  return this.isAuthenticated();
}

他にも多くの options があります。どこから始めればよいか不明な場合、最も安全な方法は options を一切許可しないことです。

@secureAiAgent()
immutableAgent(context: SecureAiAgentContext): boolean {
  const options = context.options || {};
  if (Object.keys(options).length > 0) {
    // Don't allow any options
    return false;
  }
  return this.isAuthenticated();
}

詳細は、ブロックまたは許可できる その他すべての options を参照してください。

Agent API Keys​

Agents は、App API Keys の代わりに使用できる独自の API keys を持てます。これにより agent のセキュリティルールをバイパスできます。App API Keys は、破壊的な操作を含むアプリケーション全体へのフルアクセスを提供できるため、セキュリティリスクを最小化する目的で、Agent にスコープされた API Key を使用すると便利です。

制限事項​

  • Agent API Keys は Agent ベースのアクションにのみ使用できるため、用途が制限されます。
  • App API Key が存在する場合、Agent API Keys は無視されます。

使用方法​

Agent API Key を使用するには、Agent Client を作成する際に options 配列の一部として渡します。

/**
 * Note the lack of App API Key when creating the Squid instance. This is important as passing an API Key here will cause the Agent API Key to be ignored.
 */
const squid = new Squid({
  appId: 'YOUR_APP_ID',
  region: 'YOUR_REGION',
  environmentId: 'dev',
  squidDeveloperId: 'YOUR_SQUID_DEVELOPER_ID',
});

const agentClient = await squid.ai().agent('banking-copilot', {
  apiKey: process.env.SQUID_AGENT_API_KEY,
});

API 呼び出しを直接行う場合は、x-squid-agent-api-key ヘッダーを使用して渡せます。

curl -X POST "https://console.us-east-1.aws.squid.cloud/openapi/squid-api/v1/ai/agent/ask" \
  -H "Content-Type: application/json" \
  -H "x-squid-agent-api-key: YOUR_AGENT_API_KEY" \
  -d '{
    "agentId": "lkj",
    "prompt": "What is a squid?"
  }'