Azure SDK ドキュメント更新として公開・更新された「Add hosted agent configuration to .env.template and create .gitignore…」は、アプリ本体のAPI変更というより、Azure AI ProjectsのHosted agentsをテスト・サンプルで扱いやすくするための環境変数テンプレート更新です。結論から言うと、通常のAzure SDK利用者がすぐ本番コードを書き換える必要は低い一方、azure-ai-projects のサンプル実行、CI/CD、Hosted agentsの検証環境を持つ開発者・管理者は、.env、Secrets、ログ出力、.gitignoreの扱いを確認しておくべきです。
この更新はAzure SDK for PythonリポジトリのPR #46965で確認できます。GitHub上では2026年5月19日に feature/azure-ai-projects/2.2.0 ブランチへマージされており、変更対象は sdk/ai/azure-ai-projects/.env.template と sdk/ai/azure-ai-projects/.github/skills/update-env-vars/.gitignore の2ファイルです。2026年5月20日時点で確認すべき内容としては、「Hosted agents用の環境変数がテンプレートに追加されたこと」と「環境変数更新用ディレクトリで生成物を誤ってコミットしにくくなったこと」が中心です。(GitHub)
Azure SDKのAI/Copilot関連更新で何が変わるのか
今回のAzure SDK ドキュメント更新は、Azure AI Projectsまわりの開発・テスト体験を整える小さな変更です。.github/skills/update-env-vars というパス名からAI/Copilot関連の開発補助フローを連想しやすいですが、公式PRで確認できる実体は、Hosted agents向けの環境変数追加と、生成ファイルを管理対象外にする .gitignore の追加です。(GitHub)
| 変更箇所 | 変更内容 | 実務上の意味 |
|---|---|---|
sdk/ai/azure-ai-projects/.env.template | FOUNDRY_HOSTED_AGENT_NAME= を追加 | Hosted agentsのテストやサンプルで参照するエージェント名を、既存の .env 運用に合わせて管理しやすくなる |
sdk/ai/azure-ai-projects/.env.template | サンプルテスト用ログ変数の記述を整理 | SAMPLE_TEST_PASSED_LOG などのログファイル名パターンを明示し、サンプル検証時のログ確認をしやすくする |
sdk/ai/azure-ai-projects/.github/skills/update-env-vars/.gitignore | * と !.gitignore を追加 | update-env-vars 配下で作られる一時ファイルや生成物を、原則としてGit管理対象から外す |
重要なのは、今回のPRだけを見る限り、SDKの公開API、認証方式、エンドポイント仕様を直接変更する更新ではないという点です。影響は主に、Azure SDK for Pythonリポジトリを使って azure-ai-projects のサンプルやライブテストを動かす開発者、またはHosted agents関連の検証をCIに組み込んでいるチームに及びます。
Hosted agentsとは何か
Hosted agentsは、Microsoft Foundry Agent Service上で動くコンテナベースのAIエージェントです。Microsoft Learnでは、Hosted agentsを「自分のコンテナ化されたエージェントランタイムを実行しつつ、Microsoft Foundryのマネージドホスティングとスケーリングを使う仕組み」と説明しています。Azure AI ProjectsのPythonクライアントライブラリにも samples/hosted_agents/ が用意され、CRUD、ファイルアップロード・ダウンロード、skillsシナリオなどのSDK利用例が案内されています。(Microsoft Learn)
通常のPrompt agentは、ポータル上の指示文やツール設定を中心に構成できます。一方、Hosted agentsは自分のコードをコンテナイメージとしてパッケージし、Foundry Agent Serviceにデプロイします。Microsoftの説明では、デプロイ時にAgent ServiceがAzure Container Registryからイメージを取得し、コンピュート、専用のMicrosoft Entra ID、エンドポイント、スケーリング、状態管理、監視などを扱います。(Microsoft Learn)
| エージェント種別 | 向いている用途 | 注意点 |
|---|---|---|
| Prompt agent | すばやい試作、社内FAQ、単純なツール連携 | 独自の実行ロジックを細かく制御しにくい |
| Workflow agent | 承認、分岐、複数エージェントの連携 | プレビュー機能の扱いやワークフロー定義の管理が必要 |
| Hosted agents | LangGraph、Semantic Kernel、独自コードなどを使った高度なエージェント | コンテナ、環境変数、ID、ロール、ログ、デプロイバージョン管理が重要 |
つまり、FOUNDRY_HOSTED_AGENT_NAME の追加は、Azure AI ProjectsのHosted agentsサンプルやテストで「どのHosted agentを対象にするか」を環境変数として明示するための下準備と見るのが自然です。
.env.templateに追加された設定の意味
PR後の .env.template には、既存の FOUNDRY_PROJECT_ENDPOINT、FOUNDRY_MODEL_NAME、FOUNDRY_AGENT_NAME、FOUNDRY_AGENT_CONTAINER_IMAGE などに加えて、テスト用の領域に FOUNDRY_HOSTED_AGENT_NAME= が追加されています。テンプレート自体には、値は空のままにし、ローカルでテストする場合は .env.template を .env にコピーして値を埋め、リポジトリへコミットしない旨が書かれています。(GitHub)
Hosted agentsを試す開発者は、少なくとも次のような環境変数の整理が必要になります。
FOUNDRY_PROJECT_ENDPOINT=https://<resource-name>.services.ai.azure.com/api/projects/<project-name>
FOUNDRY_MODEL_NAME=<model-deployment-name>
FOUNDRY_AGENT_CONTAINER_IMAGE=<container-image>
FOUNDRY_HOSTED_AGENT_NAME=<hosted-agent-name>
AZURE_TEST_RUN_LIVE=false
AZURE_SKIP_LIVE_RECORDING=trueここで混同しやすいのが、FOUNDRY_AGENT_NAME と FOUNDRY_HOSTED_AGENT_NAME です。前者は既存のエージェント関連サンプルで使われる名前、後者はHosted agents向けの名前として分けて管理する意図があると考えられます。チーム内で .env のテンプレートを独自にコピーしている場合は、FOUNDRY_HOSTED_AGENT_NAME が欠けていないか確認してください。
管理者・開発者が確認すべき影響範囲
今回のAzure SDK更新は小規模ですが、CI/CDやSecrets管理に関わるため、影響範囲を役割ごとに分けて確認すると安全です。
| 対象者 | 確認すべきこと | 対応の優先度 |
|---|---|---|
| アプリ利用者 | 既存アプリが azure-ai-projects の通常APIだけを使っているか | 低 |
| SDKサンプルを動かす開発者 | .env.template を最新版に合わせ、FOUNDRY_HOSTED_AGENT_NAME を必要に応じて追加する | 中 |
| Hosted agents検証担当 | Hosted agent名、コンテナイメージ、プロジェクトエンドポイント、RBACを確認する | 高 |
| CI/CD管理者 | Pipeline Variables、GitHub Actions Secrets、Azure DevOps Libraryなどに新しい変数が必要か確認する | 高 |
| セキュリティ管理者 | .env、ログ、生成ファイル、未redactログがコミットされない運用になっているか確認する | 高 |
特に、Hosted agentsはプレビュー機能として扱われています。Microsoft LearnでもHosted agentsはpublic previewとされているため、本番導入では可用性、リージョン、制限、変更可能性を前提に設計する必要があります。(Microsoft Learn)
.gitignore追加で何が安全になるのか
新しく追加された .gitignore は、sdk/ai/azure-ai-projects/.github/skills/update-env-vars/ 配下に置かれています。中身はシンプルで、すべてのファイルを無視しつつ、.gitignore 自体だけは追跡する設定です。(GitHub)
*
!.gitignoreこのパターンは、ディレクトリの存在やルールは残したいが、その中で作られる一時ファイル、出力ファイル、ローカル生成物はコミットしたくない場合によく使われます。環境変数更新を補助するスクリプトやAI/skills系の処理では、途中で .env 相当のファイル、差分、ログ、入力サンプルが生成される可能性があります。そうしたファイルがリポジトリに混入すると、機密情報の漏えいやレビュー時のノイズにつながります。
今回の .gitignore 追加は、機能追加というより「事故を起こしにくいリポジトリ運用」に近い変更です。管理者は、自社リポジトリでも同じ考え方を使えます。たとえば、環境変数を自動生成するディレクトリ、ローカル検証用の出力先、AIエージェントの実験ログ用ディレクトリには、最初から明示的な .gitignore を置いておくと安全です。
設定・移行・展開で失敗しやすいポイント
.env.templateを更新しただけで.envが更新されたと思い込む
.env.template はあくまでテンプレートです。ローカル環境やCIで実際に読み込まれる .env、Secrets、Pipeline Variablesは別管理になっていることが多いため、テンプレート更新後に実行環境の変数を追加し忘れるケースがあります。
Hosted agentsのサンプルやテストでエージェント名が見つからない、KeyError が出る、対象エージェントが空になるといった症状が出た場合は、まず FOUNDRY_HOSTED_AGENT_NAME の有無を確認してください。
Foundry SDKのプロジェクトエンドポイントとAzure OpenAIエンドポイントを混同する
Foundry SDKは、https://<resource-name>.services.ai.azure.com/api/projects/<project-name> 形式の単一プロジェクトエンドポイントに接続します。Microsoft Learnでは、Python向けに azure-ai-projects>=2.0.0 を使う案内があり、Project clientとOpenAI互換クライアントを使い分ける設計も説明されています。(Microsoft Learn)
Azure OpenAIの /openai/v1 エンドポイントと、Foundry SDKのプロジェクトエンドポイントは用途が異なります。Hosted agentsやFoundry固有機能を扱う場合は、まずプロジェクトエンドポイント、RBAC、対象プロジェクト名が正しいかを確認しましょう。
Preview機能の有効化を忘れる
AIProjectClient のAPIリファレンスでは、Hosted Agentを作成する場合に allow_preview=True を設定する必要があると説明されています。get_openai_client で agent_name を指定する場合も、allow_preview=True が設定されていないと ValueError が発生する可能性があります。(Microsoft Learn)
Hosted agentsを扱うコードでは、次のようにプレビュー機能を明示します。
import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
project_client = AIProjectClient(
endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
credential=DefaultAzureCredential(),
allow_preview=True,
)ただし、プレビュー機能は将来の仕様変更があり得ます。本番ワークロードに近い用途で使う場合は、SDKバージョン、APIリファレンス、リージョン、サポート範囲を定期的に見直してください。
環境変数を後から変えれば既存デプロイにも反映されると思い込む
Hosted agentsでは、バージョン作成時にコンテナイメージ、リソース割り当て、環境変数、プロトコル設定などがスナップショット化されます。Microsoft Learnでは、各バージョンはimmutableであり、環境変数もバージョンごとに設定されると説明されています。(Microsoft Learn)
つまり、.env やCIの変数を変更しても、すでに作成済みのHosted agentバージョンに自動で反映されるとは限りません。変更を反映したい場合は、新しいバージョンを作成し、必要に応じてカナリアリリースやブルーグリーンデプロイのように段階的に切り替える設計が必要です。
シークレットやログを軽く扱う
Hosted agentsのドキュメントでは、シークレットをコンテナイメージや環境変数に入れず、マネージドID、接続、マネージドなシークレットストアを使うことが推奨されています。サードパーティのモデル、サーバー、エージェントにデータが流れる場合は、保持、共有、所在地、コンプライアンス境界を自組織で確認する責任があります。(Microsoft Learn)
今回の .env.template ではサンプルテスト用のログファイル名も明示されています。ログは便利ですが、プロンプト、応答、ファイル名、接続情報、エラー本文に機密情報が含まれることがあります。CIでアーティファクトとして保存する場合は、保存期間、閲覧権限、マスキング設定を確認してください。
CI/CDでの確認手順
Azure SDK for Pythonリポジトリや azure-ai-projects のサンプルをCIで動かしている場合は、次の順序で確認すると手戻りを減らせます。
| 手順 | 作業 | 確認ポイント |
|---|---|---|
| 1 | 最新の .env.template と自社の .env.example を比較する | FOUNDRY_HOSTED_AGENT_NAME が欠けていないか |
| 2 | CIのSecretsまたはVariablesを更新する | 値を平文でYAMLに書いていないか |
| 3 | Hosted agents用のテストだけを限定実行する | 既存のAgentテストとHosted agentテストを混同していないか |
| 4 | ログ出力先を確認する | SAMPLE_TEST_*_LOG が不要な場所に残らないか |
| 5 | 生成ファイルを確認する | git status に .env、ログ、一時ファイルが出ていないか |
| 6 | 本番展開前にRBACを確認する | 開発者個人の権限ではなく、CI用IDまたはマネージドIDで通るか |
ローカル確認では、次のコマンドが役立ちます。
git status --short
pip show azure-ai-projects
python --version
az account showgit status --short で .env やログファイルが表示される場合は、.gitignore の設計を見直してください。pip show azure-ai-projects はSDKバージョン不一致の切り分けに有効です。Microsoft Learnでも、SDKサンプルが AttributeError や ModuleNotFoundError で失敗する場合は、SDKバージョンを確認する流れが案内されています。(Microsoft Learn)
今回の更新で慌ててやらなくてよいこと
今回の変更は、Azure SDK全体の破壊的変更や、既存アプリの認証方式変更を示すものではありません。そのため、次のような対応を急ぐ必要はありません。
- すべてのAzure SDK利用アプリを一斉に書き換える
- Hosted agentsを使っていない環境に
FOUNDRY_HOSTED_AGENT_NAMEを無理に設定する - 本番環境のエンドポイントを変更する
.env.templateの値をそのまま本番Secretsへコピーする- プレビュー機能を検証なしで本番ワークロードに組み込む
一方で、Hosted agentsを試しているチーム、Azure AI Projectsのサンプルを教材やPoCに使っているチーム、CIでライブテストを実行しているチームは、今回のテンプレート変更を反映しておくとトラブルを避けやすくなります。
管理者と開発者が次に取るべき行動
まず、Hosted agentsを使っているか、または今後使う予定があるかを確認してください。使っていない場合、今回のAzure SDK ドキュメント更新は情報把握で十分です。使っている場合は、.env.template、CI Secrets、Hosted agent名、コンテナイメージ名、RBAC、ログ保存先をセットで見直しましょう。
開発者は、サンプルやテストを動かす前に FOUNDRY_HOSTED_AGENT_NAME を追加し、allow_preview=True が必要なコードパスか確認してください。管理者は、.env や生成ファイルがGitに混入しない運用、CIログに機密情報が残らない設定、マネージドIDやRBACの最小権限化を確認するのが実務上の優先事項です。
今回の更新は小さく見えますが、AIエージェント開発では「環境変数」「生成ファイル」「ログ」「プレビュー機能」の扱いが事故の入口になりやすい領域です。Azure SDKの差分を単なるドキュメント更新として流さず、自社のHosted agents検証フローとCI/CD運用に照らして確認しておくことが、安定したAIアプリ開発につながります。
コメント