2026年6月22日に Azure Cosmos DB Blog で公開された「How to Use Deep Agents with Azure Cosmos DB – Plan, act, and verify against operational data」は、Azure Portalに新しい設定項目が追加されたという話ではありません。ポイントは、Azure Cosmos DB にある運用データを Deep Agents が「計画し、実行し、結果を確認する」流れで扱うサンプル実装です。(Microsoft for Developers)
使い方で迷いやすいのは、「どこで有効化するのか」「Cosmos DB側に何を用意するのか」「AIエージェントにどこまで書き込みを許すのか」の3点です。結論から言うと、まずは本番データではなくサンプルデータで、読み取り専用の問い合わせから試すのが安全です。そのうえで、書き込みツール、権限、確認読み取り、履歴記録を明確にしてから業務データへ広げます。
How to Use Deep Agents with Azure Cosmos DB とは何か
「How to Use Deep Agents with Azure Cosmos DB – Plan, act, and verify against operational data」は、Azure Cosmos DB 上のサポートチケットを題材に、Deep Agents が複数ステップの調査や更新を行う方法を紹介した公式ブログ記事です。
Deep Agents は、1回のLLM呼び出しで答えを返すだけでなく、タスクを分解し、ツールを呼び出し、結果を見て次の行動を決めるタイプのエージェント向け仕組みです。ブログでは、LangGraph を土台にしたエージェントハーネスとして説明されています。(Microsoft for Developers)
サンプルの中心にあるのは「Support Ops Agent」です。これは、Azure Cosmos DB に保存されたサポートチケットのキューを読み取り、必要に応じてチケットの担当者・状態・タグ・履歴を更新し、最後に再読み取りして変更結果を確認する構成です。(Microsoft for Developers)
ここで重要なのは、Azure Cosmos DB を単なる検索先として使うのではなく、実際の運用データベースとして扱っている点です。公式ブログでは、チケットは Azure Cosmos DB のアイテムとして保存され、エージェントは Azure Cosmos DB SDK 経由で同じデータストアを読み書きすると説明されています。(Microsoft for Developers)
まず押さえるべき結論：新機能の有効化ではなく、エージェント設計のサンプル
この情報は Notice として扱われる内容であり、既存の Azure Cosmos DB 環境に対して「すぐ設定変更が必要」という性質のものではありません。管理者や開発者が見るべきポイントは、新しい設定スイッチではなく、Azure Cosmos DB を使ったエージェントアプリの設計パターンです。
特に次の3点を理解すると、使い方の迷いが大きく減ります。
| 迷いやすい点 | 実際に見るべきポイント |
|---|---|
| Azure Portalのどこで有効化するのか | Deep Agents専用のPortal設定ではなく、Cosmos DB、Azure OpenAI、認証情報、サンプルコードを組み合わせる |
| Cosmos DBに何を準備するのか | NoSQLコンテナー、パーティションキー、チケットのような運用データ、読み書き権限を用意する |
| AIに書き込みを任せてよいのか | 読み取りツールと書き込みツールを分離し、書き込み後に再読み取りで検証する |
つまり、「Deep AgentsをCosmos DBでオンにする」のではなく、「Cosmos DBを操作する安全なツール群をエージェントに渡す」と考えるのが近いです。
どんな用途に向いているか
Deep Agents with Azure Cosmos DB が向いているのは、単純なQ&Aではなく、運用データを見ながら判断が変わる業務です。公式サンプルでは、サポートチケットのトリアージ、チケット解決、インシデント検出、キューの健全性確認、担当者不在時の割り振りなどが例として挙げられています。(Microsoft for Developers)
| 向いている用途 | 理由 |
|---|---|
| サポートチケットの優先順位付け | 優先度、状態、更新日時、担当者を組み合わせて判断できる |
| 障害・インシデントの兆候検出 | 類似チケットを複数条件で探し、まとまりとして判断できる |
| 注文・申請・問い合わせの状態確認 | 現在の業務データを読みながら次の対応を決められる |
| IoTデバイスや業務イベントの確認 | 顧客、拠点、デバイス単位などのパーティション設計と相性がよい |
| 担当者の負荷確認 | ステータス別、領域別、担当者別の件数確認に使える |
一方で、FAQを返すだけのチャットボットや、検索結果を要約するだけの用途では過剰です。Deep Agents の価値は、複数回の読み取り、判断、必要に応じた更新、更新後の検証までを一連の流れにできる点にあります。
設定場所で迷ったときに見るべきAzureリソース
このサンプルを試すときに見る場所は、主に Azure Cosmos DB、Azure OpenAI、Azure CLI、ローカルまたは開発環境の4つです。サンプルリポジトリのREADMEでは、前提条件として Python 3.11以上、Azure Cosmos DB アカウント、Azure OpenAI デプロイメント、Azure CLI が挙げられています。(GitHub)
| 項目 | 何を確認するか | 迷ったときの判断基準 |
|---|---|---|
| Azure Cosmos DB | アカウント、データベース、コンテナー、パーティションキー | サンプルはチケットを顧客IDで分ける考え方。自社データでも「よく一緒に読む単位」を考える |
| Azure OpenAI | エンドポイント、デプロイメント名 | サンプルのREADMEでは Azure OpenAI デプロイメント例として gpt-4o が挙げられている |
| 認証 | Azure CLI の az login、Entra ID権限 | キーをコードに埋め込まず、DefaultAzureCredentialで扱う構成を優先する |
| ローカル環境 | Python仮想環境、依存パッケージ、.env | まずサンプルを動かし、業務データへの接続は後にする |
特に初心者が混乱しやすいのは、「Cosmos DB側にDeep Agents用の特別なメニューがある」と思ってしまう点です。今回のサンプルでは、Cosmos DBを操作するツールをPythonコード側に用意し、エージェントがそのツールを呼び出します。
導入前に確認したい前提条件
サンプルを動かす前に、次の前提を満たしているか確認します。ここを曖昧にしたまま進めると、認証エラー、接続エラー、書き込み権限不足、想定外の課金につながりやすくなります。
| 確認項目 | 内容 |
|---|---|
| Python | READMEでは Python 3.11以上が前提 |
| Azure Cosmos DB | 既存または新規の Cosmos DB アカウントが必要 |
| Azure OpenAI | モデルのデプロイメントが必要 |
| Azure CLI | az login による認証に使用 |
| Cosmos DBの権限 | READMEでは Cosmos DB Built-in Data Contributor ロールが必要 |
| Azure OpenAIの権限 | READMEでは Cognitive Services OpenAI User ロールが必要 |
| 環境変数 | COSMOSDB_ENDPOINT、AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_DEPLOYMENT を設定する |
サンプルは DefaultAzureCredential を使うため、接続キーを直接コードに書く構成ではありません。READMEでは、Cosmos DB にはデータプレーンの読み書き用ロール、Azure OpenAI には利用者ロールが必要と説明されています。(GitHub)
権限を付与した直後は反映に時間がかかる場合があります。認証エラーが出たときは、コードを疑う前に、ログイン中のAzureアカウント、対象サブスクリプション、ロール割り当て、反映待ちを確認してください。
サンプルの基本的な流れ
公式ブログのサンプルは、GitHub上のリポジトリで公開されています。READMEでは、依存関係のインストール、Azureログイン、環境変数の設定、シードデータ投入、エージェント実行という流れが示されています。(GitHub)
基本の流れは次のとおりです。
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
az login
cp .env.example .env
python seed.py
python agent.pyWindows環境では、仮想環境の有効化コマンドが異なります。
.venv\Scripts\activate.env には、少なくとも Cosmos DB のエンドポイント、Azure OpenAI のエンドポイント、Azure OpenAI のデプロイメント名を設定します。READMEでは、seed.py によって supportdb/tickets が作成され、120件のデモチケットが投入されると説明されています。(GitHub)
最初に試すプロンプトは、書き込みを伴わないものが安全です。
python agent.py --query "I just got in, what should I look at first?"このような問い合わせでは、エージェントはチケットキューを読み取り、優先度や更新日時などから確認すべきチケットを整理します。サンプルでは、CLIがエージェントのツール呼び出しをストリーミング表示するため、どのような読み取りや集計が行われたか追いやすくなっています。(GitHub)
Plan、Act、Verifyをどう理解すればよいか
今回のキーワードは「Plan, act, and verify」です。これは、AIエージェントが業務データを扱うときの安全な流れとして理解すると分かりやすいです。
| 段階 | 何をするか | サポートチケットの例 |
|---|---|---|
| Plan | 依頼を分解し、必要な確認項目を決める | 「朝一番に何を見るべきか」を、期限切れ・高優先度・未担当の確認に分解する |
| Act | Cosmos DBに対して読み取り、集計、必要な更新を行う | チケット一覧を検索し、必要なら担当者やステータスを更新する |
| Verify | 書き込み後に再読み取りして、結果を確認する | 更新したチケットを読み直し、状態、担当者、タグ、履歴が反映されたか確認する |
公式ブログでは、チケットを解決する例として、エージェントが対象チケットをポイント読み取りし、関連チケットを確認し、更新を行い、最後に読み戻して変更が反映されたか確認する流れが説明されています。(Microsoft for Developers)
この「Verify」を省略しないことが重要です。AIエージェントが「更新しました」と言っても、実際には権限不足、競合、入力ミス、条件違いで更新できていない可能性があります。業務データを扱う場合は、書き込み後に必ず対象レコードを読み直し、結果を確認する設計にします。
Cosmos DBの操作はツールとして分ける
公式ブログでは、エージェントがデータベースへ直接何でもできるのではなく、クエリ、ポイント読み取り、集計、書き込みといった薄いラッパーのツールを通じて操作すると説明されています。エージェントに生のデータベース接続を渡さない点が重要です。(Microsoft for Developers)
主なツールの考え方は次のとおりです。
| ツール | 役割 | 設計上のポイント |
|---|---|---|
run_query | キュー全体を検索する読み取り用ツール | SELECT のみ許可し、書き込みは拒否する |
read_ticket | チケットIDと顧客IDが分かるときのポイント読み取り | パーティションキーを使い、余計なクエリを避ける |
update_ticket | チケットを更新する唯一の書き込み口 | 状態、担当者、履歴、更新日時を一貫して変更する |
aggregate_tickets | ステータス別、領域別、担当者別などを集計 | キュー全体の健全性確認に使う |
run_query は読み取り専用で、SELECT 以外は拒否する設計です。書き込みは update_ticket に分離されています。これにより、「調査だけの処理」と「データを変更する処理」を明確に分けられます。(Microsoft for Developers)
実務では、この分離が非常に大切です。読み取りツールに更新権限を混ぜると、プロンプトの解釈ミスや想定外のツール呼び出しでデータが変わるリスクが高まります。
パーティションキーで迷ったら「業務上よく一緒に読む単位」を考える
公式ブログのサンプルでは、各チケットが顧客IDでパーティション分割されます。顧客単位でチケットを読む場合は同じパーティション内で処理でき、キュー全体の調査やインシデント検出ではクロスパーティションクエリを使う構成です。(Microsoft for Developers)
パーティションキーで迷ったら、次のように考えると判断しやすくなります。
| 業務データ | パーティションキー候補 | 理由 |
|---|---|---|
| サポートチケット | customerId | 顧客単位で関連チケットをまとめて読むことが多い |
| 注文データ | customerId、tenantId、orderGroupId | 顧客・テナント単位で履歴確認しやすい |
| IoTデータ | deviceId、siteId | デバイス単位または拠点単位で時系列確認しやすい |
| 社内申請 | departmentId、tenantId | 部門・テナント単位の承認状況を見やすい |
「AIが全件検索するから何でもよい」と考えるのは危険です。エージェントが便利でも、Cosmos DBのRU消費やクエリ効率はデータモデルに左右されます。よく一緒に読むデータを同じパーティションに寄せ、全体調査が必要な処理は投影するフィールドを絞る設計にします。
RU消費とクエリ範囲で注意すること
公式ブログでは、ポイント読み取りは安価な経路として説明され、チケットIDと顧客IDが分かっている場合はパーティションキーを使った読み取りが選ばれます。一方、キュー全体の調査はクロスパーティション作業に応じてRUを消費するため、必要なフィールドだけを投影する設計になっています。(Microsoft for Developers)
実務で特に注意したいのは、エージェントに自由な自然言語問い合わせを許すと、広範囲なクエリが増えやすい点です。
避けたい例は次のようなものです。
SELECT * FROM c代わりに、必要なフィールドだけを取得します。
SELECT c.id, c.customerId, c.priority, c.status, c.area, c.assignee, c.updatedAt
FROM c
WHERE c.priority IN ('P1','P2')
AND c.status IN ('open','in-progress')
ORDER BY c.updatedAt ASCエージェントが作るクエリであっても、無制限に全項目を読ませる必要はありません。ツール側で取得件数、対象フィールド、許可するSQLの形、タイムアウト、ログ出力を制限しておくと、安全性とコスト管理の両方に効きます。
GROUP BYで詰まりやすいポイント
公式ブログでは、Python SDKでクロスパーティションの GROUP BY を扱う際の制約にも触れています。サンプルでは、キュー全体のグループ集計を単純な GROUP BY に任せるのではなく、対象フィールドをクロスパーティションで投影し、Python側で値を数える設計が紹介されています。(Microsoft for Developers)
ここは初心者が詰まりやすいポイントです。SQLだけを見て「GROUP BYで集計できるはず」と考えても、SDKやクロスパーティションの条件によって期待通りに動かない場合があります。
対処の考え方は次のとおりです。
| 状況 | 推奨される考え方 |
|---|---|
| 1顧客内など単一パーティションで集計する | Cosmos DB側のクエリで集計しやすい |
| キュー全体など複数パーティションをまたぐ | 必要フィールドだけ取得し、アプリ側で数える方法も検討する |
| 集計対象が大きい | 事前集計、別コンテナー、Change Feed、分析用ストアなども検討する |
| エージェントが頻繁に同じ集計を行う | キャッシュや専用APIを用意し、都度全件に近い検索を避ける |
エージェントに「今の負荷を見て」と頼むと、裏側ではステータス別、担当者別、領域別の集計が走る可能性があります。便利さだけでなく、実際にどのクエリが発行されるかを観察することが大切です。
書き込みを許可する前に決めるべき境界線
Deep Agents with Azure Cosmos DB を本番に近づけるとき、最も慎重に設計すべきなのは書き込みです。公式サンプルでは、チケット更新時に updatedAt を更新し、履歴配列に変更理由を追加する設計が紹介されています。(Microsoft for Developers)
実務では、少なくとも次の境界線を決めてから書き込みを許可します。
| 境界線 | 決める内容 |
|---|---|
| 更新してよいフィールド | status、assignee、tags などに限定する |
| 更新してはいけないフィールド | 顧客ID、請求金額、監査ID、作成日時などを保護する |
| 一度に更新してよい件数 | 1件だけ、または承認後に複数件などルール化する |
| 人の承認が必要な操作 | 複数チケットの一括タグ付け、ステータス一括変更、担当者変更など |
| 監査ログ | 誰が、いつ、どの依頼で、何を変更したかを残す |
| 検証方法 | 書き込み後に再読み取りし、期待値と照合する |
公式ブログのインシデント検出例では、ログイン関連チケットのまとまりを見つけた後、複数チケットへのタグ付けについては確認を求める流れになっています。複数件更新は単一チケット更新より影響が大きいため、承認ステップを挟む設計が現実的です。(Microsoft for Developers)
最初に試すべきプロンプト例
サンプルを動かしたら、まずは読み取り中心のプロンプトから試します。
python agent.py --query "I just got in, what should I look at first?"次に、キューの状況確認を試します。
python agent.py --query "Give me a snapshot of the queue, who's overloaded right now?"書き込みの動作を確認したい場合は、サンプルデータで対象チケットを明示して試します。
python agent.py --query "GLOBEX is unhappy about TICKET-1050, can you pick it up and move it forward?"ただし、いきなり自社の本番チケットや注文データに対して同じことを行うべきではありません。まずはデモデータで、エージェントがどのツールを呼び、どのクエリを作り、どのタイミングで書き込み、どう検証するかを確認します。
本番導入前のチェックリスト
本番や検証環境に近いデータへ接続する前に、次の項目を確認してください。
| チェック項目 | 確認内容 |
|---|---|
| データ分類 | 個人情報、機密情報、契約情報、監査対象データが含まれるか |
| 実行環境 | サンプル環境、検証環境、本番環境を分けているか |
| 認証方式 | キー埋め込みではなく、Entra IDベースの認証にできているか |
| 権限 | 読み取り専用から始め、書き込み権限は最小範囲にできているか |
| ツール制約 | 読み取り、書き込み、集計、検証のツールを分離しているか |
| ログ | プロンプト、ツール呼び出し、クエリ、更新結果を追跡できるか |
| コスト | クロスパーティションクエリ、集計、モデル呼び出しの増加を見込んでいるか |
| 失敗時対応 | 更新失敗、部分更新、タイムアウト、権限エラー時の動作を決めているか |
| 人の承認 | 複数件更新や重要フィールド変更に承認ゲートを入れているか |
| ロールバック | 誤更新時に戻せる履歴、バックアップ、再投入手順を用意しているか |
特に、AIエージェントは「便利な管理者」ではなく「制限された業務ツール利用者」として扱うべきです。最初から広い権限を与えるのではなく、読み取り、単一レコード更新、承認付き複数更新の順に広げていくと安全です。
よくある失敗と対策
Deep Agents with Azure Cosmos DB の使い方で失敗しやすい点を整理すると、次のようになります。
| 失敗しやすいポイント | 起きる問題 | 対策 |
|---|---|---|
| いきなり本番データに接続する | 想定外の読み取りや更新が起きる | サンプルデータ、検証環境、読み取り専用から始める |
SELECT * を許可する | RU消費や情報露出が増える | 必要フィールドだけ投影する |
| 書き込み後に確認しない | 実際は更新されていないのに完了扱いになる | 書き込み後に必ず再読み取りする |
| ツールに広すぎる権限を持たせる | AIの判断ミスが直接データ変更につながる | 読み取りツールと書き込みツールを分ける |
| パーティションキーを考えない | 主要な問い合わせが常に高コストになる | 業務上よく一緒に読む単位で設計する |
| 集計をすべてDB側に任せる | SDKやクロスパーティション条件で詰まる | 必要に応じてアプリ側集計や事前集計を使う |
| 曖昧な指示をそのまま実行させる | 誤ったチケットやデータを更新する | 対象が曖昧な場合は質問させる |
READMEでも、エージェントは間違った前提にそのまま従うのではなく、実際のデータに基づいて押し返したり、対象が曖昧な場合に確認したりする例が紹介されています。(GitHub)
MCP ToolkitやRAGとの違い
Azure Cosmos DB とAIエージェントの話題では、MCP Toolkit、RAG、ベクトル検索、Agentic Retrieval なども出てくるため混乱しやすいです。今回のサンプルは、ベクトル検索やフルテキスト検索を前提にしたRAGというより、Cosmos DB上の構造化された運用データに対して、エージェントがSQL的な問い合わせと更新を行う例です。READMEでも「ベクトルやフルテキストインデックスではなく、運用データに対する構造化された agentic SQL」と説明されています。(GitHub)
一方、Azure Cosmos DB の MCP Toolkit は、AIエージェントや開発ツールから Cosmos DB の機能に接続する別の方法です。Microsoft Learnでは、データベース一覧、コンテナー一覧、最近のドキュメント取得、ID検索、テキスト検索、ベクトル検索、スキーマ推定などのツールが紹介されています。(Microsoft Learn)
使い分けの目安は次のとおりです。
| 選択肢 | 向いている場面 |
|---|---|
| 今回のDeep Agentsサンプル | 自社業務に合わせて、読み取り・更新・検証の流れをコードで細かく制御したい |
| MCP Toolkit | 既存のエージェント環境や開発ツールから Cosmos DB に接続する標準的な入口を用意したい |
| RAG・ベクトル検索 | 文書、ナレッジ、類似情報を意味検索して回答に使いたい |
| Agent Memory Toolkit | エージェントの長期記憶や状態を Cosmos DB に持たせたい |
今回のテーマで最初に見るべきなのは、「AIがデータベースに触れるとき、どの操作を許可し、どう検証するか」です。検索精度やベクトル化の話よりも、ツール境界と運用安全性が中心になります。
一般ユーザー・管理者が次に取るべき行動
この公式情報を見た一般ユーザーやAzure管理者がすぐに行うべきことは、既存環境の設定変更ではありません。まずは、自社の業務データの中に「エージェントが読むだけで価値が出る運用キュー」があるかを洗い出すことです。
候補になりやすいのは、問い合わせ、障害、注文、申請、アラート、デバイスイベントなどです。これらは「状態」「担当者」「優先度」「更新日時」「顧客ID」などの項目を持ち、エージェントが複数条件を見ながら判断しやすいデータです。
次の順序で進めると安全です。
| 段階 | やること |
|---|---|
| まず確認 | 公式ブログとサンプルREADMEを読み、構成を理解する |
| 検証準備 | Azure Cosmos DB、Azure OpenAI、Azure CLI、Python環境を用意する |
| サンプル実行 | シードデータで読み取り系プロンプトを試す |
| 動作観察 | どのツール、どのクエリ、どの更新が行われるか確認する |
| 自社データ検討 | パーティションキー、権限、更新可能フィールドを設計する |
| 小さく導入 | 読み取り専用の業務支援から始める |
| 書き込み拡張 | 承認、履歴、検証、ロールバックを整えてから許可する |
Deep Agents with Azure Cosmos DB は、AIにデータベースを自由に触らせるための仕組みではありません。Azure Cosmos DB上の運用データを、制限されたツール、最小権限、確認可能な履歴、更新後の検証と組み合わせて扱うための設計例です。
まずはサンプルを読み取り専用で動かし、エージェントが「何を計画し、どのツールを呼び、何を根拠に回答するのか」を確認してください。その動きが把握できたら、自社のチケット、申請、注文、アラートなどに置き換えられるかを検討するのが、最も現実的な第一歩です。
コメント