外部LLM送信前のマスキング

/agent/run・/agent/runs は、リクエストごとに redactionPolicyId を指定することで、外部の LLM・embedding プロバイダへ送る前に会話履歴・検索クエリ・検索結果をマスキングできます。

redactionPolicyId を指定しない場合（省略、または null）はマスキングを行わず、入力はそのまま外部プロバイダへ送信されます。これは明示された API の契約であり、設定不備時に安全側へ倒れる（自動でマスキングされる）動作ではありません。マスキングが必要なリクエストでは必ず redactionPolicyId を指定してください。

マスキングの対象

redactionPolicyId を指定すると、次のすべてが対象になります。

会話履歴の全ロール（user / assistant / system / developer / tool / activity / reasoning）
文字列 content、マルチモーダル content の text、辞書内の文字列、ツール呼び出し引数（JSON）内の文字列、文字列 metadata と参照 URL
親 run から復元した過去の会話履歴（run ごとに、そのとき指定したポリシーで再マスキングされます）
ナレッジベース検索のクエリと検索結果（本文・タイトル・URL）
Google Web 検索へ送るクエリと、後続の外部 LLM へ渡す検索結果（本文・タイトル・URL）
外部 Iceberg テーブルのスキーマ・クエリ結果
エージェントが使うその他すべてのツールの実行結果

この機能は、外部プロバイダへ送るコピーだけをマスキングします。ダッシュボードや agent_runs に保存される内容、RUN_STARTED イベントは原文のままです。復元用のマッピングは保存されません。外部プロバイダへ送るコピーから除外されるもの（マスキングではなく削除）:

forwardedProps
state / tools / context / resume

これらは外部プロバイダへ渡らないため、マスキングせず削除します（マスキングしても外部へは渡らずコストだけが増え、一方で処理対象から外すと原文が残るため）。原文はダッシュボードや agent_runs 側では保持されます。対象外:

システムプロンプト

ローカルのマスキング処理で検査できない入力（画像・音声などのインラインバイナリ、未対応のメッセージ種別、未知の追加フィールド）は、原文のまま送信せずエラーになります。

検出する分類

コード	置換ラベル	内容
`N`	`[氏名]`	氏名
`T`	`[電話番号]`	電話番号
`E`	`[メールアドレス]`	メールアドレス
`A`	`[住所]`	番地を含む住所
`I`	`[ID]`	マイナンバー・免許証番号等の公的 ID
`C`	`[カード番号]`	クレジットカード番号
`P`	`[個人情報]`	その他の個人を特定できる情報
`K`	`[認証情報]`	API key、password、Bearer / access / refresh token、Cookie / session、接続文字列の password、秘密鍵
`B`	`[業務機密]`	ポリシーごとに定義された業務機密

組み込みポリシーで有効になる分類はポリシーごとに決まります。テナントポリシーでは9分類をすべて有効にし、テナント管理者が変更できるのは B（業務機密）の定義だけです。PIIや認証情報の分類を無効化することはできません。入力した定義は分類用データとして安全なJSON境界へ置かれ、system instructionや出力schemaを変更する自由記述プロンプトとしては扱われません。

テナントポリシーを管理する

管理APIは All roleのAPIキー専用です。App roleのAPIキーやDashboardのBearer認証では、一覧取得を含む管理操作を実行できません。一方、ACTIVEにしたポリシーは同じテナントのApp roleのAPIキーからも Agentの redactionPolicyId として利用できます。ポリシーは DRAFT → ACTIVE → ARCHIVED の順で管理します。本文は上書きせず、新しい版を追記します。 ACTIVE切替後も実行中のrunは開始時の版を使い続け、切替後に開始したrunだけが新しい版を使います。

ポリシー本文はサービスに保存されます。description、include、exclude、examplesには実在する秘密情報や個人情報を入れず、必ず合成データを使ってください。一度ACTIVEにした版は ARCHIVEDにしてもhard deleteできません。その名前もテナント上限20件に数え続けられるため、新しい定義には可能な限り同じ名前の新しい版を作成してください。

1. CLI schemaを確認する

APIキーはコマンドラインへ書かず、QAIP_API_KEY 環境変数で渡してください。ポリシー本文もshell引数へ直書きせず、権限を制限した一時JSON fileか標準入力を使います。

export QAIP_BASE_URL="https://api.example.com/api/v1"
read -s QAIP_API_KEY && export QAIP_API_KEY

qaip schema redaction-policies

2. DRAFTを検証・作成する

policy.json は chmod 600 したfileとして用意します。enabledCategories、version、statusはサーバーが決めるため入力しません。

policy.json

{
  "name": "internal-contracts",
  "description": "社内契約情報向け",
  "businessConfidential": {
    "definition": "未公開の契約・価格・計画に関する情報",
    "include": [{ "text": "契約金額", "mode": "value_clause" }],
    "exclude": ["公開済みの価格表"],
    "examples": ["架空会社Aとの年間契約額は3,200万円"]
  }
}

qaip api redaction-policies.validate --json @policy.json --dry-run
qaip api redaction-policies.validate --json @policy.json

qaip api redaction-policies.create --json @policy.json --dry-run
qaip api redaction-policies.create --json @policy.json

同じ正規化済みDRAFTの再送は同じ版を返します。異なるDRAFTが残っている場合は、既存本文を上書きせず 409 DRAFT_ALREADY_EXISTS になります。

3. ACTIVEにする

初回の切替ではACTIVE版がないことをCASで指定します。cas.json もfileまたは標準入力で渡します。

cas.json

{ "expectedActiveVersion": null }

qaip api redaction-policies.activate-version \
  --name internal-contracts --version 1 --json @cas.json --dry-run
qaip api redaction-policies.activate-version \
  --name internal-contracts --version 1 --json @cas.json --yes

初回リリースでは、テナント提供の評価ケースはactivateの必須条件ではありません。definitionの形式と安全性は同期検証しますが、業務上の検出品質は利用者側でも合成データで確認してください。

4. Agentから利用する

{
  "runId": "6a5c8f1e-0000-4000-8000-000000000003",
  "threadId": "thread-tenant-policy",
  "state": {},
  "messages": [{ "id": "m1", "role": "user", "content": "架空会社Aとの契約金額は3,200万円です" }],
  "tools": [],
  "context": [],
  "forwardedProps": {},
  "redactionPolicyId": "internal-contracts"
}

5. 新しい版・rollback・archive

新しい本文から name を除いたJSON fileを作り、次版のDRAFTを追記します。

qaip api redaction-policies.create-version \
  --name internal-contracts --json @policy-version.json --dry-run
qaip api redaction-policies.create-version \
  --name internal-contracts --json @policy-version.json

qaip api redaction-policies.list-versions \
  --name internal-contracts --limit 50

切替・rollback・archiveでは、直前に取得したACTIVE版を expectedActiveVersion に指定します。別の管理者が先に切り替えた場合は 409 ACTIVE_VERSION_CONFLICT となり、部分更新は行われません。policy detailを再取得してから、新しい期待版でやり直してください。

qaip api redaction-policies.activate-version \
  --name internal-contracts --version 2 --json @cas-v1.json --dry-run
qaip api redaction-policies.activate-version \
  --name internal-contracts --version 2 --json @cas-v1.json --yes

# 過去版を再度ACTIVEにするrollbackも同じactivate-versionを使います。
qaip api redaction-policies.activate-version \
  --name internal-contracts --version 1 --json @cas-v2.json --dry-run
qaip api redaction-policies.activate-version \
  --name internal-contracts --version 1 --json @cas-v2.json --yes

qaip api redaction-policies.archive \
  --name internal-contracts --json @cas-v1.json --dry-run
qaip api redaction-policies.archive \
  --name internal-contracts --json @cas-v1.json --yes

archive後の新しいAgent runは 422 UNKNOWN_REDACTION_POLICY になります。既に作成済みのrunを同じrun IDや idempotency keyで再送した場合は、ポリシーを再評価せず元のrunを返します。一度ACTIVEになった版は監査のためhard deleteできません。未有効化のDRAFTだけが delete-version --yes の対象です。

リクエスト例

マスキングなし（既定）

{
  "runId": "6a5c8f1e-0000-4000-8000-000000000001",
  "threadId": "thread-1",
  "state": {},
  "messages": [{ "id": "m1", "role": "user", "content": "佐藤太郎さんの連絡先を教えてください" }],
  "tools": [],
  "context": [],
  "forwardedProps": {}
}

入力はそのまま外部プロバイダへ送信されます。

マスキングあり（既知のポリシー ID）

{
  "runId": "6a5c8f1e-0000-4000-8000-000000000002",
  "threadId": "thread-1",
  "state": {},
  "messages": [{ "id": "m1", "role": "user", "content": "佐藤太郎さんの連絡先を教えてください" }],
  "tools": [],
  "context": [],
  "forwardedProps": {},
  "redactionPolicyId": "pii-standard"
}

外部プロバイダへは [氏名]さんの連絡先を教えてください として送信されます。ダッシュボードの表示と保存内容は原文のままです。

未知のポリシー ID・空文字（`422`）

{ "...": "...", "redactionPolicyId": "no-such-policy" }

{ "error": { "message": "unknown redaction_policy_id", "type": "UNKNOWN_REDACTION_POLICY" } }

空文字・空白のみを指定した場合はスキーマ検証で弾かれるため、FastAPI 標準の検証エラー形式（detail が配列）になります。

{ "detail": [{ "loc": ["body", "input", "redactionPolicyId"], "msg": "..." }] }

機械可読コードは error.type にあります（UNKNOWN_REDACTION_POLICY / AGENTCORE_REDACTION_UNSUPPORTED / REDACTION_UNAVAILABLE）。いずれの場合も「マスキングなし」とは解釈されません。run は作成されず、外部プロバイダも呼ばれません。

AgentCore 実行モードとの併用（`422`）

サーバーが AgentCore 実行モードで動作している場合、redactionPolicyId との併用はできません。

{
  "error": {
    "type": "AGENTCORE_REDACTION_UNSUPPORTED",
    "message": "redaction_policy_id is not supported with the AgentCore execution mode"
  }
}

AgentCore ランタイム内のナレッジベース検索結果はマスキング処理へ到達できないため、この組み合わせだけを拒否しています。redactionPolicyId を指定しない AgentCore 実行は従来どおり利用できます。

マスキング基盤が利用できない場合（`503`）

{
  "error": {
    "type": "REDACTION_UNAVAILABLE",
    "message": "redaction is unavailable: model_server_unreachable"
  }
}

redactionPolicyId を指定したリクエストは、マスキング基盤が停止・timeout・失敗しても原文送信にフォールバックしません。redactionPolicyId を指定しないリクエストと /completions・/search・/extract は影響を受けず利用できます。

実行中にマスキングが失敗した場合（`RUN_ERROR`）

{ "type": "RUN_ERROR", "code": "REDACTION_FAILED", "message": "redaction failed; ..." }

run は FAILED になり、失敗したマスキング境界より後の外部プロバイダ呼び出しは行われません。たとえば検索クエリの失敗時は embedding / Google 検索を呼ばず、検索結果の失敗時は後続の外部 LLM を呼びません。すでに完了した先行呼び出しは取り消されません。

補足

親 run のポリシーは継承されません。子 run でもマスキングが必要な場合は、その run で redactionPolicyId を明示してください。
外部 Iceberg テーブルのクエリ結果は行数が絞られます。 マスキングは 1 セルずつ処理するため、値の数が行数 × 列数で増えます。マスキングが制限時間内に終わる範囲まで結果を切り詰め、切り詰めた場合は結果の truncated が true になります（絞らないとマスキングが間に合わず run 自体が失敗します）。スキーマは切り詰めません。
引用リンクが機能しなくなる場合があります。 検索結果の URL もマスキング対象なので、 URL のパスやクエリにマスキング対象（氏名など）が含まれていると、その部分が置換ラベルに変わり、回答中の引用リンクが目的のドキュメントへ到達しません。署名付き URL のクエリに認証情報が含まれるケースを外部プロバイダへ渡さないための仕様です。原文の URL は保持されず、後からリンクを復元する手段はありません。
モデルの応答に対する再識別・プレースホルダの復元は行いません。
マスキングは処理失敗・不正応答・未対応入力の原文送信を防ぎますが、ローカルモデルの意味的な見落としを完全に排除するものではありません。この残存リスクは、認証情報の決定的検出、プロンプト安全対策、ポリシーごとに版管理した評価データセットでのリリース判定によって管理しています。

QAIP入門

データソース

Playground

管理

ユースケース

Integrations

Support

外部LLM送信前のマスキング

マスキングの対象

検出する分類

テナントポリシーを管理する

1. CLI schemaを確認する

2. DRAFTを検証・作成する

3. ACTIVEにする

4. Agentから利用する

5. 新しい版・rollback・archive

リクエスト例

マスキングなし（既定）

マスキングあり（既知のポリシー ID）

未知のポリシー ID・空文字（`422`）

AgentCore 実行モードとの併用（`422`）

マスキング基盤が利用できない場合（`503`）

実行中にマスキングが失敗した場合（`RUN_ERROR`）

補足

​マスキングの対象

​検出する分類

​テナントポリシーを管理する

​1. CLI schemaを確認する

​2. DRAFTを検証・作成する

​3. ACTIVEにする

​4. Agentから利用する

​5. 新しい版・rollback・archive

​リクエスト例

​マスキングなし（既定）

​マスキングあり（既知のポリシー ID）

​未知のポリシー ID・空文字（422）

​AgentCore 実行モードとの併用（422）

​マスキング基盤が利用できない場合（503）

​実行中にマスキングが失敗した場合（RUN_ERROR）

​補足

マスキングの対象

検出する分類

テナントポリシーを管理する

1. CLI schemaを確認する

2. DRAFTを検証・作成する

3. ACTIVEにする

4. Agentから利用する

5. 新しい版・rollback・archive

リクエスト例

マスキングなし（既定）

マスキングあり（既知のポリシー ID）

未知のポリシー ID・空文字（`422`）

AgentCore 実行モードとの併用（`422`）

マスキング基盤が利用できない場合（`503`）

実行中にマスキングが失敗した場合（`RUN_ERROR`）

補足