AIエージェントをエンタープライズシステムに組み込むプラクティス 【エージェント・ハブ / 体験トポロジー（Agent Hub）】 💡 ポイント 「"AIエージェントを導入したのに使われない"最大の理由は、ユーザーが存在を知らない・どれを使えばいいか分からないことです。」 どれだけ優秀なエージェントを作っても、ユーザーに届かなければ価値はゼロです。体験トポロジー（ハブ型と埋め込み型）の選択が、AI投資のROIを決定づけます。 🔥 解決する課題 - 「どのツール/エージェントを使えばいいか分からない」問題（発見性の欠如） - 複数システムにまたがる横断業務での画面遷移・コンテキストスイッチの負荷 - AI機能が散在し、利用率が上がらない問題 - 埋め込み型では既存アプリの権限モデルを再構築するコスト 🏗️ 提案パターン ハブ型は社内の単一AI窓口（Slackボットや専用Webポータル）として全業務にルーティングします。ユーザーが自然言語で依頼するだけで、意図分類によって適切なドメインエージェント（営業/IT/人事等）に委譲されます。埋め込み型（コパイロット）は既存システムのUI内（Salesforceのサイドパネル、Slack内ボット等）にエージェントを配置し、現画面のコンテキストを活用して高精度な提案を行います。実務では両方式を併用し、ハブを正面玄関として全社に提供しつつ、高滞在アプリには個別に埋め込み、同じオーケストレーション層を共有する構成が現実的です。 ✅ 選定条件 - ハブ型を採用する場合：横断業務が多い。ツールの発見性が課題。入口の一本化が価値をもたらす。 - 埋め込み型を採用する場合：作業が単一システム内で完結する。その画面に滞在時間が長い職種がいる。 - 実務では併用が最も効果的です。 ⚠️ 落とし穴 - ハブ型の意図分類精度が低いと、ユーザーが毎回たらい回しにされ、信頼を失います。曖昧な依頼には聞き返しを行い、意図を確定してから委譲する設計が重要です。 - 埋め込み型を「全アプリに一律導入」しようとすると、滞在時間が短いアプリでは投資対効果が合いません。高滞在アプリから優先的に導入してください。 - ハブと埋め込みでオーケストレーション層を別々に構築すると、二重投資と品質のばらつきが発生します。 🛠️ 実装方針 - ハブ型の入口として Slack Bolt / Microsoft Teams アプリを構築します。全社向けの単一AIボットとして展開し、ユーザーが自然言語で業務を依頼できるインターフェースを用意します。 - 意図分類エンジン（P16 スーパーバイザ/ルーター）を実装します。ユーザーの入力を解析し、適切なドメインエージェント（営業/IT/人事/開発等）に委譲する仕組みを構築します。曖昧な依頼には聞き返しを行う設計にします。 - 埋め込み型（コパイロット）を高滞在アプリから優先的に導入します。Salesforce LWC（Lightning Web Components）でサイドパネル型コパイロットを、Slack Bolt でチャネル内アシスタントを構築し、現画面のコンテキストをエージェントに渡す設計にします。 - トークン交換（P08 OAuth Token Exchange / OBO）を実装し、ハブ・埋め込みの両方でユーザー権限を各バックエンドシステムに伝播させます。社内IdPでSSO認証後、各SaaSへの操作はユーザー本人の権限で実行されるようにします。 - ハブと埋め込みで共通のオーケストレーション層を共有する構成にします。ドメインエージェントのロジックを一箇所に集約し、フロントエンド（Slack / Salesforce / Web等）の違いはアダプタ層で吸収します。 #AIエージェント# #エンタープライズアーキテクチャ#

🧩 「一度作れば、どのエージェントでも動く」——プラグインの相互運用に向けた業界横断の標準が登場しました。 タイトル: Agent Plugins — An open, vendor-neutral standard for portable agent plugins URL: 📦 概要 Agent Pluginsは、再利用可能なコンポーネントを「可搬なプラグイン」としてパッケージ化する、オープンかつベンダー中立な標準です（バージョン1.0.0）。プラグインの「フォルダ構造とマニフェスト」という最小限だけを共通化し、一度作れば複数のエージェントクライアントで動く状態を目指します。 ❓ 解決する課題 いまは各クライアントが、中身が同じでも独自のプラグイン形式を持っています。そのため作者は同じ部品をプラットフォームごとに作り直す必要がありました。Agent Pluginsは「クライアント間で可搬にできる部分」だけに絞った小さな相互運用の土台を用意し、この重複作業を解消します。 🗂 方法論（パッケージ構造） プラグインは決められたディレクトリ構造を持ちます。 ・plugin.json：プラグインの識別情報と、対象とするAgent Pluginsのバージョン（現在1.0.0）を指定 ・skills/：Agent Skills仕様に沿ったスキル群。各スキルはSKILL.md（説明）、scripts/（実行スクリプト）、references/（参照資料）で構成 ・mcp.json：MCP（Model Context Protocol）サーバを記述。stdio／Streamable HTTP／旧来のHTTP+SSEという3つのトランスポートに対応 ・逆ドメイン名前空間（例 com.example.client/）：可搬なコアを変更せずに、hooksなどクライアント独自の振る舞いを追加できる拡張の置き場所 🔧 標準化する範囲・しない範囲 標準化するのはマニフェスト、ディレクトリ構造、コンポーネントの配置場所まで。配布・インストール・権限・UX・クライアント固有機能は、あえて各クライアントの裁量に残します。共通化すべき「部品の可搬性」と、各社が差別化したい体験を切り分けたのが設計思想です。 🏛 ガバナンスと位置づけ 技術運営委員会はAmazon・Cursor・Microsoft・OpenAI・Vercelのコアメンテナで構成。提案や技術決定はGitHub Discussionsで公開され、エコシステムに開かれています。MCPやAgent Skillsといった既存仕様の上に重ねる形で、相互運用の一段を担います。 #AIエージェント# #MCP#

# ADK 2.0の便利だけど知られていない機能 🌍 AIエージェントのワークフローを「グラフ」として設計できたら、複雑な処理フローも見通しよく管理できると思いませんか？ ADK 2.0のWorkflowクラスは、ノードとエッジでエージェントの実行パスを定義するグラフベースのワークフロー構築機能です。AIエージェント、カスタム関数、ツール、さらにはネストされたWorkflowをノードとして組み合わせ、明示的なルーティングロジックで制御できます。 📌 タイトル：Workflow クラスによるグラフベース実行 🔗 URL： 🧩 概要 Workflowクラスは、ADK 2.0におけるグラフベースのエージェントワークフローを構築するための主要な構成要素です。ノードには、AIエージェント・コード関数・ツール・ネストされたWorkflowを配置でき、エッジ（edges）パラメータで実行パスを定義します。逐次実行は `("START", node1, node2, node3)` のようにタプルで記述し、条件分岐は辞書で定義します。これにより、従来のプロンプトベースの制御では難しかった複雑な分岐構造を、明示的かつ信頼性高く実装できます。 🛠 使い方 Workflowクラスのインスタンスを作成し、nodesにノードのリスト、edgesに実行パスを指定します。 ```python from adk import Workflow, Agent agent_a = Agent(name="researcher", ...) agent_b = Agent(name="writer", ...) workflow = Workflow( name="content_pipeline", nodes=[agent_a, agent_b], edges=[("START", agent_a, agent_b)] ) ``` 逐次実行の場合はタプルでノードを列挙し、条件分岐が必要な場合は辞書ベースのルーティングを使います。ネストされたWorkflowをノードとして組み込むことで、大規模なパイプラインも階層的に管理できます。 🏗 本番システムへの組み込み方 ・各ノードの責務を明確に分離し、テスト可能な単位で設計する ・エラーハンドリングを各ノードレベルで実装し、障害の影響範囲を限定する ・ネストされたWorkflowを活用して、再利用可能なサブパイプラインを構築する ・条件分岐のルーティングロジックをドキュメント化し、チームでの保守性を確保する 💡 ユースケース 📄 論文の収集→要約→レビュー→投稿を一連のグラフとして管理 🔀 入力データの種類に応じて異なる処理パイプラインに分岐 🏢 複数部門のエージェントを組み合わせた承認フローの構築 🔁 サブワークフローを再利用した複数プロジェクト横断の自動化 ⚠️ 注意点 WorkflowクラスはLive Streamingとの互換性がなく、一部のサードパーティ統合にも対応していません。リアルタイムのストリーミング応答が必要なケースでは、別のアプローチを検討する必要があります。また、グラフの複雑さが増すとデバッグが難しくなるため、適切な粒度でノードを分割することが重要です。 ✨ 明示的なグラフ定義により、エージェントワークフローの信頼性と保守性が大きく向上します。複雑な処理フローを構築する際にはぜひ活用してみてください。 #ADK# #AIAgent#

🔬 「50人のチームが手元にいて、1日で全部やってくれる感覚」。Geminiベースのマルチエージェントが科学仮説を生成・討論・進化させ、肝線維症の瘢痕応答を91%ブロックする薬剤候補まで導きました。 タイトル: Co-Scientist: A multi-agent AI partner to accelerate research URL: 📝 概要 Co-Scientistは、Geminiを基盤とする協調型のマルチエージェントAIで、新規の科学仮説を生成・批評・洗練します。仮説の生成と評価のサイクルを自動化することで、ブレイクスルーの発見を加速する「AI研究パートナー」として機能します。 ❓ 解決する課題 研究者は、情報過多とますます複雑化する課題の中で、ブレイクスルーとなる仮説を立てるのに苦労します。膨大な文献にまたがる断片的な事実を結びつけ、有望な研究方向を特定するのが難しいのです。 💡 方法論と提案手法 3つのフェーズに専門エージェントを配置します。 ・生成フェーズ：Generationエージェントが文献とデータに基づき新規仮説を提案し、Proximityエージェントが仮説をクラスタ化して多様な探索を確保します ・討論フェーズ：Reflectionエージェントが「仮想ピアレビュア」として批判的に評価し、Rankingエージェントがペアワイズ比較とEloベースのトーナメントで優先順位付けします ・進化フェーズ：Evolutionエージェントが上位仮説を継続的に洗練・結合し、Meta-reviewエージェントが最終的な研究提案を統合します ・計算資源の大半を「検証」に充て、主張をChEMBLやUniProt、Web検索、AlphaFoldなどの専門ツールと突き合わせます 🎯 ユースケース 抗菌薬耐性、植物免疫、肝線維症の治療発見、ALSの機序探索、細胞老化の逆転、感染症タンパク質の特定、代謝疾患、老化生物学など、幅広い生命科学領域に応用されています。 📊 実験結果 ・肝線維症で、瘢痕に関連する応答の91%をブロックする薬剤候補を特定しました ・細胞老化では、実験室で細胞を若返らせる遺伝的リードを生成し、スクリーニング解析を数ヶ月から数日に短縮しました ・100以上の研究機関がテストし、Stanford、MIT、Cambridge、Calicoなどが協力しています ・第一三共やBayer Crop Science、米国の国立研究所にエンタープライズ版が展開されています #AIforScience# #AIエージェント#

# ADKの便利で実践的な使い方 🔌 GitHub、Linear、Chroma、n8n — 既存のMCPサーバーをADKエージェントにそのまま統合できるMCP Toolsは、ツールエコシステムへの最速の接続手段です。 📌 タイトル：MCP Tools — MCPサーバーとの統合 🔗 URL： 🧩 概要 ADKのMcpToolsetは、Model Context Protocol（MCP）サーバーのツールを自動検出し、ADKエージェントのツールとして利用可能にします。Stdio、SSE、Streamable HTTPの3つのトランスポートに対応し、GitHub MCP、Linear MCP、Chroma MCP、n8n MCPなど、既存のMCPサーバーエコシステムをそのまま活用できます。GKEではサイドカーパターンでのデプロイも可能です。 🛠 使い方 各トランスポートでのMcpToolsetの設定例です。 Stdioトランスポートでは、` から `McpToolset` と `StdioServerParameters` をインポートし、`McpToolset(connection=StdioServerParameters(command="npx", args=["-y", "@modelcontextprotocol/server-github"], env={"GITHUB_TOKEN": "ghp_..."}))` のようにローカルプロセスとしてMCPサーバーを起動します。作成した `McpToolset` インスタンスを `Agent` の `tools` リストに渡すだけで、GitHub MCPサーバーのツールがエージェントから利用可能になります。 SSEトランスポートでは、`SseServerParams` を使い、`McpToolset(connection=SseServerParams(url="http://localhost:3001/sse"))` のようにリモートサーバーのSSEエンドポイントに接続します。 Streamable HTTPトランスポートでは、`StreamableHTTPServerParams` を使い、`McpToolset(connection=StreamableHTTPServerParams(url="http://localhost:3001/mcp"))` のように最新のHTTPベースで接続します。 🏗 実践的な使い方 **MCPサーバーの選択と組み合わせ**: プロジェクト管理にはLinear MCP、コード管理にはGitHub MCP、ベクトル検索にはChroma MCP、ワークフロー自動化にはn8n MCPを組み合わせることで、強力な開発支援エージェントを構築できます。 複数のMCPサーバーを組み合わせるには、GitHub用の `McpToolset` を `StdioServerParameters(command="npx", args=["-y", "@modelcontextprotocol/server-github"])` で、ベクトルDB検索用の `McpToolset` を `StdioServerParameters(command="uvx", args=["chroma-mcp"])` でそれぞれ作成し、両方を `Agent` の `tools` リストに `tools=[github_tools, chroma_tools]` として渡します。これにより、1つのエージェントからGitHub操作とChromaベクトル検索の両方が利用可能になります。 **GKEサイドカーパターン**: Kubernetes環境では、MCPサーバーをサイドカーコンテナとしてPodに配置し、localhostでStdio/SSE接続することで、ネットワーク遅延を最小化しつつセキュアな通信を実現できます。 **ツールの自動検出**: McpToolsetはMCPサーバーが公開するツールを自動検出するため、サーバー側でツールが追加された場合、ADK側のコード変更なしに新しいツールが利用可能になります。 💡 ユースケース 🐙 GitHub MCPでIssue/PR管理を自動化 📋 Linear MCPでプロジェクトタスクの追跡と更新 🔍 Chroma MCPでRAGベースの知識検索 🔄 n8n MCPでワークフロー自動化との連携 ⚠️ 注意点 - MCPサーバーのプロセス管理に注意してください。Stdioの場合、エージェント終了時にMCPプロセスも適切にクリーンアップする必要があります。 - MCPサーバーが公開するすべてのツールがエージェントに見えるため、不要なツールが多いとLLMの判断が複雑になります。 - 外部MCPサーバーのセキュリティ（認証トークンの管理、通信の暗号化）には十分注意してください。 ✨ MCP Toolsを使えば、豊富なMCPエコシステムのツールをADKエージェントにワンステップで統合できます。車輪の再発明をせず、既存のツールを最大限活用しましょう！ #ADK# #AIAgent#

# Cursorの機能と実践的な使い方 🧩 「あの作業、毎回同じ手順なのにAIに毎回説明している」を卒業しませんか。CursorのSkillsは、定型ワークフローを部品化してエージェントに覚えさせる仕組みです。 🏷️ タイトル: 再利用ワークフロー(SKILL.md) 🔗 URL: 📘 概要 Skillsは、特定ドメインのタスクの手順をエージェントに教える、ポータブルでバージョン管理可能なパッケージです。スクリプト・テンプレート・参照資料をまとめ、エージェントがツール経由で実行します。Rulesの進化形にあたり、文脈に応じて自動適用したり、スラッシュコマンドとして明示的に呼び出したりできます。 ⚙️ 機能の説明 各スキルは `SKILL.md` を中心に構成され、先頭のYAMLフロントマターで挙動を定義します。 ・`name`: 親フォルダ名と一致する小文字の識別子(必須) ・`description`: 何のためのスキルかと適用場面。エージェントがこの説明を読んで使うか判断します(必須) ・`paths`: glob パターンで対象ファイル種別にスコープを限定(任意) ・`disable-model-invocation`: `true` にすると自動適用されず `/skill-name` でのみ呼び出されるスラッシュ専用に(任意) 配置場所は階層的で、プロジェクトは `.cursor/skills/`(または `.agents/skills/`)、ユーザー全体は `~/.cursor/skills/` です。ルートは再帰的に走査され、ネストしたサブディレクトリも発見されます。スキルフォルダには `scripts/`(実行コード)、`references/`(必要時に読む資料)、`assets/`(テンプレや画像)を同梱できます。 🛠️ 実践的な使い方 たとえば `.cursor/skills/api-endpoint/SKILL.md` のフロントマターに `name: api-endpoint`、適用場面を書いた `description`、対象を絞る `paths: "src/api/**/*.ts"` を置き、本文に「ルートを registry に登録」「入力は zod で検証」「テストを必ず追加」といった手順を箇条書きします。 自動適用させたくない場合は `disable-model-invocation: true` を足し、Agentチャットで `/api-endpoint` と打って明示的に呼び出します。 💡 ユースケース モノレポでは各アプリ配下に `.cursor/skills/` を置くと、そのディレクトリ内のファイルへ自動的にスコープされ、`paths` を書かずに済みます。リリース手順・移行スクリプト・コードレビュー観点などを共有し、チーム全員が同じワークフローで作業できます。既存資産は Cursor 2.4 同梱の `/migrate-to-skills` で変換でき、「Apply Intelligently」(`alwaysApply: false`)なルールはスキルへ、スラッシュコマンドは `disable-model-invocation: true` 付きスキルへ自動移行されます。 ⚠️ 注意点 スキルの識別名は `SKILL.md` を含むフォルダ名から決まり、親カテゴリ名ではありません。旧来の `globs` フィールドは非推奨で、今は `paths` を使います。`/migrate-to-skills` は `alwaysApply: true` のルールやユーザーレベルのルールは移行しないため、これらは手動対応が必要です。 #Cursor# #AIコーディング#

# OpenCodeの機能と実践的な使い方 🤖 1つのAIに何でも任せる時代は終わり。OpenCodeのエージェント機能なら、計画役・調査役・レビュー役を役割ごとに分け、権限まで細かく絞って安全に協働させられます。 🏷️ タイトル: プライマリ/サブエージェント 🔗 URL: 📘 概要 OpenCodeのエージェントは、直接対話する「プライマリエージェント」と、それらから呼び出される専門の「サブエージェント」に分かれます。役割とツール権限を分離することで、安全かつ効率的にタスクを進められます。 ⚙️ 機能の説明 ・プライマリ: 全ツールにアクセスできる開発用の Build と、編集・bashが既定で「ask」に制限された計画用の Plan があります。`Tab` で切り替えます。 ・サブエージェント: 多段の調査向けの General、読み取り専用でコードベースを探索する Explore、外部ドキュメントや依存関係を調べる Scout が組み込みです。`@/general ...` のように `@` で明示的に呼び出せるほか、プライマリが自動で起動することもあります。 ・カスタム定義: `opencode.json` のJSON、または `.opencode/agents/*.md` のMarkdown（フロントマター）で独自エージェントを定義できます。主な項目は `description`（必須）、`mode`（`primary`/`subagent`/`all`）、`model`、`prompt`、`temperature`、`permission`（`allow`/`deny`/`ask`）、`steps`、`hidden` などです。 🛠️ 実践的な使い方 編集を禁止した「監査専用エージェント」を定義すれば、誤った変更を防ぎつつレビューだけ任せられます。Markdown定義のフロントマターで `mode: subagent`、`permission` の `edit: deny` と `bash: deny` を指定し、本文に「入力検証・認証不備・データ露出・脆弱な依存関係を中心にレビュー」と書くだけです。`permission` の `bash` はグロブで細かく制御できます。 `opencode agent create` を使えば、対話形式で配置場所・目的・権限を選びながらMarkdown定義を生成できます。 💡 ユースケース 大きな機能追加では、まず Explore で関連箇所を読み取り専用で調査させ、Plan で方針を固め、Build で実装し、最後に編集禁止のレビュー用エージェントで点検する、という分業が組めます。 ⚠️ 注意点 ・`permission` の既定はエージェントごとに異なります（Planは編集/bashが ask）。意図せぬ変更を避けるため明示設定が安全です。 ・`bash` 権限はグロブ指定可能で、`"rm *": "deny"` のように危険コマンドを個別に拒否できます。 ・サブエージェントを `@` メニューから隠したい場合は `hidden` を使います。 #OpenCode# #AIAgents#

# Cursorの機能と実践的な使い方 📏 「APIは必ずzodで検証」——その方針、毎回プロンプトに書く必要はありません。CursorのRulesがAIに永続的な記憶を与えます。 🏷️ タイトル: 永続指示(Project/Team/AGENTS.md) 🔗 URL: 📘 概要 RulesはCursorのエージェントへ、システムレベルの永続的な指示を与える仕組みです。LLMは補完間で記憶を保持しないため、Rulesがプロンプトレベルで再利用可能な文脈を供給します。プロンプト・スクリプト・ガイダンスを束ね、チーム横断で再利用できます。 ⚙️ 機能の説明 Cursorは複数の種類のRulesをサポートします。 ・Project Rules: `.cursor/rules`配下の`.mdc`ファイル。バージョン管理され、コードベースにスコープされます。 ・User Rules: Cursor設定で定義する全プロジェクト共通の好み。 ・Team Rules: ダッシュボードで管理する組織全体のルール(Team/Enterpriseプラン)。 ・AGENTS.md: プロジェクトルートやサブディレクトリに置くプレーンなMarkalternative。フロントマター不要で、ネスト配置も可能(より具体的な指示が親より優先)。 Project Rulesのフロントマターは挙動を制御します。`alwaysApply: true`で全チャットに適用、`globs`指定+`alwaysApply: false`でマッチ時に自動添付、`description`のみならエージェントが関連時に賢く適用、いずれも無ければ`@`メンション時のみ適用されます。 🛠️ 実践的な使い方 ・globsでファイル種別にスコープします。例:`src/**/*.tsx`、複数指定はカンマ区切り。これで「APIは必ずzodで検証する」を該当ファイル編集時に自動適用できます。 ・ルール生成はチャットで`/create-rule`、または`Cursor Settings > Rules, Commands`の「+ Add Rule」から行います。 ・`.mdc`の例として、フロントマターに `globs: src/api/**/*.ts` と `alwaysApply: false` を書き、本文に「受信ペイロードは必ず zod スキーマで検証」「検証失敗時は 400 と統一エラー形を返す」といった規約を記します。 ・チームでは適用順「Team Rules → Project Rules → User Rules」を踏まえ、Team Rulesで全社的な規約を強制します。 💡 ユースケース 「APIはzod検証」「コミットはConventional Commits」「ログはJSON構造化」といった反復方針をRules化し、globsで該当ファイルだけに自動適用。Gitにチェックインすればチーム全員が同じ規約の恩恵を受けられます。 ⚠️ 注意点 ルールは1ファイル500行以内に保ち、大きければ分割します。スタイルガイドの丸写しは避け(リンターに任せる)、内容の重複より「ファイル参照」を優先します。まれなエッジケースより頻出パターンを狙いましょう。User RulesはAgent(チャット)にのみ効き、Inline Editやその他のAI機能、Cursor Tabには影響しない点に注意してください。 #Cursor# #AIコーディング#

# ADKの便利で実践的な使い方 ## 🎨 実戦で使えるコールバックパターン集！ADKのCallback Design Patterns コールバックの基本は分かった、でも実際どう使うの？ADKの **Callback Design Patterns** で、ログ・キャッシュ・セキュリティなど実戦パターンをマスターしましょう！💪 ## 📌 タイトル Callback Patterns（コールバックデザインパターン） ## 🔗 URL ## 🧩 概要 ADKのコールバックには、実戦で繰り返し使われる定番パターンがあります。ロギング、キャッシュ、ステート管理、セキュリティガードレール、リクエスト/レスポンス変換、条件付きスキップ、アーティファクト処理などです。 さらに、これらのパターンを効果的に使うためのベストプラクティス（単一責任、パフォーマンス、冪等性、エラーハンドリング）も定義されています。 重要な判断基準として、**エージェント横断のセキュリティガードレールにはCallbacksよりもPluginsが推奨**されています。 ## 🛠 使い方 **パターン1: ロギング＆モニタリング** `logging_before_tool(ctx, tool, args)` では `ctx.invocation_id`、` を ` で記録し、`None` を返してフローを変更しません。`logging_after_model(ctx, response)` では ` の長さを ` で記録し、同様に `None` を返して観察のみ行います。 **パターン2: キャッシュ戦略** `cache_before_tool(ctx, tool, args)` では、` と `hash(str(args))` からキャッシュキーを生成し、`ctx.state.get(cache_key)` でキャッシュを検索します。キャッシュヒットすればその値を返してツール実行をスキップし、ミスなら `None` を返して通常実行します。`cache_after_tool(ctx, tool, args, tool_ctx, result)` では、同じキャッシュキーで `ctx.state[cache_key] = result` として結果を保存し、`None` を返してフローを変更しません。 **パターン3: ステート管理** `state_aware_callback(ctx, req)` では、`ctx.state.get("user:tier", "free")` でユーザーティアを取得し、`"premium"` であれば `req.config.system_instruction` にプレミアム向けの追加指示を動的に付加します。`None` を返してフローはそのまま続行します。 ## 🏗 実践的な使い方 **本番環境での多層防御パターン：** セキュリティガードレール（本番ではPluginsを推奨）として `security_before_model(ctx, req)` を定義します。`req.contents[-1].parts[0].text` からユーザー入力を取得し、`detect_pii()` でPIIを検出した場合は `audit_log()` で監査記録を残し、拒否メッセージ入りの `LlmResponse` を返してLLM呼び出しをスキップします。続いて `detect_injection()` でプロンプトインジェクションを検出した場合も同様にブロックします。いずれにも該当しなければ `None` を返して続行します。ツール引数のサニタイズとして `sanitize_before_tool(ctx, tool, args)` を定義し、` が `"database_query"` の場合に `args.get("query", "")` に `"DROP"` が含まれていればエラー辞書を返してツール実行をブロックします。アーティファクト保存として `save_artifact_after_agent(ctx)` を定義し、`generate_report(ctx)` でレポートを生成して `"execution_report.json", report)` で保存し、`None` を返します。 ## 💡 ユースケース - 📊 **構造化ロギング**：全実行ポイントで invocation_id 付きの構造化ログを出力 - 💾 **APIコスト削減**：before/after パターンでツール結果をキャッシュし、同じ引数の再呼び出しを防止 - 🔐 **多層セキュリティ**：PII検出、インジェクション防止、SQLサニタイズを各レイヤーに配置 - 📦 **アーティファクト管理**：実行結果やレポートをアーティファクトとして自動保存 - 🎚️ **動的振る舞い制御**：ユーザーティアやステートに応じてインストラクションを動的変更 ## ⚠️ 注意点 - **単一責任の原則**：1つのコールバックに1つの目的を持たせてください（ロギングとバリデーションを混ぜない） - **パフォーマンス**：コールバックは同期実行されるため、ブロッキングI/Oや重い処理は避けましょう - **冪等性**：外部副作用を持つコールバックは、リトライ時に安全であるように設計してください - **エラーハンドリング**：必ず try-except で囲み、コールバックエラーがプロセス全体をクラッシュさせないようにしましょう - **Plugins推奨**：エージェント横断のセキュリティポリシーには、Callbacksよりも **Plugins** を検討してください ## ✨ まとめ コールバックパターンを知ることで、ADKエージェントの実践力が格段に上がります。ログ・キャッシュ・セキュリティ・ステート管理…定番パターンを組み合わせて、堅牢でコスト効率の良いエージェントを構築しましょう。ただし、横断的なセキュリティにはPluginsの利用もお忘れなく！ #ADK# #AIAgent#