自社のプロダクトや社内システムに AI（LLM）を機能として組み込むための設計ガイド。開発作業での AI 利用は全体像、業務プロセスへの導入は業務への組み込みへ。

統合パターン — 簡単な方から

下に行くほど自由度が上がり、設計・評価・運用コストも上がる。上のパターンで足りるなら下に行かないのが原則。

パターン	姿	典型ユース	難所
1. 単発呼び出し	入力→プロンプト→出力	要約・分類・翻訳・抽出	プロンプトの安定化
2. 構造化出力	JSON スキーマで型を保証	フォーム自動入力・データ変換	スキーマ設計・検証
3. ツール使用	AI が関数・API を呼ぶ	検索して答える・操作を実行する	ツール定義の明確さ
4. RAG	社内文書を検索して根拠付き回答	社内 QA・サポートボット	検索品質・文書整備
5. エージェント	ループで自律的にタスク遂行	調査・複数ステップの処理	暴走防止・評価・コスト

基本形 — API 呼び出し

最小構成。これだけでパターン1・2は実装できる。

# Python（Anthropic SDK の例）
import anthropic

client = anthropic.Anthropic()  # ANTHROPIC_API_KEY を環境変数で

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="あなたは問い合わせ分類器。カテゴリ名のみ返す。",
    messages=[{"role": "user", "content": ticket_text}],
)
print(message.content[0].text)

• system プロンプトに役割と出力形式、user に処理対象データ、と分離する
• モデルは「安い・速いモデルで試し、品質が足りなければ上げる」。分類・抽出は小型モデルで足りることが多い
• 同じ前置き（長い指示・文書）を繰り返すならプロンプトキャッシュでコストを下げる

構造化出力とツール使用

• 後段のプログラムで使う出力は必ずスキーマで縛る（JSON Schema / SDK の構造化出力機能）。自由文をパースしない
• ツール定義は「名前・説明・入力スキーマ」の説明文の質が精度を決める。Skills 設計と同じ要領で、いつ使うかを書く
• 受け取った値は通常の入力バリデーションにかける。AI 出力は信頼境界の外側として扱う

---

RAG — 社内知識に答えさせる

1. 文書整備 — 正本を決め、古い文書を捨てる。RAG の品質は検索より先に文書で決まる
2. 分割と埋め込み — 見出し単位などの意味のまとまりでチャンク化し、ベクトル DB に投入
3. 検索 — ベクトル検索 + キーワード検索の併用（ハイブリッド）を既定にする。リランキングは精度が足りない時に追加
4. 生成 — 取得チャンクを引用付きで渡し、「文書にない場合は無いと答える」を指示
5. 評価 — 想定質問 20〜50 件で「正しい文書を引けたか」「回答が正しいか」を分けて計測

エージェント組み込み

• 構成は「モデル + ツール群 + ループ」。フレームワークを入れる前に、この最小構成で要件を満たすか確認する
• 権限は最小から: 読み取り専用ツールで始め、書き込み系は人間承認を挟む
• ステップ数・トークン・実行時間に上限を置く（暴走とコスト事故の防止）
• コーディングエージェントを CI から使うのも立派な組み込み。下のヘッドレス実行を参照

ヘッドレス実行 — 既存パイプラインへの最短組み込み

# CI で: 失敗テストの一次調査をコメント化
claude -p "直近の CI 失敗ログを読み、原因仮説を3行で" --output-format json

# 定期実行で: 週次の依存更新チェック
codex exec "依存パッケージの脆弱性を調べ、更新 PR を作成"

API を直接叩くより先に、この形で「エージェントごと」組み込む方が早いケースが多い（社内ツール・運用自動化など）。

MCP — 接続の標準化

• MCP（Model Context Protocol）は AI と外部ツール・データ源をつなぐ共通規格。社内 API を MCP サーバとして1度実装すれば、Claude Code・Codex・Cursor のどれからも使える
• 「各ツール用の連携を個別に作る」状態になったら MCP 化のサイン
• 認証・権限は MCP サーバ側で制御する（AI 側に生のクレデンシャルを渡さない）。詳細はMCP・連携参考

---

評価・監視 — 本番投入の条件

1. 評価セットを作る — 本番想定の入力 20 件以上＋期待される出力の判定基準。リリース前にスコア化
2. 回帰として回す — プロンプト変更・モデル更新のたびに評価セットを再実行（プロンプトは Git 管理）
3. 本番ログを取る — 入出力・レイテンシ・トークン数・ユーザーフィードバックを記録（個人情報のマスキングを忘れない）
4. ガードレール — 出力の検証（形式・禁止事項）を後段に置き、失敗時はフォールバック（定型応答・人間へエスカレーション）

コスト設計の定石

• 処理を分解し、各ステップに必要十分な最小モデルを割り当てる（分類は小型、生成は中型、難所だけ大型）
• プロンプトキャッシュ・バッチ API で単価を下げる（バッチは非同期で良い処理に）
• トークン使用量をテナント・機能単位で計測し、上限を設定。「気づいたら高額」を防ぐ

Gotchas

• デモは1日でできるが本番品質は評価の仕組みで決まる。評価セットなしでのリリースはしない
• ユーザー入力をそのままプロンプトに連結するとプロンプトインジェクションの入口になる。指示とデータを分離し、出力検証を置く
• モデルは更新・廃止される。モデル名は設定値に外出しし、評価セットで乗り換え試験ができる状態を保つ
• レイテンシ要件を最初に確認する。対話 UI はストリーミング前提で設計する