AI エージェント開発

目的: Microsoft Foundry と Agent Framework を使用して、本番環境対応の AI エージェントを構築します。 スコープ: エージェント アーキテクチャ、モデル選択、オーケストレーション、可視化、評価。

---

このスキルを使用する場合

• Microsoft Foundry または Agent Framework で AI エージェントを構築する
• エージェント シナリオ用の LLM モデルを選択する
• マルチエージェント オーケストレーション ワークフローを実装する
• AI エージェントへのトレースと可視化を追加する
• エージェントの品質と応答精度を評価する

判定フロー

AI エージェントが必要ですか?
+-- シンプルなリクエスト-レスポンス? -> ツール付きシングルエージェント
+-- 複数ステップの推論? -> Chain-of-thought エージェント (プランナー付き)
+-- 複数の専門領域? -> マルチエージェント オーケストレーション
+-- ヒューマンアプルーバルが必要? -> ヒューマン・イン・ザ・ループ ワークフロー
+-- 高い信頼性が必須? -> リフレクション + 自己修正ループ
+-- リアルタイム ストリーミング? -> 非同期イベント駆動エージェント アーキテクチャ

前提条件

• Python 3.14 以上または .NET 10 以上
• agent-framework-azure-ai パッケージ
• デプロイ済みモデルを持つ Microsoft Foundry ワークスペース

クイック スタート

インストール

Python (推奨):

pip install agent-framework-azure-ai --pre # プレビュー中は --pre が必須

.NET:

dotnet add package Microsoft.Agents.AI.AzureAI --prerelease
dotnet add package Microsoft.Agents.AI.Workflows --prerelease

モデル選択

トップ本番環境モデル (Microsoft Foundry):

モデル	最適用途	コンテキスト	コスト/1M
gpt-5.2	エンタープライズ エージェント、構造化出力	200K/100K	TBD
gpt-5.1-codex-max	エージェント コーディング ワークフロー	272K/128K	$3.44
claude-opus-4-5	複雑なエージェント、コーディング、コンピューター使用	200K/64K	$10
gpt-5.1	複数ステップの推論	200K/100K	$3.44
o3	高度な推論	200K/100K	$3.5

モデルをデプロイする: Ctrl+Shift+P -> AI Toolkit: Deploy Model

---

エージェント パターン

シングルエージェント

from pathlib import Path
from agent_framework.openai import OpenAIChatClient

# ファイルからプロンプトを読み込む - インライン文字列としてプロンプトを埋め込まないこと
prompt = Path("prompts/assistant.md").read_text(encoding="utf-8")

client = OpenAIChatClient(
 model="gpt-5.1",
 api_key=os.getenv("FOUNDRY_API_KEY"),
 endpoint=os.getenv("FOUNDRY_ENDPOINT")
)

agent = {
 "name": "Assistant",
 "instructions": prompt, # prompts/assistant.md から読み込み
 "tools": [] # 必要に応じてツールを追加
}

response = await client.chat(
 messages=[{"role": "user", "content": "Hello"}],
 agent=agent
)

マルチエージェント オーケストレーション

from pathlib import Path
from agent_framework.workflows import SequentialWorkflow

# 各エージェントは専用ファイルからプロンプトを読み込み
researcher = {
 "name": "Researcher",
 "instructions": Path("prompts/researcher.md").read_text(encoding="utf-8")
}
writer = {
 "name": "Writer",
 "instructions": Path("prompts/writer.md").read_text(encoding="utf-8")
}

workflow = SequentialWorkflow(
 agents=[researcher, writer],
 handoff_strategy="on_completion"
)

result = await workflow.run(query="Write about AI agents")

高度なパターン: github.com/microsoft/agent-framework で以下を検索:

• Group Chat、Concurrent、Conditional、Loop
• Human-in-the-Loop、Reflection、Fan-out/Fan-in
• MCP、Multimodal、Custom Executors

---

コア ルール

プロンプト・テンプレート ファイル管理

ルール: プロンプトや出力テンプレートをコード内にインライン文字列として埋め込まないこと。常に別ファイルとして保存します。

理由: プロンプトはコードではなくコンテンツです。分離することで以下が可能になります:

• プロンプト内で何が変わったかを正確に表示するバージョン管理 diff
• 非開発者編集 (PM、プロンプト エンジニア) がコードに触れずに可能
• コード変更なしで異なるプロンプトの A/B テスト
• エージェント、言語、テスト ハーネス間での再利用
• 関心の分離 (ロジック vs. コンテンツ)

ディレクトリ規約:

project/
 prompts/ # すべてのシステム/エージェント プロンプト
 assistant.md # エージェント ロールごとに 1 ファイル
 researcher.md
 writer.md
 reviewer.md
 templates/ # エージェントが使用する出力テンプレート
 report-template.md # 構造化出力テンプレート
 email-template.md
 summary-template.md
 config/
 models.yaml # モデル設定

読み込みパターン:

from pathlib import Path

# プロンプトを読み込み
prompt = Path("prompts/assistant.md").read_text(encoding="utf-8")

# 出力テンプレートを読み込みプロンプトに注入
template = Path("templates/report-template.md").read_text(encoding="utf-8")
prompt_with_template = f"{prompt}\n\n## Output Format\n{template}"

ルール:

• すべてのシステム プロンプトを prompts/ ディレクトリに .md または .txt ファイルとして保存すること (必須)
• 出力形式テンプレートを templates/ ディレクトリに保存すること (必須)
• 1 文を超える長さのプロンプト テキストをコード内に直接埋め込まないこと (必須)
• プロンプトに Markdown 形式を使用すること (読みやすく、構造をサポート)
• ファイル名をエージェント ロール名にしたファイルにすること: prompts/{agent-name}.md
• 各プロンプト ファイルに簡潔なコメント ヘッダーを含めること (目的、バージョン、モデルターゲット)
• テンプレート変数 ({variable}) を使用してランタイムで注入されるコンテンツに対応させてもよい

開発

[成功] 実施すること:

• コーディング前にエージェント アーキテクチャを計画すること (Research -> Design -> Implement)
• 本番環境に Microsoft Foundry モデルを使用すること
• 初日からトレースを実装すること
• デプロイ前に評価データセットでテストすること
• 信頼性の高いエージェント応答に構造化出力を使用すること
• エラー処理とリトライ ロジックを実装すること
• エージェントをバージョン管理し、変更を追跡すること
• すべてのプロンプトを prompts/ ディレクトリの別ファイルとして保存すること
• 出力テンプレートを templates/ ディレクトリの別ファイルとして保存すること

[失敗] 実施しないこと:

• API キーやエンドポイントをハードコードすること
• プロンプトや出力テンプレートを複数行文字列としてコード内に埋め込むこと
• トレース設定をスキップすること (デバッグに重要)
• 評価なしでデプロイすること
• 本番環境で GitHub モデルを使用すること (無料ティアには制限あり)
• トークン制限とコンテキスト ウィンドウを無視すること
• エージェント ロジックをビジネス ロジックと混在させること

セキュリティ

• 認証情報を環境変数または Azure Key Vault に保存すること
• すべてのツール入力と出力を検証すること
• エージェント API にレート制限を実装すること
• 監査証跡用にエージェント アクションをログに記録すること
• Foundry リソースにロールベース アクセス制御 (RBAC) を使用すること
• OWASP AI Top 10 を確認すること: owasp.org/AI-Security-and-Privacy-Guide

パフォーマンス

• 適切な場合、モデル応答をキャッシュすること
• 複数のリクエストに対してバッチ処理を使用すること
• トークン使用量とコストを監視すること
• タイムアウト処理を実装すること
• I/O 操作に async/await を使用すること
• モデル サイズとレイテンシのトレードオフを検討すること

監視

• キーメトリクスを追跡すること: レイテンシ、成功率、トークン使用量、コスト
• 障害と異常に対するアラートを設定すること
• コンテキスト付きの構造化ログを使用すること
• Azure Monitor / Application Insights と統合すること
• 最適化の機会を見つけるため定期的にトレースを確認すること

---

本番環境チェックリスト

開発

• エージェント アーキテクチャがドキュメント化されている
• モデルが選択され、デプロイされている
• ツール/プラグインが実装およびテストされている
• リトライ付きエラー処理が実装されている
• 構造化出力が設定されている
• ハードコードされたシークレットがない
• すべてのプロンプトが prompts/ に別ファイルとして保存されている (コード内にインラインではない)
• すべての出力テンプレートが templates/ に保存されている (コード内にインラインではない)

モデル変更管理 (必須)

• モデル バージョンが明示的に固定されている (例: gpt-5.1-2026-01-15)
• モデル バージョンが環境変数で設定可能である
• 現在のモデルの評価ベースラインが保存されている
• モデル切り替え前に A/B 評価が実行されている
• モデル変更後、構造化出力スキーマが検証されている
• モデル変更後、ツール/関数呼び出しの精度が検証されている
• モデル変更が変更ログに評価結果と共にドキュメント化されている
• ドリフト検出の週次評価監視が設定されている
• ベースラインから 10% を超えるスコア低下のアラート閾値が設定されている

モデル変更テスト自動化 (必須)

• エージェントが設定を通じてモデルが注入されるようにモデル非依存として設計されている
• config/models.yaml が閾値付きのモデル テスト マトリックスを定義している
• 2 つのモデル (異なるプロバイダーからのプライマリ + フォールバック) に対してテストされている
• CI/CD の複数モデル比較パイプライン (週次 + モデル設定変更時) が設定されている
• デプロイが閾値チェックでゲートされている (CI は回帰時に失敗)
• フォールバック モデルが指定されドキュメント化されている
• 比較レポートが実行ごとに生成される (JSON + 人間が読める形式)
• 品質メトリクスと並行してコストとレイテンシ評価者が含まれている

可視化

• OpenTelemetry トレースが有効になっている
• トレース ビューアが テストされている
• 構造化ログが実装されている
• メトリクス収集が設定されている

評価

• 評価データセットが作成されている
• 評価者が定義されている (組み込み + カスタム)
• 評価実行が成功している
• 結果が品質閾値を満たしている
• 複数モデル比較が実行されている (2 以上のモデルがテストされている)
• フォールバック モデルが検証され、ドキュメント化されている
• モデル比較ベースラインが保存されている

セキュリティ & コンプライアンス

• 認証情報が Key Vault/環境変数にある
• 入力検証が実装されている
• RBAC が設定されている
• 監査ログが有効になっている
• OWASP AI Top 10 が確認されている

操作

• ヘルス チェックが実装されている
• レート制限が設定されている
• 監視アラートが設定されている
• デプロイ戦略が定義されている
• ロールバック計画がドキュメント化されている
• コスト監視が有効になっている

---

アンチパターン

• インラインプロンプト文字列: コード内に複数行文字列としてプロンプトを埋め込むこと -> prompts/ ディレクトリの別ファイルに保存すること
• 固定されていないモデル バージョン: 日付サフィックスなしで gpt-4o を使用すること -> 明示的に固定すること (例: gpt-5.1-2026-01-15)
• デプロイ前に評価なし: 評価データセットを実行せずにエージェントをデプロイすること -> 品質閾値でデプロイをゲートすること
• モノリシック エージェント: 1 つのエージェントがすべての領域とタスクを処理すること -> 明確なハンドオフで特化したエージェントに分割すること
• トークン コストを無視: リクエストごとのトークン使用量を監視しないこと -> コンポーネントごとのトークンを追跡し、予算を設定すること
• エラー回復の欠落: LLM 障害時のリトライやフォールバックがないこと -> バックオフ付きリトライと フォールバック モデルを実装すること
• トレース設定をスキップ: 可視化なしでデプロイすること -> 初日から OpenTelemetry トレースを有効にすること

---

リソース

公式ドキュメント:

• Agent Framework: github.com/microsoft/agent-framework
• Microsoft Foundry: ai.azure.com
• Azure AI Projects SDK: learn.microsoft.com/python/api/overview/azure/ai-projects
• OpenTelemetry: opentelemetry.io

AI Toolkit:

• モデル カタログ: Ctrl+Shift+P -> AI Toolkit: Model Catalog
• トレース ビューア: Ctrl+Shift+P -> AI Toolkit: Open Trace Viewer
• プレイグラウンド: Ctrl+Shift+P -> AI Toolkit: Model Playground

セキュリティ:

• OWASP AI セキュリティ: owasp.org/AI-Security-and-Privacy-Guide
• Azure セキュリティ ベスト プラクティス: learn.microsoft.com/azure/security

---

関連: AGENTS.md (エージェント動作ガイドライン) - Skills.md (一般的な本番環境プラクティス)

最終更新日: 2026 年 1 月 17 日

スクリプト

スクリプト	目的	使用方法
scaffold-agent.py	AI エージェント プロジェクトをスキャフォールド (Python/.NET) し、トレースと評価を含める	python scripts/scaffold-agent.py --name my-agent [--pattern multi-agent] [--with-eval]
validate-agent-checklist.ps1	エージェント プロジェクトを本番環境チェックリストに対して検証	./scripts/validate-agent-checklist.ps1 [-Path ./my-agent] [-Strict]
check-model-drift.ps1	モデル固定、データドリフト信号、ジャッジ LLM の準備状態を検証	./scripts/check-model-drift.ps1 [-Path ./my-agent] [-Strict]
run-model-comparison.py	複数のモデルに対して評価スイートを実行し、比較レポートを生成	python scripts/run-model-comparison.py --config config/models.yaml --dataset evaluation/core.jsonl

トラブルシューティング

問題	ソリューション
モデルが見つからない	Foundry ポータルでモデル デプロイを確認し、エンドポイント URL を確認
トレースが表示されない	エージェント作成前に AIInferenceInstrumentor().instrument() が呼び出されていることを確認
エージェントが無限ループ	max_turns 制限を設定し、終了条件を追加

参照資料

• トレースと評価
• マルチモデル パターン
• モデル ドリフトとジャッジ パターン
• モデル変更テスト自動化