Azure Developer CLI（azd）のAIエージェント向けコードデプロイで、.agentignore を使ってZIPパッケージに含めないファイルを指定できるようになりました。最初に押さえるべき結論は、.agentignore を作成すると既定の除外ルールを自分で引き継ぐ必要があることです。特に .env、.azure/、.git/ などを除外し忘れると、ローカル環境情報や機密情報を含むファイルがデプロイ対象に入る可能性があります。
この変更は、Microsoft Foundry にAIエージェントをデプロイする azd AIエージェント拡張機能の「コードデプロイ時のパッケージング」を制御しやすくするものです。公式PRでは、.gitignore 形式の .agentignore 対応、既定除外ルール、azd ai agent init での既定ファイル生成、デプロイ待機中のポーリング表示改善が追加されています。(GitHub)
Microsoft AzureのAIエージェント更新で何が変わるのか
今回の更新は、Azureそのものの認証方式やMicrosoft Foundryのエージェント実行基盤を大きく変えるものではありません。変更の中心は、azd でAIエージェントをコードデプロイする際に作成されるZIPパッケージの中身を、開発者が .agentignore で制御できるようになった点です。
Microsoft Learnでは、Azure Developer CLIのAIエージェント拡張機能について、Microsoft Foundryへのエージェントのスキャフォールディング、プロビジョニング、デプロイを azd init や azd up と組み合わせて実行できるワークフローとして説明しています。今回の .agentignore は、このワークフローのうち「エージェントコードをどのファイル構成でアップロードするか」に関わる更新です。(Microsoft Learn)
| 確認項目 | 変更前の考え方 | 変更後の考え方 | 実務上の影響 |
|---|---|---|---|
| 除外ルール | ハードコードされた除外に依存 | .agentignore で利用者が制御可能 | プロジェクトごとの不要ファイルを除外しやすい |
.agentignore がない場合 | 既定除外が使われる | 引き続き既定除外が使われる | 既存プロジェクトは急に壊れにくい |
.agentignore がある場合 | 該当なし | 利用者ルールが既定ルールを置き換える | セキュリティ除外の書き忘れに注意 |
| 新規初期化 | 手動管理が中心 | azd ai agent init で既定 .agentignore を生成 | 新規プロジェクトでは標準化しやすい |
| デプロイ待機表示 | 進行状況が分かりにくい場合がある | ポーリング試行回数を表示 | デプロイが停止しているのか判断しやすい |
PRの説明では、.agentignore が存在しない場合はPython、.NET、Node関連の成果物やazd関連ファイルなどの既定除外が適用され、.agentignore が存在する場合は利用者のルールが既定ルールを置き換えるとされています。(GitHub)
対象になる環境と対象外の環境
この更新の対象は、主に次のような環境です。
- Azure Developer CLI（azd）を使っている
azure.ai.agents拡張機能でMicrosoft Foundry向けエージェントを扱っているagent.yamlに基づくHosted Agentをコードデプロイしているazd up、azd deploy、または関連するAIエージェントデプロイフローをCI/CDに組み込んでいる
一方で、すべてのAzureデプロイに .agentignore が効くわけではありません。Azure App Service、Azure Functions、Azure Container Appsなどの一般的なデプロイ全体を制御するファイルではなく、今回の対象はAzure Developer CLIのAIエージェント向けコードデプロイパッケージングです。
また、コンテナイメージをビルドしてAzure Container Registryへプッシュするコンテナデプロイでは、.dockerignore やDockerfile側の設計が引き続き重要です。.agentignore は、コードをZIP化してアップロードする経路で特に意味を持ちます。
.agentignore の動作で最も重要なポイント
.agentignore は、名前から分かる通り「エージェント用のignoreファイル」です。ただし、.gitignore や .dockerignore と同じものではありません。
.gitignore との違い
.gitignore は、Gitリポジトリに追跡させないファイルを指定します。.agentignore は、デプロイ用ZIPパッケージに含めないファイルを指定します。
たとえば、次のような違いがあります。
| ファイル | 主な役割 | 影響する対象 |
|---|---|---|
.gitignore | Git管理から除外する | コミット、リポジトリ |
.dockerignore | Dockerビルドコンテキストから除外する | コンテナイメージビルド |
.agentignore | AIエージェントのコードデプロイZIPから除外する | azd のAIエージェントコードデプロイ |
.gitignore に書いてあるから安全、とは考えないでください。ローカルに存在するファイルがGit管理外であっても、.agentignore で除外されていなければ、コードデプロイのパッケージに含まれる可能性があります。
.agentignore がない場合
.agentignore が存在しない場合、実装上は既定の除外ルールが使われます。既定ルールには、Pythonのキャッシュ、仮想環境、Nodeの node_modules/、.NETの bin/ や obj/、.env、.azure/、.git/、agent.yaml、azure.yaml などが含まれます。(GitHub)
つまり、既存プロジェクトに .agentignore を追加していない場合、基本的には従来と同様の除外が働く設計です。PRでも「.agentignore がない既存フローへの影響はない」と説明されています。(GitHub)
.agentignore がある場合
.agentignore を置いた場合は、利用者が書いたルールが優先されます。テストコードでも、利用者が *.log だけを書いた .agentignore を作成した場合、既定で除外されるはずの __pycache__、node_modules、.env、.git などは除外されないことが確認されています。(GitHub)
ここが今回の更新で最も注意すべき点です。
「自分で .agentignore を作ったら、既定の安全な除外も自分で書く」
このルールをチーム内で共有しておく必要があります。
まず入れておきたい .agentignore の実用サンプル
既存プロジェクトで .agentignore を追加する場合は、いきなり独自ルールだけを書くのではなく、既定除外に近い内容を残したうえで、プロジェクト固有の除外を追加するのが安全です。
# azd tooling files
agent.yaml
agent.manifest.yaml
azure.yaml
.agentignore
# Security / secrets
.env
.env.*
.azure/
.git/
# Python
__pycache__/
.venv/
venv/
*.pyc
*.pyo
.mypy_cache/
.pytest_cache/
# .NET
bin/
obj/
*.user
*.suo
.vs/
# Node
node_modules/
# Docker files not needed for code deploy
Dockerfile
.dockerignore
# Project-specific examples
*.log
tmp/
.cache/
coverage/このサンプルで重要なのは、.env、.env.*、.azure/、.git/ を残している点です。Azureの環境変数、ローカルの認証状態、Gitメタデータ、環境別設定をデプロイパッケージに含めないための最低限の防衛線になります。
一方で、次のようなファイルはむやみに除外しないでください。
| ファイル | 除外に注意すべき理由 |
|---|---|
requirements.txt | Pythonの依存関係解決に必要な場合がある |
pyproject.toml | Pythonプロジェクト定義や依存関係に使われる場合がある |
package.json | Node.jsの依存関係や起動定義に必要な場合がある |
.csproj | .NETプロジェクトのビルドに必要 |
| エージェントのエントリーポイント | 除外するとデプロイ後に起動できない |
.agentignore はパッケージを軽くするためのファイルですが、必要な実行ファイルや依存関係定義まで消すと、デプロイは通っても実行時に失敗する可能性があります。
既存プロジェクトで確認すべき移行手順
既存のAzure AIエージェントプロジェクトでは、次の順で確認すると安全です。
サービスのルートディレクトリを確認する
まず、azure.yaml の services に定義されている対象サービスの project を確認します。多くの場合、そこが agent.yaml を含むエージェントのソースディレクトリです。
services:
MyAgent:
project: src/MyAgent
host: azure.ai.agentこの例では、.agentignore を置く場所は次のようになります。
src/MyAgent/.agentignore実装上、コードデプロイのパッケージングではエージェント定義ファイルのあるディレクトリをソースとして扱い、.agentignore があればそれを読み込む流れになっています。(GitHub)
既定ルールをベースに .agentignore を追加する
既存プロジェクトでは、まず前述のサンプルのように既定除外に近い内容を入れます。その後、プロジェクト固有の不要ファイルを追加します。
たとえば、テストデータや開発用ログを除外したい場合は、次のように末尾に追加します。
tests/fixtures/large-local-data/
*.local.json
*.debug.logただし、テストコードをエージェントの実行時に参照している場合や、サンプルデータをプロンプト処理で読み込んでいる場合は、除外すると動作が変わります。除外対象は「実行時に本当に不要か」を基準に判断してください。
CI/CDで拡張機能のバージョンを確認する
PRがマージされていても、手元やCI/CDの実行環境に反映されているとは限りません。Azure Developer CLI本体と拡張機能の状態を確認してください。
azd version
azd extension list --installed
azd extension upgrade azure.ai.agentsMicrosoft Learnの拡張機能ドキュメントでは、azd extension list --installed によるインストール済み拡張機能の確認や、azd extension upgrade <extension-name> による拡張機能の更新が説明されています。(Microsoft Learn)
azd 本体については、azd update で更新できる環境もあります。ただし、インストール方法によって更新手段が異なるため、組織の標準手順に合わせてください。(Microsoft Learn)
パッケージサイズとデプロイログを確認する
.agentignore の追加後は、初回のデプロイで次の点を確認します。
- ZIPパッケージが極端に大きくなっていないか
.envや.azure/が含まれていない前提で運用できているか- 依存関係ファイルを除外していないか
Packaging codeの後に不自然なエラーが出ていないか- エージェントが
activeになるまでのポーリング状況が表示されるか
実装では、コードデプロイ用ZIPに最大サイズのチェックがあり、サイズ超過時には不要ファイルの除外や依存関係解決方式の見直しが示されます。.agentignore は、サイズ超過や不要ファイル混入を防ぐための実用的な対策になります。(GitHub)
管理者・開発者・CI/CD担当者が確認すべきポイント
.agentignore は小さなファイルですが、運用上はセキュリティ、ビルド再現性、CI/CD標準化に関わります。担当者ごとに見るべき観点が異なります。
| 担当者 | 確認すべきこと | 具体的な対応 |
|---|---|---|
| Azure管理者 | 機密ファイルがパッケージに入らないか | .env、.azure/、.git/ の除外をレビュー項目にする |
| 開発リーダー | 必要な依存関係ファイルを除外していないか | requirements.txt、.csproj、package.json などを確認する |
| CI/CD担当者 | 実行環境のazdと拡張機能が対応済みか | azd version と拡張機能バージョン確認をパイプラインに入れる |
| セキュリティ担当者 | .agentignore 変更が監査対象になっているか | PRレビューやCODEOWNERSで確認者を固定する |
| プラットフォーム担当者 | 新規テンプレートに標準 .agentignore が含まれるか | 社内テンプレートやサンプルに反映する |
特に本番環境では、.agentignore の変更を単なる開発者設定として扱わないことが重要です。除外ルールを1行消すだけで、デプロイパッケージの中身が変わります。インフラコードやCI/CD定義と同じく、レビュー対象にしてください。
失敗しやすいポイント
空の .agentignore を置いてしまう
空の .agentignore は「何も除外しない」という意味になります。テストコードでも、空ファイルの場合は __pycache__ や .env が除外されない挙動が確認されています。(GitHub)
「とりあえずファイルだけ作る」は危険です。作るなら、最低限の除外ルールまで入れてからコミットしてください。
.gitignore をそのままコピーする
.gitignore をそのまま .agentignore にコピーすると、必要なファイルを除外してしまうことがあります。
たとえば、開発中はGit管理しない生成ファイルでも、実行時には必要な場合があります。逆に、Git管理外の .env がローカルに存在している場合、.agentignore に書かれていなければデプロイ対象になる可能性があります。
.gitignore はリポジトリ管理、.agentignore はデプロイ管理です。目的を分けて設計してください。
.azdignore と混同する
関連Issueでは、当初 .azdignore のような名前での除外ファイルが提案されていました。しかし、実際のPRでは .agentignore として実装されています。過去のメモや社内ドキュメントに .azdignore と書かれている場合は、現在の実装に合わせて修正してください。(GitHub)
サブディレクトリごとに .agentignore を置く
既定の .agentignore 内容には、ルートの .agentignore のみが読み込まれ、サブディレクトリのファイルはサポートされない旨が含まれています。複数階層に分けて制御するのではなく、サービスルートの .agentignore にルールを集約する運用にしてください。(GitHub)
シンボリックリンクで共通化する
実装では、.agentignore は通常ファイルである必要があります。テストでも、.agentignore がシンボリックリンクの場合にエラーになるケースが確認されています。複数サービスで共通ルールを使いたい場合は、CIでコピーする、テンプレートに含める、リポジトリ内で標準ファイルを管理して同期するなど、通常ファイルとして配置する方法を選んでください。(GitHub)
デプロイ時の注意点
依存関係解決方式によって影響が変わる
コードデプロイでは、ZIP化したソースをもとにリモート側で依存関係を解決する構成があります。この場合、依存関係定義ファイルを .agentignore で除外すると、ビルドや起動に失敗する可能性があります。
一方、.NETの一部構成では dotnet publish の出力をZIP化する処理が使われる場合があります。つまり、すべてのパッケージング経路で .agentignore が同じように効くとは限りません。デプロイログに出る Packaging の種類や、remote_build / bundled などの依存関係解決方式を確認しながら検証してください。(GitHub)
パッケージを軽くしすぎない
.agentignore の目的は、不要なファイルを削ることです。しかし、削りすぎると実行に必要なファイルまで消えます。
判断基準はシンプルです。
- ローカル開発だけに必要なものは除外する
- 実行時に読み込むものは除外しない
- 依存関係解決に必要なものは除外しない
- 機密情報はファイルで同梱せず、環境変数、マネージドID、Key Vaultなどで扱う
Microsoft Learnでは、azd AIエージェント拡張機能がマネージドIDやロール割り当てなどの安全なアクセスパターンを構成することも説明されています。秘密情報をパッケージに含めるのではなく、Azure側のIDと権限設計に寄せるのが基本です。(Microsoft Learn)
ポーリング表示を「正常な待機」と「異常停止」の判断に使う
今回のPRでは、エージェントがアクティブになるまでの待機処理で、ポーリング試行回数を表示する改善も含まれています。これにより、デプロイが完全に止まっているのか、エージェントの状態反映を待っているのかを判断しやすくなります。(GitHub)
CI/CDでは、単に「時間がかかっている」と判断してジョブを中断するのではなく、ログにポーリング状況が出ているか、最後のステータスが何かを確認してください。
よくある疑問
.agentignore は必ず作るべきですか
新規プロジェクトでは、azd ai agent init により既定の .agentignore が生成される流れになっています。既存プロジェクトでも、デプロイ対象を明確にしたい場合は作成を推奨します。ただし、空ファイルや独自ルールだけのファイルを置くのではなく、既定のセキュリティ除外を含めて管理してください。(GitHub)
.env を除外しても、環境変数は使えますか
使えます。むしろ、.env をコードパッケージに含めるべきではありません。ローカルやazd環境の値は、デプロイ設定、環境変数、マネージドID、Azure側の接続設定で扱うのが基本です。
.agentignore に !important.txt のような否定ルールは使えますか
PRでは .gitignore 構文の利用が説明されており、テストでも否定パターンの動作が確認されています。たとえば *.txt でテキストファイルを除外しつつ、!important.txt で特定ファイルだけ含める、といった使い方ができます。(GitHub)
.dockerignore は不要になりますか
不要にはなりません。.dockerignore はDockerビルドコンテキストの制御に使います。.agentignore はAIエージェントのコードデプロイZIPの制御に使います。コンテナデプロイとコードデプロイを併用するチームでは、両方を別々に管理してください。
まとめ：.agentignore はデプロイ用の別ルールとして管理する
今回のAzure Developer CLI AIエージェント更新では、.agentignore によりコードデプロイのパッケージ内容を細かく制御できるようになりました。不要なキャッシュ、ビルド成果物、ローカル環境ファイルを除外できるため、パッケージサイズの削減と安全性向上に役立ちます。
一方で、.agentignore を作成すると既定除外を自分で引き継ぐ必要があります。既存プロジェクトでは、まずサービスルートを確認し、.env、.azure/、.git/、agent.yaml、azure.yaml などの除外を含む標準ルールを作成してください。そのうえで、CI/CDのazd本体と azure.ai.agents 拡張機能を更新し、初回デプロイでパッケージサイズ、依存関係、ログ、エージェントのアクティブ化状況を確認するのが安全な進め方です。
.agentignore は「あると便利な設定ファイル」ではなく、AIエージェントを安全にデプロイするためのパッケージ境界です。今後のMicrosoft Foundry向けAIエージェント開発では、.gitignore、.dockerignore、.agentignore を役割ごとに分け、レビュー対象として管理しましょう。
コメント