Application Engineering: Agent、RAG、Memory

LLM アプリケーション開発には、モデル API の呼び出しだけでなく、ツールの呼び出し、タスクのオーケストレーション、知識の取得、メモリ管理、評価、セキュリティ、信頼性も含まれます。

1. コアアーキテクチャ

LLM Application
│
├── Tool Calling
│   ├── Tool Schema / Arguments
│   ├── Validation / Authorization
│   ├── Parallel / Sequential Calls
│   └── Error Handling / Idempotency
│
├── Agent / Workflow
│   ├── ReAct / Plan-and-Execute
│   ├── Router / State Machine
│   ├── State / Checkpointing
│   └── Human-in-the-loop
│
├── RAG
│   ├── Parsing / Chunking / Embedding
│   ├── Hybrid Retrieval / Reranking
│   └── Context Assembly / Citation
│
├── Vector Database
│   ├── Similarity / ANN
│   ├── HNSW / IVF
│   └── Metadata Filtering
│
├── Memory
│   ├── Short-term / Long-term
│   ├── Retrieval / Updating
│   └── Invalidation
│
├── Evaluation / Observability
│   ├── Task Success / Groundedness
│   └── Trace / Logging / Metrics
│
└── Security / Reliability
    ├── Prompt Injection
    ├── Authorization / Sandboxing
    └── Retry / Rate Limit / Audit

2. Tool Calling / Function Calling

モデルは外部操作を直接実行しませんが、ツール名と構造化パラメーターを生成し、実際の実行はアプリケーション バックエンドによって完了します。

User
  ↓
LLM
  ↓
Tool Name + Arguments
  ↓
Validate / Authorize
  ↓
Backend Executes Tool
  ↓
Tool Result
  ↓
LLM Continues

Tool Schema / JSON Schema

通常、ツールの説明には、名前、説明、およびパラメーター Schema が含まれます。

{
  "name": "get_weather",
  "description": "Get weather for a city",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"]
      }
    },
    "required": ["city"],
    "additionalProperties": false
  }
}

JSON Schema はパラメータの形状を記述していますが、バックエンドのビジネス検証を置き換えることはできません。

Tool Choice

モデルが呼び出すかどうか、またどのツールを呼び出すかを制御します。

一般的な戦略:

特定のパラメータ名とサポートはモデル API によって異なります。

複数のツール呼び出し

Parallel Tool Calling: 複数のツールは互いに独立しており、同時に実行できます。

                 ┌── get_weather()
LLM Tool Calls ──┤
                 └── get_exchange_rate()
                         ↓
                  Aggregate Results

Sequential Tool Calling: 後続のツールは、前のツールの戻り値に依存します。

search_flight()
      ↓
get_flight_details()
      ↓
check_availability()
      ↓
book_flight()

注: モデルは複数の Tool Call を一度に生成しますが、これはバックエンドを並行して実行する必要があるという意味ではありません。リソースの依存関係や副作用が関係する場合、プログラムは実行順序を制御する必要があります。

Tool Validation / Authorization

モデルによって生成されたパラメーターは信頼できない入力です。

バックエンドは少なくとも以下をチェックします。

1. JSON の構造体とフィールドの型は正しいですか?
2. パラメータがビジネス上の制約を満たしているかどうか。
3. 現在のユーザーが呼び出し権限を持っているかどうか。
4. ユーザーが指定されたリソースを操作する権限を持っているかどうか。
5. リスクの高い業務が明確に特定されているかどうか。

たとえば:

def delete_document(user, document_id):
    document = get_document(document_id)

    if document.owner_id != user.id:
        raise PermissionError("Forbidden")

    document.delete()

モデルが delete_document を呼び出したからといって、自動的にドキュメントを削除する権限があることを意味するわけではありません。

Timeout / Retry / Idempotency

外部ツールがタイムアウトするか、失敗する可能性があります。

• Timeout: 待ち時間を制限します。
• Retry: 回復可能なエラーが発生した場合は再試行します。
• Fallback: メイン プランが失敗した後、代替プランに切り替えます。
• Idempotency: 同じ論理演算を繰り返し実行しても、予期しない副作用が繰り返し発生することはありません。

支払い、予約、通知の送信などの操作では、Idempotency Key を通じて重複したリクエストを識別できます。

Retry は冪等性 を考慮する必要があります。そうしないと、ネットワーク タイムアウト後の再試行が繰り返し実行される可能性があります。

Tool Result

ツールの結果も信頼できないコンテンツです。

外部 Web ページ内のテキスト、ドキュメント、および API 応答はデータとして使用できますが、システム コマンドやユーザー認証に自動的にアップグレードすることはできません。

---

3. Agent Loop / Workflow

ReAct

ReAct はループ実行を採用しています。

Reason
   ↓
Action
   ↓
Observation
   ↓
Reason
   ↓
Action
   ↓
...

モデルは、ツールから返された結果に基づいて次のステップを継続的に調整します。

実行パスを事前に完全に決定することが難しい、オープンエンドの複数ステップのタスクに適しています。

Plan-and-Execute

最初に全体的な計画を作成してから、個々のステップを実行します。

User Task
    ↓
Planner
    ↓
Step 1 → Step 2 → Step 3
    ↓
Executor
    ↓
Result

計画は実行中に再計画することもできますが、計画の変更が決して許可されないという意味ではありません。

Router

タスクの種類に基づいて実行パスを選択します。

User
  ↓
Router
  ├── General QA → LLM
  ├── Document QA → RAG
  ├── Weather → Tool
  └── Data Analysis → Data Agent

Router は、ルール、分類モデル、または LLM を使用して実装できます。

State Machine / Workflow

State Machine は、プロセスを明示的な状態遷移に制限します。

START
  ↓
SEARCH
  ↓
VALIDATE
  ↓
CONFIRM
  ↓
EXECUTE
  ↓
DONE

Workflow は、決定論的コード、LLM ノード、ツール ノードを組み合わせたものです。

Agent を生成する際のすべてのステップを LLM に決定させる必要はありません。

たとえば:

Upload Document
       ↓
Parse（確定的なコード）
       ↓
Retrieve（検索）
       ↓
Summarize（LLM）
       ↓
Human Approval
       ↓
Save（確定的なコード）

プロセスが明確に定義されたビジネス タスクの場合、完全に自由な Agent Loop の決定よりも、Workflow + 少数の Agent の決定の方が制御とテストが容易であることがよくあります。

Agent State / Checkpointing

これは Agent プロジェクトにおいて非常に重要な概念です。

State は、現在のタスクの実行に必要な情報を保存します。

たとえば:

{
    "messages": [...],
    "current_step": "validate",
    "tool_results": {...},
    "retry_count": 1,
    "approved": False
}

Checkpointing は、次のように実行状態を保持します。

• エラー後のリカバリ。
• 実行は複数のリクエストにわたって継続されます。
• 手動による確認を待つために一時停止します。
• 過去の実行ステータスを確認します。

LangGraph の Checkpointer は Graph State を保持でき、Store は Thread 全体の長期データに使用できます。

注: 実行の再開は、コードの各行が 1 回だけ実行されることを意味するものではありません。一部のノードは再実行される可能性があるため、外部の副作用に対して冪等性の保護が必要です。

Loop Termination / Budget

Agent には明確な停止条件が必要です。

Task Completed
Max Steps Reached
Timeout
Token / Cost Budget Exhausted
Unrecoverable Error
User Cancelled

max_steps に加えて、以下も制限することをお勧めします。

• ツール呼び出しの最大数。
• 費やした最大合計時間。
• Tokenの最大消費量。
• 最大コスト。
• 単一ツールの再試行回数。

Max Steps を設定するだけでは、単一のツール呼び出しが長期間ブロックされるのを必ずしも防ぐことができます。

Human-in-the-loop

リスクの高い操作は一時停止し、ユーザーの確認を待つ必要があります。

Agent Proposes Action
          ↓
     Pause / Checkpoint
          ↓
     Human Approval
       ├── Reject → Stop
       └── Approve → Execute

たとえば:

• データを削除します。
• メールを送信します。
• 支払いを実行します。
• 実稼働構成を変更します。
• 不可逆的な操作を送信します。

LangGraphのinterrupt()は状態保存と外部入力待ち後の復元をサポートしています。

---

4. RAG：Retrieval-Augmented Generation

RAG は、外部の知識を取得することで、関連するコンテキストを LLM に提供します。

Indexing Pipeline

Documents
    ↓
Parsing
    ↓
Chunking
    ↓
Embedding
    ↓
Vector Database / Search Index

Query Pipeline

User Query
     ↓
Query Processing
     ↓
Retrieval
     ↓
Reranking
     ↓
Context Assembly
     ↓
LLM
     ↓
Answer + Citation

Document Parsing

PDF、Web ページ、Markdown、Office ドキュメントなどを処理可能なコンテンツに変換します。

次の点に注意する必要があります。

• タイトルレベル。
• シート。
• ページ番号。
• 文書構造。
• 画像とマルチモーダル コンテンツ。

解析中にテーブル構造が失われると、その後の Retrieval の品質にも影響が出る可能性があります。

Chunking

長い文書を小さな検索単位に分割します。

一般的な戦略:

Overlap は境界情報の損失を軽減できますが、Overlap が大きすぎるとストレージコストが増加し、検索結果が重複してしまいます。

Embedding / Semantic Search

Embedding はテキストをベクトルとして表します。

Query → Query Encoder → Query Vector
                              ↓
                          Similarity
                              ↑
Document → Document Encoder → Doc Vector

共通の Bi-Encoder は、それぞれ Query および Document としてエンコードできます。

両側でまったく同じエンコード プロセスを使用する必要はありませんが、相互に互換性があり、一貫したトレーニング目標を持つベクトル空間を使用する必要があります。

BM25 / Hybrid Search

BM25 キーワード一致、用語頻度、逆文書頻度、文書長に基づいて関連性を計算します。

Semantic Search は意味上の類似性をより重視します。

Hybrid Search は次の 2 つを組み合わせたものです。

Query
  ├── BM25 Retrieval
  └── Vector Retrieval
          ↓
      Merge / Fusion
          ↓
        Rerank

RRF：Reciprocal Rank Fusion

RRF は、Hybrid Search の一般的な並べ替えおよび融合方法です。

その核心は、BM25 と Cosine Similarity の生のスコアを直接比較するのではなく、さまざまな検索リストでのランキングに基づいてドキュメントに累積スコアを与えることです。

結果 (d) の一般的な形式は次のとおりです。

$$RRF(d)=\sum_i\frac{1}{k+\operatorname{rank}\_i(d)}$$

ここで、(k) はランキング平滑化定数です。

Reranking

フェーズ 1 Retrieval は、スピードとリコールに重点を置いています。

Reranking より複雑なモデルを使用して候補結果を再評価します。

共通 Cross-Encoder:

Query + Document
        ↓
Joint Encoding
        ↓
Relevance Score

Bi-Encoder とは異なり、Cross-Encoder は Query と Document を直接共同処理します。これは一般に詳細な並べ替えにより適していますが、計算コストが高くなります。

Query Rewriting / Multi-query Retrieval

Query Rewriting ユーザーの質問が不明瞭であるか、文脈が欠如している場合は、言い換えます。

Multi-query Retrieval は、リコール範囲を向上させるために、さまざまな観点から複数のクエリを生成します。

ただし、クエリの数が増えると、コスト、遅延、ノイズも増加します。

Context Assembly

最終的な検索結果を LLM コンテキストに構築します。

考慮する必要があるのは次のとおりです。

• Token Budget。
• 重りを取り除きます。
• 出典とページ番号。
• 関連性ランキング。
• コンテキストの切り捨て。
• コンテンツ権限を取得します。

Citation

Citation を使用すると、回答を元のソースまで遡ることができます。

ただし、Citation を生成しても、その参照が必ずしも正しいとは限りません。また、参照資料が実際に対応する記述をサポートしているかどうかも確認する必要があります。

RAG 権限の分離

これは、量産 RAG における重要な安全上の問題です。

たとえば、ユーザーまたは組織が異なれば、ドキュメントに対するアクセス権も異なります。

リソース権限フィルタリングは、以下を取得するときにバックエンドによって強制される必要があります。

filters = {
    "tenant_id": authenticated_user.tenant_id
}

ここで、tenant_id は、LLM によって生成された値を直接信頼するのではなく、認証された ID から取得する必要があります。

最初にすべてのユーザー プロファイルを取得してから、LLM が表示できるコンテンツを独自に決定させることはできません。

---

5. Vector Database

Vector Database は Embedding の格納と取得に使用され、ANN Index と Metadata Filtering が通常サポートされます。

Embedding
    ↓
Vector Storage
    ↓
ANN Index
    ├── HNSW
    └── IVF
    ↓
Similarity Search
    ↓
Top-k

Similarity Metrics

ベクトルが L2 Normalization を通過する場合、Cosine Similarity、Dot Product、および Euclidean Distance の順序の間には明確な対応関係があります。

正規化を行わないと、異なるランク付けが行われる可能性があります。

ANN

Approximate Nearest Neighbor は、近似インデックスを使用して、低い計算コストで類似性の高いベクトルを見つけます。

取得速度、メモリ、Recall の間のトレードオフが必要です。

HNSW

Hierarchical Navigable Small World マルチレベル近傍グラフを使用した検索。

共通パラメータ:

• M: 制御グラフ接続番号。
• ef_construction: インデックス構築の品質とコストに影響します。
• ef_search: クエリ速度と Recall に影響します。

IVF

Inverted File Index はベクトルを異なる Cluster に分割します。

クエリを実行するときは、計算を減らすために Cluster の部分のみを検索します。

共通パラメータ:

• nlist: Cluster 数量。
• nprobe: クエリ中に検索された Cluster の数。

Vector Database選択

別個のベクトル データベースは必ずしも必要ではありません。

アプリケーションがすでに PostgreSQL を使用している場合は、ベクトルの保存と取得に pgvector を使用することもできます。

中小型 RAG の場合:

PostgreSQL + pgvector

通常、検討する価値のあるオプションです。

ベクトルのサイズ、検索スループット、または配布要件が増加する場合は、専用のベクトル データベースを評価します。

---

6. Memory

Memory を使用すると、Agent は現在のコンテキストまたは長期保存された情報を活用できます。

Short-term Memory

Conversation History
       ↓
Summarization
       ↓
Context Compression
       ↓
Current LLM Context

主に現在のダイアログとタスクの実行ステータスを処理します。

Long-term Memory

Episodic Memory

たとえば:

2026-10-01:
モデルのデプロイ時に発生した CUDA OOM。

2026-10-03:
別の推論エンジンに切り替えることを決定。

Semantic Memory

歴史的な出来事をより安定した知識に抽出します。

User frequently develops Django applications.

Episodic Memory は何が起こったかを強調し、Semantic Memory は長期的に使用できる事実や知識を強調します。

Memory Retrieval

長期記憶では毎回すべてのContextを入れることはできません。

以下に基づいて作成できます。

• Semantic Similarity。
• Keywords。
• Recency。
• Importance。
• User / Task Scope。

関連する思い出を選択してください。

Memory Updating / Invalidation

解決する必要がある:

• ユーザー情報が変更された場合はどうすればよいですか?
• 新しい記憶が古い記憶と矛盾する場合はどうすればよいですか?
• 期限切れの思い出はいつ削除されますか?
• ユーザーが情報の削除を要求した場合はどうすればよいですか?
• 思い出はどれくらいの期間保存しておくべきですか？

たとえば:

Old:
User prefers Framework A.

New:
User now prefers Framework B.

システムは、2 つの矛盾する設定を永久に保持するのではなく、現在有効な事実を更新する必要があります。

同時に、Prompt Injectionの内容や未検証のツールの戻り値を長期メモリに直接書き込むことはできません。

---

7. Evaluation / Observability

Agent アプリケーションは、最終結果と内部実行プロセスの両方を観察する必要があります。

Evaluation

Groundedness は Correctness と等しくありません。取得されたドキュメント自体は不正確である可能性があり、モデルがそれを忠実に参照している場合でも、不正確な回答が生成される可能性があります。

Trace

Trace はタスク内の完全な呼び出しパスを記録します。

Request
   ↓
LLM Call
   ↓
Tool Call
   ↓
Tool Result
   ↓
Retriever
   ↓
Reranker
   ↓
LLM Call
   ↓
Final Answer

通常、各ステップは Span を形成し、以下を記録します。

• 開始時刻と終了時刻。
• 入力と出力の概要。
• Token Usage。
• Model Name。
• Error。
• Tool Name。
• Parent / Child Relationship。

Logging および Metrics

実稼働環境では通常、3 つすべての組み合わせが必要です。

ユーザーのプライバシー、ツールの資格情報、または機密ファイルの内容がログおよび Trace に無制限に記録されないよう、特に注意してください。

---

8. Security、Authorization & Reliability

Prompt Injection

Prompt Injection は入力コンテンツを通じてモデルに影響を与え、予想される指示や安全境界からの逸脱を引き起こします。

Direct Prompt Injection：

攻撃者は悪意のある命令を直接入力します。

Indirect Prompt Injection：

悪意のある指示は、外部の Web ページ、電子メール、PDF、RAG ドキュメント、またはツールの戻り結果に隠されています。

External Document
       ↓
RAG Retrieval
       ↓
LLM Reads Document
       ↓
Malicious Instruction
       ↓
Unauthorized Tool Call

RAG とモデルの微調整では、Prompt Injection のリスクを根本的に排除することはできません。

Trust Boundary

以下を区別する必要があります。

Trusted:
Application Rules
Authorization Policy
Explicit User Approval

Untrusted:
User-controlled Data
Retrieved Documents
Web Pages
Tool Results
LLM-generated Arguments

LLM が権威の最終裁判官であってはなりません。

OWASP では、外部コンテンツを信頼できないものとして扱い、ツール パラメーターの検証とアクセス制御をモデルの外部で実行することも推奨しています。

Least Privilege

Agent には、現在のタスクを完了するために必要な最小限の権限のみが必要です。

たとえば:

Read-only Research Agent
    ↓
Search / Read Permissions

Booking Agent
    ↓
Search Permissions
    ↓
Explicit Confirmation
    ↓
Booking Permission

Confirmation / Human Approval

通常、次の操作では追加の確認または承認が必要です。

• 重要なリソースを削除します。
• 機密情報を外部に送信します。
• 支払うか予約してください。
• 本番環境を変更します。
• 不可逆的な操作を実行します。

確認する場合、ユーザーは後続のすべての操作を一般的に承認するのではなく、実際の操作オブジェクトと主要なパラメーターを確認できる必要があります。

Input / Output Validation

入力の検証:

Schema
Type
Range
Resource Existence
Business Rules
Authorization

出力の検証:

Expected Format
Required Fields
Output Safety
Groundedness
Downstream Compatibility

たとえば、モデルが SQL を生成する場合、JSON Schema 検証に合格したからといって、運用データベースで直接実行することを許可することはできません。

Sandboxing

コード、Shell、またはその他の高リスク ツールを実行する場合は、制限されたランタイム環境を使用する必要があります。

共通のコントロール:

• ファイルシステムのアクセス範囲。
• ネットワークアクセス権。
• CPU / Memory 制限。
• 実行がタイムアウトしました。
• 不要な権限を禁止します。
• 一時的な環境のクリーンアップ。

Reliability

入力と出力の検証に加えて、以下も必要です。

• Timeout。
• Retry / Backoff。
• Idempotency。
• Circuit Breaker。
• Rate Limiting。
• Audit Logs。
• Secrets Management。

Circuit Breaker は、外部サービスが失敗し続ける場合に、リソースを継続的に消費する要求の繰り返しを避けるために、外部サービスの呼び出しを一時的に停止するために使用されます。

Audit Logs は、承認と実行結果だけでなく、誰がどの重要な操作をいつ開始したかを記録する必要があります。

概要

最も重要なエンジニアリング原則:

1. LLM は決定の提案を担当し、バックエンドは検証と実行を担当します。
2. の確定的なビジネス ロジックは、最初に通常のプログラム コードを使用するため、Agent に引き継ぐ必要はありません。
3. RAG の取得品質とデータ許可制御は、生成品質と同じくらい重要です。
4. Agent には、状態管理、停止条件、および回復メカニズムが必要です。
5. 外部コンテンツ、ツール結果、モデル出力は、信頼できるアクセス許可を自動的に取得できません。
6. 評価 Agent 模範解答の質だけでなく、最終的な課題の成功率を優先する必要があります。

---

参考資料

• LangGraph Documentation
• LangGraph Persistence
• Ragas Evaluation
• OWASP LLM Prompt Injection
• OWASP Prompt Injection Prevention
• pgvector