Azure AI Agents SDKでPROJECT_ENDPOINT_STRINGが見つからないときの原因と対処法【Foundry・リージョン・EU対応】

Azure AI Agents SDK へ移行しようとしたら、「PROJECT_ENDPOINT_STRING がどこにも出てこない」「接続文字列しか見えない」「model が解決できない」といった壁にぶつかるケースが増えています。本記事では、実際に報告されている事例を踏まえつつ、Project endpoint が表示されない原因とEU リージョンなど制約がある環境での具体的な解決手順を、コード例とチェックリスト付きで整理します。

Azure AI Agents SDK で PROJECT_ENDPOINT が必要になった背景

まず、「なぜ今までの connection string だけではダメなのか？」という背景から整理します。

旧 SDK と新 SDK の大きな違い

これまで多くのサンプルでは、次のように AIProjectClient.from_connection_string() を使っていました。

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
import os

client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=os.environ["PROJECT_CONNECTION_STRING"],
)

しかし Azure SDK の更新により、この from_connection_string は削除・非推奨となり、「プロジェクトのエンドポイント URL」を直接指定するスタイルが標準になりました。

新しいスタイルでは、azure-ai-agents（もしくはバージョンにより AgentsClient クラス）を、Project endpoint で初期化します。公式ドキュメントでも、Azure AI Foundry プロジェクトの Overview ページに表示される「Project endpoint」を PROJECT_ENDPOINT として環境変数に設定し、それをクライアントの endpoint 引数に渡すことが推奨されています。

import os
from azure.ai.agents import AgentsClient  # バージョンにより AIClient のこともあります
from azure.identity import DefaultAzureCredential

agents_client = AgentsClient(
    endpoint=os.environ["PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

つまり、「PROJECT_ENDPOINT_STRING = プロジェクトのエンドポイント URL」であり、旧来の「接続文字列」とは別物だという点が、最初の重要ポイントです。

旧 API と新 API の比較表

項目	旧 API（非推奨）	新 API（推奨）
主なパッケージ	`azure-ai-resources` / `azure-ai-generative` / `azure-ai-projects`	`azure-ai-projects` + `azure-ai-agents`
クライアントクラス	`AIClient` / `AIProjectClient`	`AgentsClient` や `AIProjectClient`（endpoint ベース）
接続方法	`from_connection_string()` に接続文字列を渡す	Project endpoint URL を `endpoint=` に渡す
認証方式	キー認証または AAD	Microsoft Entra ID（AAD）が前提
典型的な落とし穴	接続文字列のコピペミス	Project endpoint が見つからない／リージョン未対応／RBAC 不備

症状の整理：「Project endpoint が見えない」「InvalidUrlClientError」が出る

Azure ポータルでプロジェクトを開き、Project details を見ると、次のような状態になっていることがあります。

Project details に表示されるのが
- Project connection string
- Subscription / Subscription ID
- Location
のみで、Project endpoint という項目が存在しない。
自力で URL を組み立てて endpoint="https://<project>.<region>.inference.ai.azure.com" のように指定すると、
- InvalidUrlClientError
- もしくは “Failed to resolve host” 系のエラー
が出る。
Agents タブを開くと赤いエラーが出て、エージェントの一覧がそもそも表示されない。

こうした症状には、大きく分けて 2つの原因が絡んでいます。

プロジェクトの種類（Hub ベースか、Foundry ベースか）
リージョン（その地域で Agents サービスのエンドポイントが提供されているか）

それぞれ詳しく見ていきます。

原因1：Hub ベースと Foundry ベースの違いで endpoint が出ない

Hub ベースのプロジェクトでは Project endpoint が表示されない

Microsoft Q&A の回答でも指摘されている通り、Hub ベースのプロジェクトでは Project details が「接続文字列中心」の表示になり、Project endpoint が出てこないケースがあります。

公式回答の要点を要約すると、

Project details にエンドポイントがなく接続文字列だけが表示される場合、
- そのプロジェクトは Hub ベースである可能性が高い
新しい Azure AI Agents SDK で PROJECT_ENDPOINT_STRING を使いたい場合は、
- スタンドアロン（Hub なし）の Foundry ベースプロジェクトを作る必要がある

ということになります。

Hub ベース / Foundry ベースの見分け方

観点	Hub ベースプロジェクト	Foundry ベース（スタンドアロン）プロジェクト
作成パス	AI Hub から紐づけて作成	Hub とは独立して「AI Foundry project」を作成
Project details の表示	Project connection string が主、Project endpoint が出ないことが多い	Project endpoint が明示される
Agents タブ	リージョンや機能によっては非対応でエラーになりやすい	対応リージョンであればエージェント一覧が表示される
SDK からの接続	新しい `AgentsClient` / `AIClient` では扱いづらい	Project endpoint URL をそのまま SDK に渡せる

Foundry ベース（スタンドアロン）プロジェクトを作り直す手順

既存プロジェクトが Hub ベースっぽい場合、遠回りに感じても、新しく Foundry ベースのプロジェクトを作り直すのが近道です。

Azure ポータル（または Azure AI Studio / AI Foundry ポータル）にサインイン
「プロジェクトの新規作成」から、Hub に紐づいていないスタンドアロンの Foundry プロジェクトを選択
リージョンを選ぶ（EU 制約があるなら EU 内のリージョン）
作成後、プロジェクトの Project overview → Project details を開く
Project endpoint という項目が表示されるかを確認

ここで Project endpoint が表示されていれば第一関門クリアです。逆に言うと、どんなに設定をいじっても endpoint が出てこないなら、プロジェクト種別かリージョンのどちらかがミスマッチしていると考えてください。

原因2：リージョン未対応（EU リージョン制約を含む）

Agents エンドポイントがまだ提供されていないリージョン

次のような症状がある場合は、リージョン未対応である可能性が高いです。

Project details に Project endpoint が出ない
Agents タブがエラーで開けない
自分で URL を組み立てて SDK を叩くと InvalidUrlClientError になる

実際、Microsoft Q&A では Sweden Central に Foundry プロジェクトを作成したケースで、エンドポイントが提供されておらず、手動 URL でも InvalidUrlClientError になる事例が報告されています。

同スレッドでは、East US / West Europe / Southeast Asia など一部リージョンでは Agents サービスとエンドポイントが利用可能であることも案内されていました。

EU 制約がある場合の現実的な方針

「インフラは EU 内に限定したい」という要件がある場合、次のような順番で検討するのが現実的です。

EU 内の候補リージョン（例：West Europe、North Europe、Norway East など）をリストアップ
各リージョンで スタンドアロンの Foundry プロジェクトを仮作成し、
- Project details に Project endpoint が表示されるか
- Agents タブが正常に開くか（エージェント一覧が表示できるか）
を確認
両方満たしたリージョンのみを「候補」として残し、本番プロジェクトを作成する

先の Q&A では、West Europe では Agents タブでエラーが出てしまい、最終的に Norway East を選んだところ、Project connection string が表示され、Agents タブのエラーも解消したという報告がありました。

ただしリージョン対応状況はアップデートで変化するため、「2025年時点でこのリージョンが必ず使える」とは言い切れません。実務的には、

Project endpoint が実際に表示されるか
Agents タブがエラーなく開くか

の 2 点を、リージョンが対応しているかどうかを見極める簡易テストとして使うのがもっとも安全です。

InvalidUrlClientError が出るときのチェックポイント

もしリージョンが対応しているはずなのに、SDK 側で InvalidUrlClientError が出る場合は、次を確認してみてください。

エンドポイント URL を手入力ではなくポータルからコピーしているか
URL が次のようなパターンに沿っているか
- https://<project-name>.<region>.inference.ai.azure.com
https://<project-name>.studio.azure.ai など、ポータル用の URL を誤って指定していないか
プロキシや企業の FW によって *.inference.ai.azure.com へのアクセスがブロックされていないか

特に、「見た目がそれっぽい URL を自力で組み立てて使う」のは危険です。必ずポータルが表示している Project endpoint を、そのままコピーして使うようにしましょう。

新 SDK（AIClient / AgentsClient）での正しい初期化パターン

次に、エンドポイントが無事に見つかったあとにどう初期化するかを整理します。

前提：Microsoft Entra ID（Azure AD）での認証

Project endpoint を利用する場合、Microsoft Entra ID（旧 Azure AD）での認証が前提になります。公式ドキュメントでも、DefaultAzureCredential を使うことと、Azure AI プロジェクトに対して適切な RBAC ロール（Azure AI Developer など）を割り当てる必要があることが明記されています。

最低限必要になるのは次のような設定です。

Entra ID にアプリ登録（クライアント ID / テナント ID）
アプリまたはユーザーに
- Azure AI Developer
- またはそれ以上の権限（Contributor など）
をプロジェクトリソースに対して付与
ローカル開発環境や Function Apps などから DefaultAzureCredential でトークンが取得できる状態にする

Q&A でも、「プロジェクトのエンドポイントを使うには、アプリケーション側で Microsoft Entra ID を構成する必要がある」というコメントが紹介されており、キー認証だけでは動かない点に注意が必要です。

同期コードの最小例：with 文でクライアントを閉じる

Unclosed client session を避けるためにも、with 文を使うパターンが推奨です。

from azure.ai.agents import AgentsClient  # バージョンにより AIClient の場合あり
from azure.identity import DefaultAzureCredential

endpoint = "https://&lt;project-name&gt;.&lt;region&gt;.inference.ai.azure.com"

# with ブロックでセッションを自動クローズ
with AgentsClient(endpoint=endpoint, credential=DefaultAzureCredential()) as client:
    # 例：エージェント作成
    agent = client.create_agent(
        model="gpt-4o-mini",  # 後述のモデル名の項を参照
        name="sample-agent",
        instructions="You are a helpful assistant.",
    )
    thread = client.create_thread()
    client.create_message(
        thread_id=thread.id,
        role="user",
        content="Hello from Azure AI Agents SDK",
    )
    run = client.create_and_process_run(
        thread_id=thread.id,
        agent_id=agent.id,
    )
    # 結果の取得など...

バージョンによっては client.agents.create(...) や client.threads.create() のようなネスト構造になる場合もありますが、「Project endpoint + DefaultAzureCredential + with で閉じる」というパターンは同じです。

非同期コードの例：Unclosed client session を完全に防ぐ

非同期クライアントでは、クライアントを閉じ忘れると Unclosed client session が出やすくなります。次のように async with を使えば、確実にセッションをクローズできます。

import asyncio
import os

from azure.ai.agents.aio import AgentsClient
from azure.identity import DefaultAzureCredential

async def main() -&gt; None:
    endpoint = os.environ["PROJECT_ENDPOINT"]

    async with AgentsClient(endpoint=endpoint,
                             credential=DefaultAzureCredential()) as client:
        agent = await client.create_agent(
            model="gpt-4o-mini",
            name="async-agent",
            instructions="You are an async agent.",
        )
        thread = await client.create_thread()
        await client.create_message(
            thread_id=thread.id,
            role="user",
            content="Hi from async client",
        )
        run = await client.create_and_process_run(
            thread_id=thread.id,
            agent_id=agent.id,
        )
        # 結果処理...

if __name__ == "__main__":
    asyncio.run(main())

もし既存コードで client = AgentsClient(...) を作成したまま client.close() を呼んでいない場合は、with / async with に書き換えるだけで Unclosed client session はほぼ解消できます。

invalid_engine_error: Failed to resolve model info の原因と対処

エラーメッセージの意味

Q&A の実例では、次のようなエラーが発生していました。

Run error: {'code': 'invalid_engine_error',
 'message': 'Failed to resolve model info for: gpt-4o-mini-mvp'}

invalid_engine_error 自体は、指定した model の情報が解決できない場合に返されるエラーです。主体となる原因は次の 2 つに絞られます。

そのリージョンで利用可能な正式なモデル名ではない
プロジェクトから参照できるデプロイ（Model deployment）が存在しない

Q&A のケースでは gpt-4o-mini-mvp という名称が使われていましたが、これは プレビュー専用の別名・内部的なエイリアスであり、すべてのリージョンで利用できるとは限りません。

原因1：リージョンで公開されていないモデル名を指定している

Agents の公式ドキュメントでは、エージェント作成時の model= には、そのプロジェクトが接続している Foundry / Azure OpenAI などのデプロイ名や リージョンで有効なモデル名を指定することが前提になっています。

例えば、

gpt-4o-mini
gpt-4.1-mini
gpt-4o

など、Azure ポータルの「Models + endpoints」画面やドキュメントに記載がある正式名称を指定する必要があります。「-mvp」「-preview」などのサフィックス付き名称は、特定の環境やリージョン限定でしか動かないことが多いため、エラーの原因になりやすいです。

原因2：プロジェクトに紐づくモデルデプロイがない

もう一つの典型的な原因は、プロジェクトから参照可能なモデルデプロイが存在しないことです。Agents のサンプルコードでも、

MODEL_DEPLOYMENT_NAME という環境変数
またはポータル上で設定したデプロイ名

を使うように記載されています。

つまり、

Azure AI Services / Foundry Models 側でモデルをデプロイする
Azure AI Foundry プロジェクトからそのデプロイを接続する
Agents 側では、そのデプロイ名を model= に指定する

という 3 段階が揃って初めて、model 名が正しく解決できます。

具体的な解決ステップ（3 ステップ）

invalid_engine_error を解消するための具体的なステップをまとめると、次のようになります。

Azure AI Foundry プロジェクトの 「Models + endpoints」 を開く
- 利用したいモデルがこの画面に一覧表示されているか
- そのモデルに対して、自分のプロジェクトから利用可能なデプロイが存在するか
一覧の中から、実際に利用可能な モデル名（あるいはデプロイ名）を控える
Agents SDK 側の model= に、その文字列をそのまま指定して再実行する

コード例は次のようになります。

# 悪い例（リージョンで未サポートの別名を指定）
agent = client.create_agent(
    model="gpt-4o-mini-mvp",  # invalid_engine_error の原因になり得る
    instructions="You are a helpful agent.",
)

# 良い例（Models + endpoints に表示されている正式なデプロイ名を指定）
agent = client.create_agent(
    model="gpt-4o-mini",  # 例：同リージョンで GA になっている正式名
    instructions="You are a helpful agent.",
)

EU 制約下でのモデル名の選び方

EU リージョンでは、US に比べて提供モデルが少し遅れてロールアウトする傾向があります。そのため、EU 内で動かしたい場合は、

プレビュー色の強いモデル名（-mvp, -preview 系）は避ける
ポータルの「Models + endpoints」で本当にそのリージョンに出ているモデルのみを対象にする
ドキュメントのリリースノートや Q&A で、そのリージョンでのサポート状況を確認する

といった慎重な選び方をするのがおすすめです。

旧 API からの移行チェックリスト

ここまでの内容を、「旧 API からの移行」という観点でまとめ直してみます。

チェック項目	旧 API（from_connection_string）	新 API（Project endpoint ベース）
接続情報	Project connection string	Project endpoint URL
クライアント初期化	`AIProjectClient.from_connection_string()`	`AgentsClient(endpoint=..., credential=...)`
認証方式	キー or AAD	Entra ID + RBAC（Azure AI Developer 等）
プロジェクト種別	Hub ベースでも動くケースがあった	Foundry ベース（Hub なしスタンドアロン）が前提
リージョン	比較的制約が緩かった	Agents エンドポイント対応リージョンのみ利用可能
代表的なエラー	接続文字列の形式エラーなど	`InvalidUrlClientError` / `invalid_engine_error` / 認可エラーなど

移行の際は、次の 5 点を順番に潰していくとスムーズです。

Foundry ベースのスタンドアロンプロジェクトを作れているか
そのリージョンで Project endpoint が表示され、Agents タブが正常表示か
Project endpoint を endpoint= に渡し、Entra ID（DefaultAzureCredential）で認証できているか
モデルは Models + endpoints で見える正式な名称を指定しているか
クライアントは with / async with で確実にクローズしているか

トラブルシューティング早見表

最後に、本記事で触れた内容を即座に引けるよう、トラブルシューティングの早見表を置いておきます。

症状	主な原因	チェックポイント	解決策
Project endpoint が Project details に表示されない	Hub ベースプロジェクト / リージョン未対応	Project details に connection string だけ出ていないか Agents タブはエラーになっていないか	Hub なしの Foundry ベースプロジェクトを、対応リージョンで作り直す
`InvalidUrlClientError` が出る	URL 形式の誤り / リージョン非対応	URL を手入力していないか `*.inference.ai.azure.com` の形式か該当リージョンで Agents がサポートされているか	ポータルに表示された Project endpoint をそのままコピーし、対応リージョンでプロジェクトを作成する
`invalid_engine_error` / `Failed to resolve model info for ...`	モデル名がリージョン・プロジェクトで有効でない	Models + endpoints にそのモデル / デプロイが存在するかプレビュー用の別名を使っていないか	同一リージョン・同一プロジェクトから参照できる正式なモデル名・デプロイ名に差し替える
`Unclosed client session` が表示される	クライアントのクローズ漏れ	`with AgentsClient(...)` を使っているか非同期なら `async with` で囲んでいるか	`with` / `async with` でクライアント生成・利用・クローズを一括管理する
認可エラー（AuthorizationFailed など）	Entra ID のロール・スコープ設定不足	アプリまたはユーザーに Azure AI Developer / Contributor が付いているか正しいサブスクリプションをデフォルトにしているか	Azure ポータルの Access Control (IAM) から、AI プロジェクトリソースに適切なロールを割り当てる

実運用でのベストプラクティス

プロジェクトを作り直す前提で小さく検証する

リージョン・プロジェクト種別・モデル名など、Agents SDK 周りはまだ変化が激しい部分です。最初から本番規模のプロジェクトを作り込むよりも、

小さなテストプロジェクト（EU で 2〜3 個）を先に作る
Project endpoint と Agents タブの動作確認を行う
使いたいモデルがそのリージョンで利用可能かを確認する

という「検証→本番」の二段構えで進める方が、結果的に工数が少なく済みます。

環境変数で PROJECT_ENDPOINT と MODEL 名を一元管理する

ローカル / Function Apps / コンテナなど複数環境で動かす場合は、

PROJECT_ENDPOINT
MODEL_DEPLOYMENT_NAME

といった環境変数に統一しておくと、後でリージョンやモデルを切り替えるときもコード修正が最小限で済みます。

RBAC（ロール）設定は「最初に」確認する

invalid_engine_error や InvalidUrlClientError を追いかけていると、つい見落としがちなのが RBAC 設定です。Entra ID + DefaultAzureCredential を使う以上、

アプリ登録 → マネージド ID → Azure AI プロジェクトへのロール割り当て

の流れを最初にきちんと押さえておくと、後で謎の認可エラーに悩まされる時間を大きく減らせます。

まとめ

Azure AI Agents SDK で PROJECT_ENDPOINT_STRING が見つからない・使えない問題は、実際には次の 4 点に集約されます。

Foundry ベースのスタンドアロンプロジェクトかどうか
選択した リージョンが Agents エンドポイントに対応しているか
Microsoft Entra ID（AAD）での認証と RBACが正しく構成されているか
リージョンで利用可能な正式なモデル名（またはデプロイ名）を指定しているか

この 4 つを順番に確認すれば、

Project endpoint がそもそも表示されない
InvalidUrlClientError
invalid_engine_error
Unclosed client session

といったよくあるハマりポイントは、落ち着いて一つずつ潰していけます。特に EU 制約があるケースでは、「Project endpoint が出るリージョン」を見つけることがスタートラインになるので、まずは小さな検証プロジェクトを複数リージョンに用意し、挙動を確かめるところから始めてみてください。

この記事を書いた人

佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。