ガードレール

AI agentの応答に制約を定義し、コンテンツポリシーを適用し、データ漏洩を防止し、プロフェッショナルなコミュニケーション基準を維持します。

ガードレールを使用する理由

AI agentは幅広い知識にアクセスでき、多様な応答を生成できます。制約がない場合、次のような可能性があります。

• Social Security番号やメールアドレスなどの機密ユーザーデータを開示する
• 本来の対象範囲外の質問に回答する
• プロフェッショナルではない、または不快な言葉を使用する

ガードレールを使用すると境界を定義でき、agentがトピックに沿った、プロフェッショナルでポリシーに準拠した状態を維持できます。単一のフラグでプリセットを有効にすることも、独自のカスタムポリシーを作成することもできます。

TypeScript

Backend code

await this.squid.ai().agent('support-agent').updateGuardrails({
  disablePii: true, // Blocks personally identifiable information
  professionalTone: true, // Enforces formal language
});

Python

Backend code

await self.squid.ai().agent('support-agent').update_guardrails({
    'disablePii': True,  # Blocks personally identifiable information
    'professionalTone': True,  # Enforces formal language
})

概要

ガードレールは、最優先でAI agentのsystem promptに挿入される、設定可能な制約です。ガードレールが有効な場合、agentはそれに応じて応答をフィルタリングするための具体的な指示を受け取ります。

ガードレールには2種類あります。

• プリセットガードレール - オンまたはオフに切り替え可能な4つの組み込みポリシー
• カスタムガードレール - プリセットでカバーされないポリシー用の自由形式テキスト指示

ガードレールは3つの方法で設定できます。

方法	最適な用途
Squid Console（Agent Studio）	クイックセットアップおよび非開発者ユーザー
Backend SDK	アプリケーションコードからのプログラムによる制御
REST API	外部システムまたは自動化パイプライン

ガードレールの仕組み

agentがメッセージを処理すると、有効なガードレールは、基盤となるLLMへ送信されるsystem prompt内に高優先度の指示として埋め込まれます。agentはこれらの指示を最高優先度で扱い、ユーザーへ返す前に、すべての有効なガードレールポリシーに準拠するよう応答をフィルタリングします。

基本概念

プリセットガードレール

ガードレール	キー	内容
不適切な表現フィルター	disableProfanity	不適切な表現、下品な言葉、攻撃的な用語をフィルタリングします。敬意を払い、中立的な言葉遣いを適用します。
PII保護	disablePii	SSN、銀行口座番号、住所、氏名、生年月日、メール、電話番号、パスポート／運転免許証番号、クレジットカード番号など、個人を特定できる情報の出力を防止します。
トピック制限	offTopicAnswers	定義された対象範囲内の質問にのみagentの応答を制限します。agentは対象範囲外の質問を丁寧に断ります。
プロフェッショナルな口調	professionalTone	明確かつ正確な言葉を使い、スラングやカジュアルな表現を避けながら、プロフェッショナルで礼儀正しく中立的な口調を維持します。

各プリセットはbooleanフラグです。有効にするにはtrue、無効にするにはfalseに設定します。

注記

disablePiiは、agentが書き出す内容を制御します。モデルに対して個人情報を回答に含めないよう指示しますが、ユーザーのprompt自体は引き続きモデルに届きます。モデルが認識する前に受信promptを拒否するには、prompt privacyを使用してください。両方を同時に有効にできます。

カスタムガードレール

カスタムガードレールでは、追加ポリシーを記述する自由形式テキストを受け付けます。プリセットでカバーされない、ドメイン固有のルールに使用してください。例：

• 「事実に関する主張を行う際は、必ず情報源を引用する」
• 「競合他社の製品について議論しない」
• 「スペイン語でのみ応答する」

マージ動作

updateGuardrailsメソッドは、新しい設定を既存の設定とマージし、置き換えることはありません。agentがすでにdisablePii: trueであり、updateGuardrails({ professionalTone: true })を呼び出した場合、両方のガードレールが有効なままになります。ガードレールを無効にするには、明示的にfalseに設定してください。

Studioでガードレールを設定する

Squid Consoleを通じてagentのガードレールを設定するには、次の手順に従います。

1. 左サイドバーのAgent Studioタブに移動します
2. 設定するagentを選択します
3. Settingsタブをクリックします
4. Agent Guardrailsセクションまでスクロールします
5. 4つのプリセットガードレールのオン／オフを切り替えます
6. （任意）テキストフィールドにカスタムガードレールポリシーを入力します

Backend SDKでガードレールを設定する

プリセットガードレールを更新する

updateGuardrailsを使用して、プリセットガードレールを有効または無効にします。設定は既存の値とマージされます。

TypeScript

Backend code

// Enable PII protection and professional tone
await this.squid.ai().agent('AGENT_ID').updateGuardrails({
  disablePii: true,
  professionalTone: true,
});

Python

Backend code

# Enable PII protection and professional tone
await self.squid.ai().agent('AGENT_ID').update_guardrails({
    'disablePii': True,
    'professionalTone': True,
})

4つのプリセットをすべて一度に有効にするには、次のようにします。

TypeScript

Backend code

await this.squid.ai().agent('AGENT_ID').updateGuardrails({
  disableProfanity: true,
  professionalTone: true,
  disablePii: true,
  offTopicAnswers: true,
});

Python

Backend code

await self.squid.ai().agent('AGENT_ID').update_guardrails({
    'disableProfanity': True,
    'professionalTone': True,
    'disablePii': True,
    'offTopicAnswers': True,
})

他のガードレールを維持したまま、特定のガードレールを無効にするには、次のようにします。

TypeScript

Backend code

// Disable profanity filter; other guardrails remain unchanged
await this.squid.ai().agent('AGENT_ID').updateGuardrails({
  disableProfanity: false,
});

Python

Backend code

# Disable profanity filter; other guardrails remain unchanged
await self.squid.ai().agent('AGENT_ID').update_guardrails({
    'disableProfanity': False,
})

カスタムガードレールを追加する

updateCustomGuardrailsを使用して、カスタムガードレールポリシーを設定します。

TypeScript

Backend code

await this.squid.ai().agent('AGENT_ID')
  .updateCustomGuardrails('Always cite sources when making factual claims.');

Python

Backend code

await self.squid.ai().agent('AGENT_ID').update_custom_guardrails(
    'Always cite sources when making factual claims.'
)

このメソッドを再度呼び出すと、以前のカスタムガードレールテキストが置き換えられます。

カスタムガードレールを削除する

deleteCustomGuardrailを使用して、カスタムガードレールポリシーを削除します。

TypeScript

Backend code

await this.squid.ai().agent('AGENT_ID').deleteCustomGuardrail();

Python

Backend code

await self.squid.ai().agent('AGENT_ID').delete_custom_guardrails()

これはカスタムガードレールのみを削除します。プリセットガードレールには影響しません。

REST APIを介してガードレールを設定する

すべてのAPI endpointは、Squid Cloudアプリケーションのbase URLを使用します。API URLの構築方法について詳しくは、API documentationを参照してください。

プリセットガードレールを更新する

POSTリクエストを送信して、プリセットガードレールを更新します。設定は、SDKのupdateGuardrailsと同様に、agentの既存ガードレールとマージされます。

POST /squid-api/v1/ai/agent/updateGuardrails

{
  "agentId": "your-agent-id",
  "guardrails": {
    "disablePii": true,
    "professionalTone": true,
    "offTopicAnswers": true,
    "disableProfanity": true
  }
}

カスタムガードレールを更新する

POST /squid-api/v1/ai/agent/updateCustomGuardrails

{
  "agentId": "your-agent-id",
  "customGuardrail": "Always cite sources when making factual claims."
}

カスタムガードレールを削除する

POST /squid-api/v1/ai/agent/deleteCustomGuardrails

{
  "agentId": "your-agent-id"
}

エラー処理

よくあるエラー

エラー	原因	解決策
Agent not found	指定されたagentIdが存在しない	Squid Consoleでagent IDを確認する
Unauthorized	API keyが無効、または存在しない	有効なapp API keyを使用していることを確認する
Cannot perform this operation on the built-in agent	組み込みagentのガードレールを変更しようとした	組み込みagentを変更する代わりにカスタムagentを作成する

動作に関する注意

• updateCustomGuardrailsは、指定したカスタムガードレール文字列が空の場合、変更せずにサイレントに返ります。agentが存在しない場合は、Agent not foundエラーをスローします。
• deleteCustomGuardrailは、agentが存在しない場合でもエラーを出さずにサイレントに返ります。この呼び出しは冪等です。カスタムガードレールが設定されていない状態で削除しても、エラーなく成功します。
• プリセットガードレールの値は単純なbooleanであり、コンテンツ検証は必要ありません。

ベストプラクティス

1. カスタムルールを作成する前に、まずプリセットを使用してください。 4つの組み込みガードレールは、最も一般的なコンプライアンス要件をカバーします。ドメイン固有のポリシーに対してのみカスタムガードレールを追加してください。
2. カスタムガードレールでは具体的に記述してください。 「安全にする」のような曖昧な指示よりも、「社内の価格計算式を開示しない」のような明示的なルールの方が効果的です。
3. 多層的な保護のためにガードレールを組み合わせてください。 disablePiiと、ドメインにおける追加のデータ処理ルールを指定するカスタムガードレールを併用してください。
4. ガードレールの動作をテストしてください。 ガードレールを有効にした後、各ポリシーをトリガーするよう設計されたpromptでagentをテストし、制約が想定どおりに機能していることを検証してください。
5. マージセマンティクスを忘れないでください。 updateGuardrailsの呼び出しは既存の設定とマージされます。ガードレールを無効にするには、明示的にfalseに設定する必要があります。