# ADKの便利で実践的な使い方 長時間タスクが途中で落ちても、最初からやり直し…なんてもう古い！💪 ADKのResume Agents機能を使えば、チェックポイントベースで中断箇所から再開できます。HITLの承認待ちフローにも対応しており、エージェントの信頼性が格段に向上します。 ## 📌 タイトル Resume Agents — チェックポイントベースのワークフロー再開 ## 🔗 URL ## 🧩 概要 Resume Agentsは、中断されたADKワークフローを完全に再起動することなく、停止した地点から継続する機能です。イベントログと状態の保存により進捗を追跡し、成功済みステップのスキップやHITL（Human-in-the-Loop）の承認待ちフローの再開を実現します。 ## 🛠 使い方 `ResumabilityConfig`を有効化してAppを構成します。 `google.adk` から `App` を、`google.adk.runtime` から `ResumabilityConfig` をインポートします。`App` のコンストラクタで `resumability_config=ResumabilityConfig(is_resumable=True)` を指定することで、チェックポイントベースの再開機能が有効になります。`name` にアプリケーション名、`root_agent` にルートエージェントを渡します。 再開時は同じ`invocation_id`を指定して実行します。 再開時は ` のように、中断時と同じ `invocation_id` を指定して実行します。 ## 🏗 実践的な使い方 - **Sequential Agent**: 次に実行すべきサブエージェントを自動特定して再開 - **Loop Agent**: 最後に完了したイテレーションから継続 - **Parallel Agent**: 未完了のサブエージェントのみ再実行 - **HITL承認フロー**: 人間の承認待ちで中断したワークフローが、承認後に自動再開 - カスタムエージェントでは`BaseAgentState`を拡張し、各ステップ後にチェックポイントを設定 ## 💡 ユースケース - 数時間かかるデータ処理パイプラインの途中障害からの復旧 - 人間の承認が必要な経費申請や契約書レビューのワークフロー - マルチステップのAPI連携で部分的に成功した処理の続行 - 本番環境でのエージェント障害時のダウンタイム最小化 ## ⚠️ 注意点 - ツールは**少なくとも1回**実行され、再開時に複数回実行される可能性があります（冪等性の確保が重要） - 中断から再開までの間にワークフロー定義を変更するとサポート対象外です - 現時点ではWeb UIとCLIからの再開はサポートされていません ## ✨ 中断に強いエージェントは、本番運用の必須条件です。Resume Agentsを活用して、障害に負けないロバストなワークフローを構築しましょう！🚀 #ADK# #AIAgent#

# ADKの便利で実践的な使い方 同じシステムプロンプトやツール定義を何度も送信していませんか？Context Cachingで繰り返しのトークンコストを大幅に削減しましょう💰 📌 **タイトル**: Context Caching 🔗 **URL**: ## 🧩 概要 Context Cachingは、LLMに送信するコンテキスト（システムインストラクションやツール定義など）の静的な部分をキャッシュし、繰り返しのトークンコストを削減する機能です。 `ContextCacheConfig` を設定することで、毎回のリクエストで同じプレフィックストークンを再送信する代わりに、キャッシュされたコンテキストを参照するようになります。 特にマルチユーザー環境で同じエージェント（同じプロンプト・ツール定義）を多くのユーザーが利用する場合、コスト最適化の効果が顕著です。 ## 🛠 使い方 `google.adk` から `Agent` を、`google.adk.agents` から `ContextCacheConfig` をインポートします。`ContextCacheConfig(max_entries=100, ttl_seconds=3600)` でキャッシュエントリの上限と有効期間（秒）を設定します。この `cache_config` を `Agent` の `context_cache_config` パラメータに渡すことで、`instruction` に記述した長いシステムプロンプトや `tools` に指定したツール定義（`search_kb`、`create_ticket`、`escalate` など）の静的部分がキャッシュされ、繰り返しのトークンコストが削減されます。 ## 🏗 実践的な使い方 **大規模カスタマーサポートの最適化:** カスタマーサポートエージェントでは、以下の要素が全ユーザーで共通です。 - システムインストラクション（対応ガイドライン、トーン、禁止事項） - ツール定義（ナレッジベース検索、チケット作成、エスカレーション） - Few-shotの例示 これらの静的なコンテキストは毎リクエストで数千トークンになることがあります。1日1万リクエストのサポートボットなら、Context Cachingにより膨大なトークン削減が見込めます。 **RAGパイプラインでの活用:** ツール定義にナレッジベースのスキーマや検索パラメータの説明が含まれる場合、これらをキャッシュすることで各クエリのコストを最適化できます。 **マルチテナントSaaS:** 同一のエージェント定義を複数テナントで共有する場合、テナント固有の情報のみが動的部分となり、共通のプロンプトとツール定義はキャッシュで共有されます。 ## 💡 ユースケース - 💰 コスト削減: 長いシステムプロンプトの繰り返し送信コストを削減 - 🚀 レイテンシ改善: キャッシュヒット時のプリフィル処理が高速化 - 👥 マルチユーザー最適化: 同じプロンプトを使う複数ユーザーでキャッシュを共有 - 🏢 マルチテナント: テナント共通部分のコンテキストを効率的にキャッシュ - 📚 大規模ツール定義: 多数のツールを持つエージェントのツール定義コストを最適化 ## ⚠️ 注意点 - Context Cachingはモデルプロバイダーのサポートに依存します。利用可能なモデルを事前に確認してください - キャッシュのTTL（有効期限）が短すぎるとヒット率が下がり、長すぎるとメモリを消費します。アクセスパターンに応じて調整してください - システムプロンプトやツール定義を頻繁に変更する場合、キャッシュの恩恵は限定的です - キャッシュのコスト自体も発生する場合があります。プロバイダーの料金体系を確認し、トータルコストで判断してください - 動的なコンテキスト（ユーザー固有の情報など）はキャッシュ対象外です。静的部分と動的部分を明確に分離して設計しましょう ✨ Context Cachingは「同じことを何度も言わない」をインフラレベルで実現します。マルチユーザー環境でのコスト最適化に大きな効果を発揮します！ #ADK# #AIAgent#

# ADKの便利で実践的な使い方 セッションを超えた「長期記憶」を実現するMemory機能。過去の会話から学び、ユーザーを深く理解するエージェントを作りましょう🧠 📌 **タイトル**: Memory 🔗 **URL**: ## 🧩 概要 Memoryは、セッションを横断して検索可能な長期知識を管理する機能です。Stateが「今の会話」のデータを保持するのに対し、Memoryは「過去の会話から得た知識」を蓄積し、自然言語で検索できます。 主要なAPIは以下の2つです。 - `add_session_to_memory` / `add_events_to_memory`: セッションやイベントの内容をメモリに追加 - `search_memory`: 自然言語クエリでメモリを検索 バックエンドにはChromaなどのベクトルDBを使用でき、RAG（Retrieval-Augmented Generation）パターンでエージェントの応答品質を向上させます。 ## 🛠 使い方 `google.adk.memory` から `InMemoryMemoryService` をインポートしてインスタンス化します。セッション終了時に `await memory_service.add_session_to_memory(session)` でセッション内容をメモリに追加します。検索時は `await memory_service.search_memory(app_name=..., user_id=..., query="以前のネットワーク接続の問題")` のように自然言語クエリを渡します。返されたresultsの各 `memory` オブジェクトの `memory.content` から、過去の関連する会話内容を取得してエージェントの文脈に活用できます。 ## 🏗 実践的な使い方 **カスタマーサポートでの活用:** 1. ユーザーが「ネットワークがまた繋がらない」と問い合わせ 2. Memoryを「ネットワーク接続の問題」で検索 3. 「前回（3日前）も同じ問題で問い合わせがあり、ルーターの再起動で解決しました」という情報を取得 4. エージェントが「前回の問題は解決しましたか？同じ症状でしたらルーターの再起動をお試しください」と提案 過去の対応履歴を踏まえた、パーソナライズされたサポートが実現します。 **学習支援エージェント:** 1. 「微分がわからない」とユーザーが相談 2. Memoryを検索し、「このユーザーは視覚的な説明を好む」「前回は具体例から理解した」という知識を取得 3. グラフを使った具体例ベースの説明を提供 ## 💡 ユースケース - 🎧 カスタマーサポート: 過去の問い合わせ履歴を踏まえた対応。「前回の問題は解決しましたか？」 - 📚 学習支援: ユーザーの学習スタイルや理解度を記憶し、最適な教え方を選択 - 🏥 健康管理: 過去の相談履歴から傾向を把握し、継続的なアドバイスを提供 - 🛒 パーソナルショッパー: 購買履歴や好みを記憶し、的確な商品提案 ## ⚠️ 注意点 - メモリに個人情報を保存する場合、プライバシーポリシーとデータ保護規制への準拠が必要です - ベクトルDBの検索精度はエンベディングモデルの品質に依存します。適切なモデルを選択してください - メモリの量が増えると検索コストも増加します。定期的な整理やTTL（有効期限）の設定を検討しましょう - `InMemoryMemoryService` はプロセス再起動でデータが消えます。本番ではChromaなどの永続化バックエンドを使用してください ✨ Memory機能でエージェントに長期記憶を持たせれば、ユーザーとの関係が深まり、回を重ねるほど賢くなるエージェントが実現します！ #ADK# #AIAgent#

# ADKの便利で実践的な使い方 🔐 APIキー、Bearer Token、OAuth2、OpenID Connect、サービスアカウント — ADKのAuthentication機能は、あらゆる認証方式をツールにシームレスに統合します。 📌 タイトル：Authentication — ツールの認証統合 🔗 URL： 🧩 概要 ADKのAuthentication機能は、AuthSchemeとAuthCredentialの2つのコンポーネントで構成されます。APIKey、HTTP Bearer、OAuth2、OpenID Connect、SERVICE_ACCOUNTの各認証方式をサポートし、ツールの認証を統一的に管理できます。OAuth2ではブラウザフローにも対応し、`tool_context.state`を使ったトークンキャッシュや、トークン有効期限の管理も可能です。 🛠 使い方 各認証方式の設定例です。 `google.adk.auth` から `AuthScheme`、`AuthCredential`、`APIKeyAuth`、`HTTPBearerAuth`、`OAuth2Auth` をインポートします。APIキー認証では `APIKeyAuth(header_name="X-API-Key")` でスキームを作成し、`AuthCredential(api_key="sk-your-api-key")` でクレデンシャルを設定します。HTTP Bearer認証では `HTTPBearerAuth()` と `AuthCredential(token="your-bearer-token")` を使います。OAuth2認証（ブラウザフロー）では `OAuth2Auth(authorization_url="", token_url="", scopes=["read", "write"])` でスキームを定義し、`AuthCredential(client_id="your-client-id", client_secret="your-client-secret")` でクレデンシャルを渡します。 ツールでの認証の活用: ツール内での認証活用例として、`call_protected_api(endpoint: str, tool_context: ToolContext)` 関数を定義します。`tool_context.state.get("user:api_token")` でキャッシュ済みトークンを取得し、有効期限内であればそのまま使用します。期限切れの場合は `refresh_token(tool_context)` で新しいトークンを取得し、`tool_context.state["user:api_token"]` に保存してキャッシュします。取得したトークンを `Authorization: Bearer` ヘッダーに設定してAPIを呼び出します。 🏗 実践的な使い方 **トークンキャッシュ戦略**: `tool_context.state`の`user:`プレフィックスを使ってトークンをキャッシュすることで、同一ユーザーのセッション内でトークンの再取得を避けられます。有効期限の管理も忘れずに実装しましょう。 トークンキャッシュの実践例として `get_or_refresh_token(tool_context: ToolContext) -> str` を定義します。`tool_context.state.get("user:oauth_token")` からトークンデータを取得し、`expires_at` を確認して有効期限内（60秒のバッファ付き）であれば `access_token` をそのまま返します。期限切れの場合は `oauth_client.refresh(refresh_token=...)` で新しいトークンを取得し、`tool_context.state["user:oauth_token"]` に `access_token`、`refresh_token`、`expires_at` を含む辞書として保存します。 **サービスアカウント認証**: GCPサービス間の通信では、SERVICE_ACCOUNT認証を使うことで、ユーザーの介入なしにセキュアなAPI呼び出しが可能です。 **認証の多層化**: 同一エージェント内で複数の認証方式を使い分ける場合、ツールごとに異なる認証を設定できます。OpenAPIToolsetの`auth_scheme`/`auth_credential`と組み合わせると効果的です。 💡 ユースケース 🔑 APIキーによるサードパーティAPI認証 🌐 OAuth2によるユーザー代理でのAPI操作 🏗️ サービスアカウントによるGCPサービス間連携 🔄 トークンのキャッシュと自動リフレッシュ ⚠️ 注意点 - 認証情報（APIキー、シークレット）はコードにハードコードせず、環境変数やSecret Managerから取得してください。 - OAuth2のブラウザフローはサーバーサイドのバッチ処理では使えません。サービスアカウントやクライアントクレデンシャルフローを検討してください。 - トークンの有効期限管理を怠ると、期限切れトークンでのAPI呼び出しが401エラーになります。バッファを持った自動リフレッシュを実装しましょう。 ✨ ADKの認証機能を適切に設定すれば、セキュアなAPI連携をツール内にシームレスに組み込めます。認証はエージェントの信頼性の土台です！ #ADK# #AIAgent#

# ADKの便利で実践的な使い方 📜 OpenAPI/Swaggerの仕様書があれば、それだけでAPIをツール化できる — ADKのOpenAPI Toolsは、既存のREST APIを最小労力でエージェントに統合します。 📌 タイトル：OpenAPI Tools — OpenAPI仕様からの自動ツール生成 🔗 URL： 🧩 概要 ADKのOpenAPIToolsetは、OpenAPI（Swagger）仕様書からRestApiToolを自動生成します。各エンドポイントがそのままエージェントのツールになり、入力バリデーションも自動的に適用されます。`auth_scheme`と`auth_credential`を設定すれば、生成されたすべてのツールに認証が自動適用されるため、個別のツールごとに認証コードを書く必要がありません。 🛠 使い方 OpenAPI仕様からツールを自動生成する例です。 ` から `OpenAPIToolset` を、`google.adk.auth` から `APIKeyAuth` をインポートします。`OpenAPIToolset(spec_url="", auth_scheme=APIKeyAuth(header_name="X-API-Key"), auth_credential="your-api-key-here")` のように、OpenAPI仕様のURLと認証設定を渡してツールセットを作成します。認証は全ツールに自動適用されます。作成した `toolset` を `Agent` の `tools` リストに渡すだけで、各エンドポイントがエージェントのツールとして利用可能になります。 ローカルのOpenAPI仕様ファイルを使う場合: ローカルのOpenAPI仕様ファイルを使う場合は、` でYAMLファイルを読み込み、`OpenAPIToolset(spec_dict=spec, base_url="")` のように `spec_dict` パラメータに辞書として渡し、`base_url` でAPIのベースURLを指定します。 🏗 実践的な使い方 **既存APIの即座の統合**: 社内のマイクロサービスがOpenAPI仕様を公開していれば、コードを書くことなくエージェントのツールとして利用できます。API仕様の`description`フィールドがツールの説明として使われるため、仕様書の品質がそのままエージェントの精度に影響します。 複数のAPIを統合するには、ユーザーサービス用の `OpenAPIToolset(spec_url="https://user-service.internal/openapi.json", auth_scheme=APIKeyAuth(header_name="Authorization"), auth_credential="Bearer token123")` と注文サービス用の `OpenAPIToolset` をそれぞれ作成し、`Agent` の `tools` リストに `tools=[user_api, order_api]` として両方を渡します。各ツールセットに異なる認証情報を設定できるため、サービスごとのアクセス制御が可能です。 **入力バリデーションの活用**: OpenAPI仕様のスキーマ定義（required、type、enum等）に基づいて入力が自動バリデーションされるため、不正なAPI呼び出しを防げます。 **段階的な統合**: まずは読み取り専用のGETエンドポイントだけをツール化し、動作を確認してからPOST/PUT/DELETEを追加する段階的なアプローチが安全です。 💡 ユースケース 🏢 社内マイクロサービスのエージェント統合 🛒 ECサイトのAPI（商品検索、注文管理）のツール化 📊 データ分析APIの統合による自然言語クエリ 🔗 サードパーティSaaS APIの統合 ⚠️ 注意点 - OpenAPI仕様の`description`が不十分だと、LLMが適切なツールを選択できません。仕様書の品質を事前に確認してください。 - 認証情報（`auth_credential`）はハードコードせず、環境変数やSecret Managerから取得してください。 - エンドポイントが多すぎると、LLMのツール選択が不正確になります。必要なエンドポイントに絞ってToolsetを構成しましょう。 ✨ OpenAPI Toolsを使えば、API仕様書がそのままエージェントの能力になります。既存のAPIドキュメントを最大限に活かしましょう！ #ADK# #AIAgent#

🤔 「AIエージェントを作るのは難しくない。でも、本番で動かし続けるのは別の話だ。」──エージェント開発者なら、誰もがこの壁に当たったはずです。 Why Managed Agents Are the Next Big Thing in Agent Building 2022年末にLangChainが登場してから、エージェント開発は急速に進化してきました。初期のAutoGPTの熱狂から、LangGraphやGoogle ADKによる精緻なフレームワークの時代へ。そして2025年に入ると、モデルの能力が臨界点を超え、「ツールを呼び出しながら自律的にループするLLM」という基本形が現実のものとなりました。Claude Code、Deep Agentsといった専用ハーネスの登場は、その完成形への一歩でした。 🌊 しかし、ここで大きな問題が浮かび上がります。エージェントを本番環境で"動かし続ける"ためには、LLMの賢さだけでは足りないのです。信頼性のある実行環境をどう構築するか。失敗したエージェントをどう再開させるか。コードをどう安全に実行させるか。ユーザーへのUXをどう設計するか──開発者はモデルとは全く別の、インフラの泥沼と格闘してきました。 LangChainの創業者 Harrison Chase はこの1年間の学びを結晶化し、「マネージドエージェント」というコンセプトを提唱します。本番エージェントに必要なのは、ビジネスロジック・ハーネス・インフラの3層だと整理し、そのうちインフラ層をまるごと引き受けるのがManaged Deep Agentsです。ランタイム管理、イベントストリーミング、サンドボックス、メモリ、認証、評価ツール──かつては自前で構築するしかなかったすべてが、プラットフォームとして提供されます。Anthropicの「Claude Managed Agents」やVercelの「Eve」も同様の方向へ向かっており、エコシステム全体がインフラの民主化という潮流に入りつつあります。 エージェント開発者がビジネスロジックだけに集中できる時代が、ようやく到来しようとしています。 #AIエージェント# #LangChain#

# ADKの便利で実践的な使い方 ⚡ Python関数をそのままツールに、エージェントもツールに、そして長時間タスクもノンブロッキングで実行 — ADKのFunction Toolsは、ツール定義の柔軟性を極限まで高めます。 📌 タイトル：Function Tools — 関数・エージェント・非同期タスクをツール化 🔗 URL： 🧩 概要 ADKのFunction Toolsでは、Python/TypeScriptの関数をそのままエージェントのツールとして利用できます。さらに、AgentToolを使えばエージェント自体をツールとして別のエージェントに提供できます。Long Running Function Toolsは、動画エンコードやバッチ処理のような長時間タスクをブロッキングせずに実行するための仕組みです。 🛠 使い方 基本的な関数ツールの定義とAgentToolの活用例です。 `google.adk`から`Agent`と`AgentTool`をインポートします。シンプルな関数ツールとして`calculate_price`を定義し、`base_price`（float）、`quantity`（int）、`discount_percent`（float、デフォルト0）を受け取り、合計金額を計算してdictで返します。 エージェントのツール化には`AgentTool`を使います。まず`analysis_agent`を`name="data_analyst"`、`tools=[query_database]`で定義し、次に`main_agent`の`tools`リストに`calculate_price`関数と`AgentTool(agent=analysis_agent)`を含めます。これにより、メインエージェントは価格計算関数とデータ分析エージェントの両方をツールとして呼び出せます。 Long Running Function Toolsの使い方です。 `google.adk`から`LongRunningFunctionTool`をインポートします。非同期関数`encode_video`は`video_url`（str）と`format`（str、デフォルト"mp4"）を受け取り、`start_encoding_job`でエンコードジョブを開始してジョブIDを返します。この関数を`LongRunningFunctionTool(func=encode_video)`でラップして`video_tool`を作成し、`Agent`の`tools=[video_tool]`に渡すことで、エージェントがブロッキングなしで長時間処理を実行できます。 🏗 実践的な使い方 **AgentToolによるモジュール化**: 複雑な処理を専門エージェントとしてカプセル化し、AgentToolで公開することで、メインエージェントのinstructionをシンプルに保てます。専門エージェントは独自のツールやプロンプトを持てるため、関心の分離が実現します。 `summarizer`（3行要約）と`translator`（英語翻訳）をそれぞれ`Agent`で定義し、メインの`content_manager`エージェントの`tools`リストに`AgentTool(agent=summarizer)`と`AgentTool(agent=translator)`として登録します。これにより、メインエージェントは要約と翻訳の専門エージェントをツールとして呼び出し、コンテンツ管理の依頼を処理できます。 **Long Running Toolsの活用場面**: バッチ処理、外部APIのポーリング待ち、ファイル変換など、完了まで数秒〜数分かかる処理に最適です。エージェントはジョブIDを受け取り、他のタスクを並行して進められます。 **型アノテーションの重要性**: 関数のパラメータ型と戻り値型を明確に定義することで、LLMが正確にツールを呼び出せます。docstringもツールの説明として使われるため、簡潔で明確に書きましょう。 💡 ユースケース 🧮 計算・変換関数のツール化（価格計算、単位変換） 🤖 専門エージェントのAgentTool化による再利用 🎬 動画エンコード・画像処理の非同期実行 📊 バッチデータ処理のノンブロッキング実行 ⚠️ 注意点 - 関数のdocstringがツールの説明になるため、LLMが理解しやすい説明を書いてください。docstringがないとツールの用途が不明確になります。 - AgentToolで呼び出されたエージェントは、親エージェントのコンテキストとは別のセッションで動作します。状態の共有には注意が必要です。 - Long Running Function Toolsは完了通知の仕組みを別途実装する必要があります。ポーリングや Webhook での通知を検討してください。 ✨ Function Toolsを使えば、既存のコード資産をそのままエージェントに統合でき、AgentToolでエージェントの再利用も自在。開発効率を大幅に向上させましょう！ #ADK# #AIAgent#

# ADKの便利で実践的な使い方 🔧 標準ワークフローでは実現できない独自のオーケストレーションロジックが必要な場面、ありますよね。ADKのCustom Agentsなら、`BaseAgent`を継承して自由自在に制御フローを組み立てられます！ 📌 タイトル：Custom Agents — BaseAgent継承による自由な制御フロー設計 🔗 URL： 🧩 概要 Custom Agentsは、`google.adk.agents.BaseAgent`を継承し、`_run_async_impl`メソッドを実装することで、任意のオーケストレーションロジックを構築できる仕組みです。SequentialAgentやParallelAgentなどの定型パターンでは対応できない、条件分岐・ループ・外部状態同期といった高度なワークフローを実現します。サブエージェントの呼び出し、セッション状態の共有、イベントの伝播がフレームワーク標準で管理されます。 🛠 使い方 Custom Agentの基本構造は以下のとおりです。 `google.adk.agents.BaseAgent` を継承して `MyCustomAgent` クラスを定義します。フィールドとして `story_generator`、`critic_agent`、`tone_checker` の3つの `LlmAgent` を宣言します。`_run_async_impl` メソッド内で、まず `self.story_generator.run_async(ctx)` でストーリーを生成し、次に `self.critic_agent.run_async(ctx)` を `for i in range(2)` で最大2回ループして批評・修正を行います。最後に `self.tone_checker.run_async(ctx)` でトーンを確認し、`ctx.session.state.get("tone_result")` が `"negative"` の場合は `self.story_generator.run_async(ctx)` で再生成する条件分岐を行います。各サブエージェントの実行は `async for event in ... yield event` パターンでイベントを伝播します。 サブエージェント間のデータ共有には`ctx.session.state`を使います。 エージェントAが `ctx.session.state["analysis_result"] = result` で結果を書き込み、エージェントBが `ctx.session.state.get("analysis_result")` でそれを読み取ります。 🏗 実践的な使い方 **レガシーステートマシンの再現**: 既存の状態遷移ロジックをCustom Agentに移植できます。`_run_async_impl`内でPythonの標準的な制御構文（if/elif/while/try-except）を使い、状態ごとに異なるサブエージェントを呼び分けます。 `_run_async_impl` 内で `state = "INIT"` から開始し、`while state != "DONE"` でステートマシンを実装します。`"INIT"` 状態では `self.init_agent.run_async(ctx)` を実行し、`ctx.session.state.get("next_state", "PROCESS")` で次の状態を決定します。`"PROCESS"` 状態では `self.process_agent.run_async(ctx)` を実行後 `"REVIEW"` に遷移します。`"REVIEW"` 状態では ` を実行し、`ctx.session.state.get("approved")` が真なら `"DONE"` に、偽なら `"PROCESS"` に戻ります。 **外部状態との同期**: データベースやAPIから取得した状態に基づいて実行パスを動的に切り替えられます。例えば、外部システムのステータスを確認してから次のエージェントを選択するパターンが実現可能です。 💡 ユースケース 🔄 レガシーシステムの状態遷移ロジックをAIエージェントとして再実装 🔀 中間結果に基づく条件分岐ワークフロー（品質チェック → 不合格なら再生成） 🔗 外部API/DBの状態に応じたエージェント選択 🔁 批評・修正の反復ループ（最大N回で打ち切り） ⚠️ 注意点 - `sub_agents`リストには、`_run_async_impl`内で直接呼び出すすべてのサブエージェントを含める必要があります。含めないとフレームワークのライフサイクル管理が正しく動作しません。 - `ctx.session.state`は全サブエージェント間で共有されるため、キー名の衝突に注意してください。プレフィックスをつけるなどの規約を決めておくと安全です。 - 無限ループを防ぐため、ループ処理には必ず最大回数や終了条件を設けてください。 ✨ Custom Agentsは、定型パターンでは収まらない独自のビジネスロジックをエージェントに組み込むための最も柔軟な手段です。ステートマシンの移行や複雑な条件分岐が必要な場面で、ぜひ活用してみてください！ #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#

# ADKの便利で実践的な使い方 ## 🏢 アプリケーション単位で状態を分離！ADKのApps機能 複数のエージェントワークフローを管理するとき、状態やアーティファクトが混ざってしまう…ADKの **Apps** を使えば、`app_name` によるネームスペースでState/Artifact/Memoryを完全に分離できます！🏗️ ## 📌 タイトル Apps（アプリケーション） ## 🔗 URL ## 🧩 概要 App クラスは、ADKエージェントワークフローのトップレベルコンテナです。ルートエージェントを中心に、ライフサイクル管理、共有リソースの一元設定、状態スコープの定義を担います。 主な役割： - **一元設定**：APIキーやDBクライアントなどの共有リソースを一箇所で管理 - **ライフサイクル管理**：スタートアップ/シャットダウンフック - **状態スコープ**：`app:*` プレフィックスで明示的なデータ境界 - **デプロイ単位**：バージョニングとテストの正式な単位 さらに、Context Caching、Context Compaction、Resumability、Pluginsの設定もAppレベルで行えます。 ## 🛠 使い方 `google.adk.agents.llm_agent` から `Agent`、`google.adk.apps` から `App`、`google.adk.runners` から `InMemoryRunner` をインポートします。`Agent` を `model='gemini-flash-latest'`、`name='assistant'`、`description='汎用アシスタント'` で作成します。次に `App` を `name="my_app"` で作成し、`root_agent` を渡します。オプションで `plugins`、`context_cache_config`、`events_compaction_config`、`resumability_config` も指定可能です。最後に `InMemoryRunner(app=app)` でランナーを作成し、`await "こんにちは！")` で実行します。 ## 🏗 実践的な使い方 **マルチテナントSaaSでのデータ分離：** `app_name` をテナントごとに変えることで、State/Artifact/Memoryの完全な分離を実現できます。 `create_tenant_app(tenant_id: str, root_agent: Agent) -> App` 関数を定義し、テナントごとに独立した `App` を作成します。`name=f"saas_{tenant_id}"` でテナント固有のネームスペースを設定し、`plugins` に全テナント共通の `SecurityGuardPlugin()` とテナント別の `TenantLoggingPlugin(tenant_id)` を渡します。テナントAでは `create_tenant_app("tenant_a", support_agent)` で App を作成し `InMemoryRunner` で実行すると、State は `"app:saas_tenant_a:*"` に保存されテナントBからは見えません。テナントBも同様に `"app:saas_tenant_b:*"` に保存され、テナントAからは見えません。 **環境別の設定分離：** 開発環境では `App` を `name="myservice_dev"` で作成し、`plugins` に `DebugLoggingPlugin()` を、`events_compaction_config` に `EventsCompactionConfig(compaction_interval=10, overlap_size=3)` を設定します。本番環境では `name="myservice_prod"` で作成し、`plugins` に `SecurityGuardPlugin()`、`BigQueryAnalyticsPlugin()`、`RateLimitPlugin()` を設定し、`events_compaction_config` は `EventsCompactionConfig(compaction_interval=5, overlap_size=2)` とより頻繁なコンパクションを行います。 ## 💡 ユースケース - 🏢 **マルチテナントSaaS**：テナントごとにAppを分離し、データの混在を完全防止 - 🔧 **環境分離**：dev/staging/prodで異なるプラグインと設定を適用 - 📦 **マイクロサービス**：サービスごとに独立したAppとしてデプロイ・バージョニング - 🧪 **A/Bテスト**：同じエージェントを異なるApp設定で実行し、効果を比較 - 🔄 **ライフサイクル管理**：DB接続プールやキャッシュの初期化/クリーンアップを一元管理 ## ⚠️ 注意点 - `app_name` はState/Artifact/Memoryのネームスペースに使われるため、一意で変更しないようにしてください - App名を変更すると、過去のStateやArtifactにアクセスできなくなります - 複数のAppが同じルートエージェントを共有する場合、エージェントのステートレス性を確保してください - PluginsはAppレベルで設定するため、テナント共通とテナント固有のプラグインを適切に分離しましょう ## ✨ まとめ Appクラスは、ADKエージェントのデプロイと運用における「境界」を明確にする仕組みです。マルチテナント分離、環境別設定、ライフサイクル管理…Appを適切に設計することで、スケーラブルで安全なエージェントアプリケーションを構築できます！ #ADK# #AIAgent#