GuidesOneMux

ツール承認と復旧に対応した、プライバシー配慮型LangGraphエージェントの構築

LangGraphの人間によるレビュー、チェックポイント、実行制限、認証情報を安全に扱うツールを組み合わせ、機密データを扱うエージェントを構築する実践的なパターンを紹介します。

AI

要約 · TL;DR

LangGraphのhuman-in-the-loopミドルウェアを使って機密性の高いツール呼び出しを一時停止し、レビューまたは拒否したうえで、チェックポイントから再開します。このワークフローに厳格なツール境界、認証情報の隔離、実行制限を組み合わせましょう。

要点

  • 認証情報はツールの実装内に保持し、モデルには必要最小限の引数だけを渡します。
  • 安全な読み取りは許可しつつ、機密性の高い書き込みやクエリには人間のレビューを必須にします。
  • 永続的なチェックポインターと安定したスレッドIDを使い、中断した処理を再開します。
  • グラフの実行を制限し、ツールは冪等にするか、再試行しても安全な設計にします。
  • チェックポイントに保存される状態と割り込みペイロードは、機密データとして扱います。
目次 (5)

プライバシーに配慮したエージェントを設計する際、ツール呼び出しが安全かどうかの判断をモデル任せにしてはいけません。認証情報は会話の外に置き、各ツールの操作範囲を限定し、機密性の高い処理は人間によるレビューのために一時停止します。LangGraphのhuman-in-the-loopミドルウェアは一時停止と再開の仕組みを提供しますが、データの扱い、認可、実行制限はアプリケーション側で定義する必要があります。

このガイドでは、顧客レコードの読み取りとデータベース変更の申請ができるエージェント向けに、小規模な実装パターンを紹介します。コードは例示であり、ここではテストしていません。デプロイ前に、利用する環境に合わせてパッケージのバージョンとツールのシグネチャを確認してください。

1. モデルのコンテキストと認証情報を分離する

パスワード、APIキー、セッションCookie、または制限のないデータベース認証情報を、プロンプトやツール引数に含めないでください。代わりに、ツールの操作範囲を限定し、実行時にアプリケーションのシークレット管理機構から認証情報を取得させます。モデルには、アクションを選ぶために必要なデータだけを見せてください。

たとえば、任意のSQLや接続情報を受け取る汎用ツールよりも、find_customer_record(customer_id)のようなツールを使いましょう。認可はツール自体で検証してください。ユーザーから依頼されたというだけでは、そのレコードへのアクセス権があることの証明にはなりません。

人間によるレビューは追加の管理策であり、認可システムの代わりにはなりません。レビュー担当者が判断に必要な情報を確認できるようにしつつ、レビュー画面やログに不要な個人データやシークレットを表示しないようにしてください。

2. 機密性の高いアクションにレビューを設定する

提供されているLangChainのhuman-in-the-loopドキュメントでは、ポリシーに基づいてツール呼び出しを確認するミドルウェアが説明されています。該当する呼び出しでは実行を中断でき、チェックポインターでグラフの状態を保存すれば、後から処理を再開できます。ドキュメントに記載されている判断には、承認、引数の編集、フィードバックを添えた拒否、ユーザーに質問するツールへの回答があります。

以下は設定例です。プレースホルダーのツールは、アプリケーションのアクセスルールと入力検証を適用する実装に置き換えてください。

from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver

agent = create_agent(
    model="YOUR_CONFIGURED_MODEL",
    tools=[read_customer_record, update_customer_record],
    middleware=[
        HumanInTheLoopMiddleware(
            interrupt_on={
                "read_customer_record": False,
                "update_customer_record": {
                    "allowed_decisions": ["approve", "edit", "reject"]
                },
            },
            description_prefix="Review requested customer-data change",
        ),
    ],
    # For production, use a persistent checkpointer appropriate to your stack.
    checkpointer=InMemorySaver(),
)

InMemorySaverはプロトタイプ向けであり、プロセス再起動後も確実に復旧するためのものではありません。ドキュメントによると、人間によるレビューで割り込みを行うにはチェックポインターが必要で、AsyncPostgresSaverやMongoDBSaverなどの永続化オプションが挙げられています。チェックポイントに保存するデータに適したアクセス制御、保持ルール、暗号化を備えたストレージを選んでください。チェックポイントにはメッセージやツール引数が含まれることがあるため、認証情報を除外していても機密性の高いユーザーデータが保存される可能性があります。

一部の呼び出しだけをレビュー対象にする場合、ドキュメントでは条件付き割り込みにwhen述語を使う方法も紹介されています(langchain>=1.3.3が必要)。たとえば、承認済みのワークスペース外への書き込みや、読み取り専用ではないクエリを一時停止できます。文字列の先頭部分を確認するだけでは、完全なSQLセキュリティポリシーとは言えません。データベース層とツール層でも、安全な操作を強制してください。

3. 同じ実行を一時停止し、レビュー後に再開する

安定したスレッドIDを使うことで、アプリケーションは保留中のレビューを適切な会話に関連付けられます。このIDとレビュー画面を保護してください。スレッドIDを知っているだけで、アクションの承認権限が得られるようにしてはいけません。

from langgraph.types import Command

config = {"configurable": {"thread_id": "conversation-123"}}

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Update this customer's address"}]},
    config=config,
    version="v2",
)

if result.interrupts:
    # Present the requested action to an authenticated reviewer.
    # Resume only after recording that reviewer's decision.
    result = agent.invoke(
        Command(resume={"decisions": [{"type": "reject", "message": "Verify the request first."}]}),
        config=config,
        version="v2",
    )

複数のツール呼び出しを一時停止する場合、判断の順序は割り込みリクエスト内のアクションの順序と一致させる必要があります。副作用のあるアクションを拒否するにはrejectを使ってください。ドキュメントによると、respondは合成されたツール結果を返す機能です。「ユーザーに質問する」形式のツールへの回答に使うものであり、書き込みを拒否するためのものではありません。

4. 実行を制限し、復旧を考慮した設計にする

レビューのために処理を一時停止しても、モデルがツールを繰り返し要求することをそれだけで防げるわけではありません。呼び出しにグラフの再帰上限を設定し、上限エラーが発生した場合は、制御された形で停止するように処理してください。適切な上限はワークロードによって異なります。有用なモデルとツールの連続ステップ数に基づいて決め、上限に達した場合の動作もテストしてください。

config = {
    "configurable": {"thread_id": "conversation-123"},
    "recursion_limit": 12,
}

この設定例はグラフのステップ数を制限するものであり、遅いツール、大きな出力、外部への副作用の繰り返しを防ぐ保証にはなりません。ネットワークやデータベースの呼び出しにはタイムアウトを設定し、ツールの出力サイズに上限を設け、入力を検証してください。再試行可能な操作には冪等性の制御を設けるか、変更を適用する前に現在の状態を確認します。ツールの処理が成功した後、エージェントが結果を記録する前に実行が失敗した場合、何も確認せずに再試行すると操作が二重に実行される可能性があります。

復旧時には、保留中のアクションとその認可が現在も有効であることを確認してから、同じチェックポイントのスレッドを再開してください。レビュー待ちの間にユーザーの権限や対象レコードの状態が変わっていた場合は、古い引数のまま実行せず、拒否するか、改めて検証してください。

5. プライバシーと障害対応のチェックリスト

本番環境に移行する前に、次の点を確認してください。

  • ツールの実装が認証情報を内部で取得し、ツールの結果やエラーに含めない。
  • 各ツールがユーザーの認可を確認し、必要最小限の引数だけを受け付ける。
  • チェックポイント、割り込みペイロード、ログ、レビュー画面について、アクセス制御と保持ルールが定められている。
  • レビュー担当者が、無関係な個人データを見ずに対象と結果を把握できる。
  • 拒否された場合はツールが実行されず、再試行しても副作用が重複しない。
  • 実行ステップ、ツールのタイムアウト、出力にそれぞれ上限があり、中断または失敗した処理を報告する明確な手段がある。

設計上の重要なポイントは、人間による承認を、セキュリティを備えたワークフロー上のチェックポイントの一つとして扱うことです。最小権限、データ最小化、ツールレベルの検証の代わりにしてはいけません。

よくある質問

LangGraphのhuman-in-the-loopミドルウェアは、一時停止したエージェントの状態を保存しますか?

割り込みをまたいで状態を保存するために、LangGraphの永続化機能を使います。チェックポインターが必要です。本番環境では永続ストレージを選び、適切なアクセス制御と保持ルールを設定してください。

機密性の高いツール呼び出しを拒否するために、respondの判断を使うべきですか?

いいえ。ドキュメントでは、respondは合成された成功ツール結果を返す動作であり、「ユーザーに質問する」ツールへの回答などを想定しています。副作用のあるアクションを拒否するにはrejectを使ってください。

LangGraphエージェントで認証情報を非公開にするにはどうすればよいですか?

認証情報はツールの実行環境またはシークレット管理レイヤーに保持してください。プロンプト、モデルから見えるツール引数、ツールの結果、割り込みメッセージ、ログには含めないでください。

人間の承認を導入すれば、エージェントが無期限に実行されるのを防げますか?

いいえ。承認ミドルウェアが扱うのは、設定されたツール呼び出しのレビューです。実行制限、ツールのタイムアウト、出力制限、安全な再試行動作は別途設定してください。

関連記事