# ADKの便利で実践的な使い方 🧪 エージェントのテストで、本番APIを叩くわけにはいきません。ADKのEnvironment Simulation機能を使えば、ツール呼び出しをインターセプトし、制御されたレスポンスに差し替えることで、本番システムに影響を与えずにエッジケースを再現できます。 📌 タイトル：Environment Simulation 🔗 URL： 🧩 概要 ADKのEnvironment Simulatorは、エージェント実行中のツール呼び出しをインターセプトし、制御されたレスポンスに置き換えます。エージェントのコードを一切変更せずに、エラー注入、固定レスポンス、条件付き注入、確率的障害、レイテンシシミュレーションが可能です。CallbackまたはPluginとして統合でき、注入設定→モック戦略→実ツール実行の優先順位で動作します。 🛠 使い方 Callbackとしての統合例です。 `google.adk.agents` から `LlmAgent` を、` から `EnvironmentSimulationFactory` を、同パッケージの `environment_simulation_config` から `EnvironmentSimulationConfig`、`InjectedError`、`InjectionConfig`、`ToolSimulationConfig` をインポートします。`EnvironmentSimulationConfig` の `tool_simulation_configs` に `ToolSimulationConfig` のリストを渡し、各ツールに対する注入設定を定義します。例えば `tool_name="get_user_profile"` に対して `InjectionConfig` で `InjectedError(injected_http_error_code=503, error_message="Service temporarily unavailable.")` を設定すると、503エラーが注入されます。作成した `config` を `EnvironmentSimulationFactory.create_callback(config)` でコールバックに変換し、`LlmAgent` の `before_tool_callback` パラメータに渡します。 固定レスポンスの注入： `InjectionConfig` の `injected_response` パラメータに辞書（例: `{"status": "ok", "order_id": "ORD-9999"}`）を渡すことで、ツール呼び出しに対して固定のレスポンスを返すことができます。 引数に基づく条件付き注入： `InjectionConfig` の `match_args` パラメータに引数パターン（例: `{"item_id": "ITEM-404"}`）を指定すると、ツール呼び出しの引数が一致した場合のみ注入が発動します。`injected_error` に `InjectedError(injected_http_error_code=404, error_message="Item not found.")` を設定すれば、特定の引数でのみ404エラーを返すことができます。 確率的な障害シミュレーション： `InjectionConfig` の `injection_probability` に確率値（例: `0.3` で30%）を設定し、`random_seed`（例: `42`）で再現性を確保します。`injected_error` に `InjectedError(injected_http_error_code=500, error_message="Internal server error.")` を指定すると、指定確率でランダムに500エラーが発生します。 レイテンシのシミュレーション： `InjectionConfig` の `injected_latency_seconds` に遅延秒数（例: `5.0`）を設定し、`injected_response` にレスポンス（例: `{"result": "slow but successful"}`）を指定すると、指定秒数の遅延後にレスポンスが返されます。 Mock Strategyモードでは、ツールスキーマから自動的にレスポンスを生成します。 `environment_simulation_config` から `MockStrategy` をインポートし、`ToolSimulationConfig` の `mock_strategy_type` に `MockStrategy.MOCK_STRATEGY_TOOL_SPEC` を設定します。これにより、`tool_name`（例: `"create_order"`）で指定したツールのスキーマから自動的にレスポンスが生成されます。 🏗 実践的な使い方 **API障害時のエージェント回復力テスト**: 503エラーや500エラーを注入して、エージェントがリトライやフォールバックを適切に行うかを検証します。本番システムに影響を与えることなく、障害シナリオを再現できます。 **条件付き注入によるエッジケーステスト**: `match_args`を使って特定の引数パターンでのみエラーを発生させます。例えば「存在しない商品ID」「在庫切れの商品」など、特定条件下でのエージェントの振る舞いをピンポイントでテストできます。 **確率的障害でのリアルなテスト**: `injection_probability`を使って30%の確率でエラーを発生させ、不安定なAPIとのやり取りをシミュレートします。`random_seed`を固定すれば再現性のあるテストになります。 **環境データの提供によるリアルなモック生成**: `environment_data`にDBスナップショットなどのコンテキストを渡すと、Mock Strategyがよりリアルなレスポンスを生成します。 DBスナップショットなどのコンテキストデータ（例: 商品リストの辞書）を `json.dumps()` でJSON文字列に変換し、`EnvironmentSimulationConfig` の `environment_data` パラメータに渡します。Mock Strategyはこの環境データを参照して、よりリアルなレスポンスを生成します。 **注入とモック戦略の組み合わせ**: 特定の条件ではエラーを注入し、それ以外はMock Strategyで自動生成するという組み合わせが可能です。注入設定が先に評価され、マッチしなければモック戦略にフォールバックします。 💡 ユースケース 🔧 外部API障害時のエージェント回復力の検証 🎯 特定条件下でのエッジケース再現テスト 📉 不安定なAPIとのやり取りの確率的シミュレーション ⏱ レイテンシの高いAPIでのタイムアウト処理の検証 ⚠️ 注意点 - `injected_latency_seconds`の上限は120秒です。 - `InjectionConfig`はエラーとレスポンスのどちらか一方のみ指定可能で、両方同時には設定できません。 - `tool_name`は登録されたツール名と完全一致する必要があります。タイポに注意してください。 - Mock Strategyはツールスキーマに依存するため、スキーマが不十分だと生成されるレスポンスの質が下がります。 ✨ Environment Simulationは、本番環境を汚さずにエッジケースを再現できる強力なテスト基盤です。エラー注入と条件付きモックを組み合わせて、あらゆる障害シナリオに対するエージェントの耐性を検証しましょう！ #ADK# #AIAgent#

# ADK 2.0の便利だけど知られていない機能 🌍 エージェントのプロンプトを手作業で調整する代わりに、自動で最適化してくれたら効率的だと思いませんか？ ADK 2.0の最適化機能は、サンプラーとエージェントオプティマイザーを組み合わせて、エージェントのインストラクションを自動的に改善する仕組みです。 📌 タイトル：最適化 (Optimization) 🔗 URL： 🧩 概要 最適化機能は、Samplers（候補の評価）とAgent Optimizers（インストラクションの改善）の2つのコンポーネントで構成されます。`LocalEvalSampler` は候補エージェントを評価データセットに対して実行しスコアを算出します。オプティマイザーとしては、GEPAアルゴリズムを用いてルートエージェントのプロンプトを最適化する `GEPARootAgentPromptOptimizer` と、「実行→評価→批評→書き直し」の反復サイクルで改善する `SimplePromptOptimizer` が用意されています。最適化の結果は `OptimizerResult` に格納され、スコア付きの最適化済みエージェントが得られます。 🛠 使い方 CLIから `adk optimize` コマンドで最適化を実行できます。 ```python import asyncio from google.adk.evaluation.eval_config import EvalConfig from google.adk.evaluation.local_eval_sets_manager import LocalEvalSetsManager from google.adk.optimization.local_eval_sampler import LocalEvalSampler from google.adk.optimization.local_eval_sampler import LocalEvalSamplerConfig from google.adk.optimization.simple_prompt_optimizer import SimplePromptOptimizer from google.adk.optimization.simple_prompt_optimizer import ( SimplePromptOptimizerConfig, ) # サンプラーの設定 sampler_config = LocalEvalSamplerConfig( eval_config=EvalConfig(criteria={"response_match_score": 0.75}), app_name="my_agent", train_eval_set="train_eval_set", ) sampler = LocalEvalSampler(sampler_config, LocalEvalSetsManager(agents_dir=".")) # オプティマイザーの実行 optimizer = SimplePromptOptimizer(config=SimplePromptOptimizerConfig()) result = sampler)) # 最適化されたエージェントとスコアを取得 best = result.optimized_agents[0] best_agent = best.optimized_agent print(f"Score: {best.overall_score}") ``` 🏗 本番システムへの組み込み方 ・定期的に最適化を実行し、評価データセットの更新に合わせてプロンプトを継続的に改善する ・`SimplePromptOptimizer` で素早くイテレーションし、`GEPARootAgentPromptOptimizer` で本格的な探索を行う ・最適化前後のスコアを比較し、改善が確認できた場合のみプロンプトを更新する ・評価データセットを実際のユーザーインタラクションから構築し、実用的な最適化を実現する 💡 ユースケース 📈 エージェントのプロンプトを評価スコアに基づいて自動改善する 🔬 複数のプロンプト候補を体系的に比較して最良のものを選定する 🔄 モデル変更やAPI仕様変更後に、プロンプトを新環境に最適化し直す 🎯 特定のタスク（コード生成、要約、分類など）に特化したプロンプトチューニングを行う ⚠️ 注意点 `GEPARootAgentPromptOptimizer` はルートエージェントのプロンプトのみを最適化対象とします。サブエージェントのプロンプト最適化には対応していないため、必要に応じて個別に最適化を行ってください。また、最適化には複数回の評価実行が必要となるため、LLMのAPI呼び出しコストに注意が必要です。 ✨ 最適化機能を活用すれば、試行錯誤に頼っていたプロンプト改善をデータ駆動で自動化できます。定期的な最適化サイクルで、エージェントの品質を継続的に向上させましょう。 #ADK# #AIAgent#

# ADKの便利で実践的な使い方 🎭 固定プロンプトのテストだけでは、実際のユーザーの予測不可能な行動を再現できません。ADKのUser Simulation機能は、「せっかちな顧客」「曖昧な依頼者」といったペルソナ駆動の対話シミュレーションで、エージェントの堅牢性を自動検証します。 📌 タイトル：User Simulation 🔗 URL： 🧩 概要 ADKのUser Simulation機能は、AIが生成するユーザープロンプトを使って会話エージェントを動的に評価します。固定的なテストケースではなく、シミュレートされたユーザーがエージェントのレスポンスに適応的に応答するため、予測不可能な会話フローのテストに最適です。ConversationScenarioは`starting_prompt`（初期メッセージ）、`conversation_plan`（達成すべきゴールのガイドライン）、`user_persona`（ユーザー特性）の3要素で構成されます。 🛠 使い方 ユーザーシミュレーターの基本設定です。 ```json { "user_simulator_config": { "model": "gemini-flash-latest", "model_configuration": { "thinking_config": { "include_thoughts": true, "thinking_budget": 10240 } }, "max_allowed_invocations": 20 } } ``` ADKは3つのプリセットペルソナを提供しています。 | 振る舞い | EXPERT | NOVICE | EVALUATOR | |----------|--------|--------|-----------| | 情報提供 | 詳細志向 | ゴール志向 | 詳細志向 | | 質問への回答 | 関連質問のみ | すべて回答 | 関連質問のみ | | 不正確さの指摘 | する | しない | しない | | エラー対処 | 1回試行 | しない | しない | | トーン | プロフェッショナル | カジュアル | カジュアル | カスタムペルソナをConversationScenarioのJSONで直接定義できます。 ```json { "user_persona": { "id": "IMPATIENT_USER", "description": "急いでいて、すぐにイライラするユーザー", "behaviors": [ { "name": "Short responses", "description": "簡潔で不完全な返答をする", "behavior_instructions": [ "Keep responses under 10 words", "Omit polite phrases" ], "violation_rubrics": [ "Response exceeds 10 words", "Response is overly polite" ] } ] } } ``` 評価シナリオの自動生成も可能です。 ```bash adk eval_set generate_eval_cases \ --user_simulation_config_file= ``` 🏗 実践的な使い方 **「せっかちな顧客」ペルソナでの堅牢性テスト**: IMPATIENT_USERペルソナを使い、10語以下の短い返答や丁寧な表現の省略をシミュレートします。エージェントが不十分な情報からでも適切にヒアリングし、タスクを完了できるかを検証できます。カスタマーサポートエージェントの品質向上に特に有効です。 **「曖昧な依頼者」ペルソナの活用**: 「具体的な要件を示さず、抽象的な表現で依頼するユーザー」をシミュレートします。エージェントが適切な質問で要件を明確化できるか、曖昧な入力で暴走しないかをテストできます。 **プリセットペルソナの使い分け**: EXPERTペルソナはエージェントの技術的正確性を検証し、NOVICEペルソナは初心者にも分かりやすい説明ができるかを検証します。EVALUATORペルソナは中立的な立場でエージェントのパフォーマンスを評価します。 **シナリオの自動生成による網羅性向上**: `generate_eval_cases`コマンドで多様な会話シナリオを自動生成し、手動では思いつかないエッジケースを発見できます。`generation_instruction`でシナリオの方向性を指定し、`environment_context`でバックエンドの状態を提供することで、より現実的なシナリオが生成されます。 💡 ユースケース 🎭 カスタマーサポートエージェントの多様なユーザータイプへの対応力検証 🧪 固定テストでは発見できない会話パスのエッジケース発見 🤖 新規ペルソナ定義によるドメイン特化の堅牢性テスト 📊 大量のシナリオ自動生成による網羅的な品質評価 ⚠️ 注意点 - `max_allowed_invocations`を適切に設定しないと、シミュレーションが無限に続く可能性があります。デフォルト20からドメインに応じて調整してください。 - シナリオの自動生成にはVertex Gen AI Evaluation Service APIが必要です。 - カスタムペルソナの`violation_rubrics`が不明確だと、ペルソナの一貫性が保てない場合があります。具体的な違反条件を定義してください。 - シミュレーターのモデルにthinking機能を有効にすると、より自然な対話が生成されますが、コストが増加します。 ✨ User Simulationは、固定テストの限界を突破する強力な機能です。ペルソナを活用して「実際のユーザーならどう振る舞うか」をシミュレートし、エージェントの堅牢性を多角的に検証しましょう！ #ADK# #AIAgent#

# ADKの便利で実践的な使い方 📏 エージェントの品質を「何で」測るかは、評価の成否を分けます。ADKのEvaluation Criteriaは、ツール軌跡の正確性からハルシネーション検出、安全性評価まで、多角的な評価基準を組み込みで提供します。 📌 タイトル：Evaluation Criteria 🔗 URL： 🧩 概要 ADKは複数の組み込み評価基準を提供し、すべて0.0〜1.0のスコアで評価結果を返します。**tool_trajectory_avg_score**はエージェントのツール呼び出し順序を検証し、**response_match_score**はROUGE-1でレスポンスの一致度を測定します。**hallucinations_v1**はコンテキストに対する回答の根拠を検証し、**safety_v1**は有害コンテンツの有無を評価します。**multi_turn_task_success_v1**は複数ターンの会話でタスク達成度を測定します。 🛠 使い方 各評価基準はJSON設定ファイルで定義します。 **tool_trajectory_avg_score** — 3つのマッチタイプを選択できます。 ```json { "criteria": { "tool_trajectory_avg_score": { "threshold": 1.0, "match_type": "EXACT" } } } ``` - `EXACT`: 期待されるツール呼び出しと完全一致（余分な呼び出しも不足も不可） - `IN_ORDER`: 期待されるツールが順序通りに出現（間に他の呼び出しがあってもOK） - `ANY_ORDER`: 期待されるツールがすべて存在（順序は問わない） **response_match_score** — ROUGE-1によるユニグラム一致度です。 ```json { "criteria": { "response_match_score": 0.8 } } ``` **hallucinations_v1** — レスポンスの各文をコンテキストに対して検証します。 ```json { "criteria": { "hallucinations_v1": { "threshold": 0.8, "judge_model_options": { "judge_model": "gemini-flash-latest" }, "evaluate_intermediate_nl_responses": true } } } ``` 各文には「supported（支持）」「unsupported（不支持）」「contradictory（矛盾）」「disputed（議論あり）」「not_applicable（該当なし）」のラベルが付与されます。スコアはsupportedとnot_applicableの割合で計算されます。 **safety_v1** — ヘイトスピーチ、ハラスメント、危険な情報の有無を評価します。 ```json { "criteria": { "safety_v1": 0.8 } } ``` **multi_turn_task_success_v1** — 会話全体を通じたタスク達成度を評価します。 ```json { "criteria": { "multi_turn_task_success_v1": 0.8 } } ``` 🏗 実践的な使い方 **ツール軌跡の厳密な検証**: 金融取引や医療情報など、ツールの呼び出し順序が重要なドメインでは`EXACT`マッチタイプを使用します。例えば「まず認証→次に残高確認→最後に送金」という順序が厳守されるべきケースで、エージェントが正しい手順を踏んでいるかを検証できます。 **柔軟なツール検証**: 探索的なタスクでは`ANY_ORDER`を使い、必要なツールがすべて呼ばれたかだけを確認します。`IN_ORDER`は、主要なステップの順序は保証したいが、間に補助的なツール呼び出しを許容するケースに適しています。 **ハルシネーション検出の実践**: RAGベースのエージェントで`hallucinations_v1`を使用し、検索結果に基づかない情報をエージェントが生成していないかを自動検出します。`evaluate_intermediate_nl_responses`を有効にすれば、最終回答だけでなく中間的な回答も含めて検証できます。 **安全性とタスク達成の両立**: `safety_v1`と`multi_turn_task_success_v1`を組み合わせることで、「安全だがタスクを達成できないエージェント」や「タスクは達成するが不適切な内容を含むエージェント」を検出できます。 💡 ユースケース 🎯 金融・医療エージェントでのツール呼び出し順序の厳密な検証 🔍 RAGエージェントのハルシネーション自動検出 🛡 カスタマーサポートエージェントの安全性評価 📈 マルチターン対話でのタスク達成率の定量測定 ⚠️ 注意点 - `safety_v1`、`multi_turn_task_success_v1`、`multi_turn_trajectory_quality_v1`、`multi_turn_tool_use_quality_v1`はGoogle Cloudプロジェクトの設定（`GOOGLE_CLOUD_PROJECT`、`GOOGLE_CLOUD_LOCATION`環境変数）が必要です。 - LLMベースの評価基準はジャッジモデルの判断にばらつきがあります。`num_samples`を設定して複数回サンプリングし、多数決で結果を安定させることを推奨します。 - `response_match_score`はROUGE-1（単語の重なり）のみで意味的な同等性は評価しません。意味的な評価には`final_response_match_v2`を検討してください。 ✨ 適切な評価基準の選択は、エージェントの品質管理の基盤です。ドメインの特性に合わせてEXACT/IN_ORDER/ANY_ORDERを使い分け、ハルシネーション検出と安全性評価を組み合わせて多角的に品質を担保しましょう！ #ADK# #AIAgent#

# ADK 2.0の便利だけど知られていない機能 🌍 標準メトリクスだけでは測れない、自社独自の評価基準でエージェントを採点できたら理想的だと思いませんか？ ADK 2.0のカスタム評価メトリクス機能は、Python関数として独自の評価ロジックを定義し、エージェントの品質を自由な基準で測定できる仕組みです。 📌 タイトル：カスタム評価メトリクス (Custom Metrics) 🔗 URL： 🧩 概要 カスタム評価メトリクスは、`EvaluationResult` を返すPython関数として定義します。関数には `eval_metric`（評価メトリクスの定義）、`actual_invocations`（実際のエージェントの応答）、`expected_invocations`（期待される応答）、`conversation_scenario`（会話シナリオ）がパラメータとして渡されます。非同期関数もサポートされており、外部サービスとの連携も可能です。 🛠 使い方 カスタムメトリクス関数を作成し、評価設定JSONに登録します。 ```python from google.adk.evaluation.eval_metrics import EvalStatus from google.adk.evaluation.evaluator import EvaluationResult async def response_length_metric( eval_metric, actual_invocations, expected_invocations, conversation_scenario ) -> EvaluationResult: # 応答の長さが適切か評価 last_response = "".join( part.text for part in actual_invocations[-1].final_response.parts ) score = 1.0 if len(last_response) < 500 else 0.5 return EvaluationResult( overall_score=score, overall_eval_status=( EvalStatus.PASSED if score >= eval_metric.criterion.threshold else EvalStatus.FAILED ), ) ``` 評価設定JSONでは、`criteria`（閾値）と `custom_metrics` の `code_config.name`（関数のインポートパス）を指定して登録します。 ```json { "criteria": { "response_length": {"threshold": 0.8} }, "custom_metrics": { "response_length": { "code_config": {"name": "my_metrics.response_length_metric"} } } } ``` 🏗 本番システムへの組み込み方 ・ドメイン固有の品質基準（正確性、トーン、コンプライアンス等）をメトリクスとして実装する ・CI/CDパイプラインでカスタムメトリクスを自動実行し、品質閾値を下回った場合にデプロイをブロックする ・非同期メトリクスを活用して、外部の評価APIやLLM-as-a-Judgeと連携する ・複数のメトリクスを組み合わせて、エージェントの総合的な品質スコアを算出する 💡 ユースケース 📏 応答の簡潔さや情報密度を独自基準で評価する 🏢 業界規制やコンプライアンス要件への準拠を自動チェックする 🎯 特定のツール呼び出しパターンが期待通りか検証する 🗣 応答のトーンや丁寧さをLLM-as-a-Judgeで自動採点する ⚠️ 注意点 カスタムメトリクス関数内で重い処理を行う場合、評価全体の実行時間に影響します。非同期関数を活用し、必要に応じてタイムアウトを設定してください。また、`code_config` のモジュールパスは評価実行環境からインポート可能である必要があります。 ✨ カスタム評価メトリクスにより、標準メトリクスではカバーしきれない独自の品質基準を体系的に運用できます。自社のユースケースに合わせた評価を構築しましょう。 #ADK# #AIAgent#

# ADKの便利で実践的な使い方 🧪 エージェントのプロンプトを変更したら、品質が下がっていないか確認していますか？ADKのEvaluation機能を使えば、テストファイル方式とデータセット方式の2つのアプローチでエージェントの品質を体系的に検証できます。CIに組み込めば、プロンプト変更の回帰テストも自動化できます。 📌 タイトル：Evaluation 概要 🔗 URL： 🧩 概要 ADKは、エージェントのパフォーマンスを評価するための2つの主要な方法を提供します。**テストファイル方式**は`.test.json`ファイルに単一セッション（複数ターン可）を記述し、ユニットテストのように高速に反復できます。**Evalset方式**は複数セッション・多数のターンを含む統合テスト向けです。一部の評価基準（レスポンス品質、安全性、マルチターン品質など）はVertex Gen AI Evaluation Service APIを必要とします。評価基準として`tool_trajectory_avg_score`、`response_match_score`、`hallucinations_v1`、`safety_v1`などの組み込みメトリクスが利用可能です。 🛠 使い方 テストファイルには、ユーザークエリ、期待されるツール使用軌跡、期待されるレスポンスを記述します。 評価の実行方法は3つあります。 **Web UI**での対話的な評価： ```bash adk web path/to/agents_dir ``` **pytest**との統合： `AgentEvaluator.evaluate()` を `await` で呼び出し、`agent_module` に評価対象のエージェントモジュール名（例: `"home_automation_agent"`）、`eval_dataset_file_path_or_dir` にテストファイルのパス（例: `"tests/integration/fixture/test.test.json"`）を指定します。 **CLI**での実行： ```bash adk eval --config_file_path= ``` 評価基準のしきい値は`test_config.json`で設定します。 ```json { "criteria": { "tool_trajectory_avg_score": 1.0, "response_match_score": 0.8 } } ``` デフォルトでは、ツール軌跡は100%一致を要求し、レスポンスマッチングは80%の類似度を許容します。 🏗 実践的な使い方 **エージェント更新時の回帰テスト**: プロンプトやツール定義を変更するたびに、既存のテストファイルを使って回帰テストを実行します。`tool_trajectory_avg_score`でツール選択の正確性を、`response_match_score`でレスポンスの品質を定量的に検証できます。品質低下を早期に検出できるため、安心してプロンプトの改善を繰り返せます。 **テストファイル方式で高速イテレーション**: 開発中は`.test.json`ファイルを使ったユニットテスト的なアプローチが最適です。単一セッションの期待値を記述し、pytestで自動実行すれば、コード変更のたびに数秒で品質を確認できます。エッジケースごとにテストファイルを追加していくことで、テストカバレッジを段階的に拡充できます。 **データセット方式でバッチ評価**: 本番に近い複雑なシナリオは、Evalset方式で多数のセッションをまとめて評価します。マルチターンの会話フローや、異なるユーザーパターンを網羅的にテストでき、統合テストとして機能します。 **CIパイプラインへの統合**: `adk eval`コマンドをCIに組み込めば、プロンプト変更のプルリクエストごとに自動で品質チェックが実行されます。しきい値を下回った場合はCIを失敗させることで、品質低下したプロンプトのマージを防げます。 💡 ユースケース 🔄 プロンプト変更時の回帰テスト自動化 ⚡ テストファイル方式での高速な開発イテレーション 📊 データセット方式での網羅的なバッチ評価 🔗 CI/CDパイプラインへの品質ゲート統合 ⚠️ 注意点 - 一部の評価基準（レスポンス品質、安全性、マルチターン品質など）はVertex Gen AI Evaluation Service API（有料のGoogleサービス）が必要です。 - テストファイルのしきい値は厳しすぎると偽陰性が増え、緩すぎると品質低下を見逃します。初期値から段階的に調整してください。 - LLMベースの評価基準（`hallucinations_v1`など）はジャッジモデルの判断にばらつきがあるため、`num_samples`で複数回サンプリングすることを推奨します。 ✨ ADKのEvaluation機能を活用すれば、エージェントの品質管理を「感覚」から「定量的な基準」に変えられます。まずはテストファイル方式で始めて、CI統合へと進めてみてください！ #ADK# #AIAgent#

# ADK 2.0の便利だけど知られていない機能 🌍 エージェントのツール呼び出しを制御下に置いて、外部サービスなしでテストできたら便利だと思いませんか？ ADK 2.0の環境シミュレーション機能は、ツール呼び出しをインターセプトし、制御されたレスポンスに差し替えることで、外部依存なしにエージェントの振る舞いを検証できる仕組みです。 📌 タイトル：環境シミュレーション (Environment Simulation) 🔗 URL： 🧩 概要 環境シミュレーションは、エージェントが実行するツール呼び出しをインターセプトし、実際の外部サービスを呼ばずに制御されたレスポンスを返す機能です。3つのステップで構成されます。まずインジェクション設定でどのツール呼び出しを差し替えるか定義し、次にモック戦略でどのようなレスポンスを返すか決定し、最後にパススルーで差し替え対象外の呼び出しはそのまま実行します。コールバック方式（`before_tool_callback`）またはプラグインとして組み込めます。 🛠 使い方 インジェクション設定では、固定ペイロード、引数条件付き応答、HTTPエラー注入、確率的な失敗、人工的な遅延など、多彩なモックパターンを定義できます。 ```python from import ( InjectionConfig, ToolSimulationConfig, ) # 固定レスポンスの注入 ToolSimulationConfig( tool_name="weather_api", injection_configs=[ InjectionConfig( injected_response={"temperature": 25, "condition": "sunny"} ) ], ) # 条件付き応答（引数に基づく） ToolSimulationConfig( tool_name="search_api", injection_configs=[ InjectionConfig( match_args={"query": "ADK"}, injected_response={"results": ["ADK documentation"]}, ) ], ) ``` モック戦略としてLLMベースの方式を選ぶと、ツールのスキーマに合致するリアルなレスポンスを自動生成し、状態の追跡も行えます。 🏗 本番システムへの組み込み方 ・CIパイプラインで外部API呼び出しをすべてモックし、安定した自動テストを実現する ・確率的な失敗注入でエージェントのエラーハンドリングとリトライロジックを検証する ・人工的な遅延を設定して、タイムアウト処理が正しく機能するか確認する ・LLMベースのモック戦略を使い、スキーマ準拠のリアルなテストデータを自動生成する 💡 ユースケース 🔌 外部APIに依存しないエージェントの単体テストを構築する 💥 ネットワーク障害やHTTPエラーへのエージェントの耐障害性をテストする ⏱ 高遅延環境でのエージェントの振る舞いを検証する 🔄 複数のツール呼び出しを跨ぐ複雑なワークフローのステートフルなテストを行う ⚠️ 注意点 モック戦略でLLMベースの自動生成を使う場合、生成されるレスポンスは実際のAPIレスポンスと異なる場合があります。重要なテストでは固定ペイロードとの併用をお勧めします。また、パススルー設定を誤ると意図しない外部呼び出しが発生する可能性があるため、インジェクション対象の範囲を慎重に設計してください。 ✨ 環境シミュレーションを活用すれば、外部サービスの状態に左右されない堅牢なテスト環境を構築できます。障害パターンの注入で、エージェントの信頼性を飛躍的に高めましょう。 #ADK# #AIAgent#

# ADKの便利で実践的な使い方 🔍 エージェントが「なぜその判断をしたのか」を追跡できていますか？ADKのObservability機能を使えば、ツール選択の理由からLLMへの完全なプロンプトまで、エージェントの内部動作を透明化できます。本番障害の原因特定にも不可欠な機能です。 📌 タイトル：Observability / Logging 🔗 URL： 🧩 概要 ADKはPythonの標準`logging`モジュールとOpenTelemetryを統合した構造化ログ機能を提供します。DEBUG/INFO/WARNING/ERROR/CRITICALの5段階のログレベル（デフォルトはINFO）で、LLMへの完全なプロンプト、ツール実行の引数と結果、エージェントのライフサイクルイベントなどを記録できます。GCPのCloud Loggingとのネイティブ連携により、GKE上のエージェントのログを一元管理することも可能です。 🛠 使い方 基本的なログ設定は以下の通りです。 Pythonの `logging` モジュールをインポートし、`logging.basicConfig()` で `level=logging.DEBUG` とフォーマット文字列（`'%(asctime)s - %(levelname)s - %(name)s - %(message)s'`）を設定します。 CLIからの起動時にログレベルを指定できます。 ```bash adk web --log_level DEBUG path/to/agents_dir ``` DEBUGレベルでは、LLMに送信される完全なプロンプト内容が確認できます。デフォルトではプロンプト内容は省略されるため、OpenTelemetryの環境変数で明示的に有効化する必要があります。 ```bash export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true ``` GCPのCloud Loggingにログを送信する場合は、専用のエクスポーターを使用します。 ` から `get_gcp_exporters` をインポートし、`get_gcp_exporters(enable_cloud_logging=True)` を呼び出してGCPエクスポーターを取得します。 CLIからGCPエクスポートを有効化する場合はさらに簡単です。 ```bash adk web --otel_to_cloud path/to/agents_dir ``` 🏗 実践的な使い方 **本番インシデントの根本原因分析**: DEBUGログを有効にすると、エージェントがLLMに送った完全なプロンプト（システム指示、会話履歴、ツール定義）とレスポンスが確認できます。「なぜ間違ったツールを選択したのか」「なぜ期待と異なる回答をしたのか」を、LLMとのやり取りレベルで追跡できます。 **予期しないツール呼び出しループの検出**: INFOレベルのログではツール実行の名前と引数が記録されます。同じツールが短時間に繰り返し呼ばれているパターンを検出すれば、エージェントが無限ループに陥っていることを早期発見できます。Cloud Loggingと組み合わせれば、アラート設定も可能です。 **GKE環境での一元管理**: `get_gcp_exporters`を使えば、複数のエージェントインスタンスのログがCloud Loggingに集約されます。OpenTelemetryのSemantic Conventionsに準拠した構造化ログにより、エージェント名やツール名でフィルタリングしながら横断的に動作を分析できます。 **本番と開発のログレベル使い分け**: 本番環境ではINFOまたはWARNINGを推奨し、アクティブなトラブルシューティング時のみDEBUGを有効にします。DEBUGレベルではプロンプト全文が記録されるため、機密データやPIIが含まれる可能性がある点に注意が必要です。 💡 ユースケース 🔎 エージェントのツール選択戦略の効率性分析 🚨 本番障害時の根本原因の迅速な特定 📊 Cloud Loggingでの複数エージェントの横断的モニタリング 🔄 ツール呼び出しの無限ループ検出とアラート ⚠️ 注意点 - `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true`を有効にすると、ユーザープロンプトとエージェントレスポンスの全文がログに記録されます。機密データやPIIの漏洩リスクがあるため、本番環境での使用には注意してください。 - DEBUGレベルのログは非常に詳細でストレージコストが増大するため、常時有効にするのは避けてください。 - Cloud Loggingへのエクスポートには適切なGCPプロジェクトの設定とIAM権限が必要です。 ✨ Observability機能は、エージェントの「ブラックボックス」を開く鍵です。開発時はDEBUGでプロンプトレベルの詳細を確認し、本番ではINFOレベル＋Cloud Loggingで運用監視を実現しましょう！ #ADK# #AIAgent#

# ADK 2.0の便利だけど知られていない機能 🌍 エージェントの評価で「実際のユーザーとの会話」を再現できたら、テストの質が格段に上がると思いませんか？ ADK 2.0のユーザーシミュレーション機能は、多様なペルソナを持つ仮想ユーザーとの会話を動的に生成し、エージェントの応答品質を体系的に評価できる仕組みです。 📌 タイトル：ユーザーシミュレーション (User Simulation) 🔗 URL： 🧩 概要 ユーザーシミュレーションは、エージェント評価のために動的な会話プロンプトを自動生成する機能です。`ConversationScenario` を定義し、`starting_prompt`（会話の開始メッセージ）、`conversation_plan`（会話の進行計画）、`user_persona`（ユーザーの振る舞い）を指定することで、現実的な対話パターンを再現します。組み込みペルソナとして、EXPERT（詳細志向で誤りを指摘する）、NOVICE（指示を待つ受動的なユーザー）、EVALUATOR（詳細志向だが誤りの指摘はしない）の3種が用意されています。 🛠 使い方 CLIから `adk eval_set generate_eval_cases` コマンドで評価ケースを生成できます。カスタムペルソナを作成する場合は `UserPersona` クラスを使います。 ```python from google.adk.evaluation.conversation_scenarios import ConversationScenario from google.adk.evaluation.simulation.user_simulator_personas import ( UserBehavior, UserPersona, ) # カスタムペルソナの定義 impatient_user = UserPersona( id="IMPATIENT", description="短い応答を好み、長い説明には不満を示す", behaviors=[ UserBehavior( name="Short responses", description="短く、ときに不完全な応答をする", behavior_instructions=["応答は10語以内にする", "丁寧な言い回しは省く"], violation_rubrics=["応答が10語を超えている"], ) ], ) # シナリオの定義 scenario = ConversationScenario( starting_prompt="旅行の予約を手伝ってください", conversation_plan="目的地→日程→予算の順に確認し、最終的に予約を完了する", user_persona=impatient_user ) ``` 🏗 本番システムへの組み込み方 ・CI/CDパイプラインに評価シナリオを組み込み、エージェント更新時に自動でリグレッションテストを実行する ・EXPERT/NOVICE/EVALUATORの3ペルソナを使い分けて、異なるユーザー層での応答品質を網羅的に検証する ・`conversation_plan` を業務シナリオに合わせて設計し、実際の利用パターンに近い評価を行う ・カスタムペルソナを作成して、自社サービス特有のユーザー行動パターンをシミュレートする 💡 ユースケース 🧪 新しいプロンプトやモデルへの変更後に、会話品質のリグレッションを自動検出する 👥 初心者ユーザーと上級者ユーザーで異なる応答戦略が機能するか検証する 📊 複数シナリオを一括実行して、エージェントの弱点を体系的に洗い出す 🔄 会話の途中で話題が変わるケースや、曖昧な質問への対応力を評価する ⚠️ 注意点 シミュレーションはLLMベースで生成されるため、同一シナリオでも実行ごとに会話の展開が微妙に異なる場合があります。評価の再現性を確保するには、複数回実行して統計的に判断することをお勧めします。また、組み込みペルソナはそれぞれ異なる振る舞いをするため、評価目的に合ったペルソナを選択してください。 ✨ ユーザーシミュレーションを活用することで、実ユーザーを巻き込まずにエージェントの対話品質を継続的に改善できます。多様なペルソナでの評価を習慣化しましょう。 #ADK# #AIAgent#