デフォルトでは、Agent 365 CLIはMicrosoftの商用クラウドをターゲットにしています。
https://login.microsoftonline.com で認証し、https://graph.microsoft.com で Microsoft Graph を呼び出し、https://agent365.svc.cloud.microsoft で Agent 365 サービスを呼び出します。 Microsoft 365の米国政府クラウドは、Government Community Cloud(GCC)、GCC High、そして国防総省(DoD)です。 これらのクラウドのいずれかでCLIを使用するには、クラウド環境を選択し、そのクラウドのエンドポイントを設定してください。
この記事では、CLI がクラウド設定をどのように解決するか、ご利用の a365.config.json ファイルや環境変数を使用してそれらを構成する方法について説明します。
Note
クラウド認識型エンドポイント解決は、Agent 365 CLIの最新バージョンで利用可能です。 米国政府向けクラウドを設定する前に、最新バージョンにアップデートしてください。 更新手順については「 エージェント365 CLIの更新」を参照してください。
Important
設定可能なエンドポイントは、すべてのAgent 365サービスや機能がすべてのクラウドで利用可能であることを保証するわけではありません。 商用クラウドで利用可能なサービスや機能の中には、GCC、GCC High、DoDでまだ利用できないものもあります。 セットアップを実行する前に、クラウドのサービスの利用可能性を確認してください。 GCCにおけるAgent 365の機能利用可能性については、Microsoft Agent 365サービス説明をご覧ください。
サポートされているクラウド環境
環境名は、CLI に対してどのクラウドを対象とするかを指定します。 すべての米国政府クラウドに対して明示的に設定してください。
| 雲 |
environment 値 |
環境変数のサフィックス(<ENV>) |
|---|---|---|
| 商業 (デフォルト) | prod |
PROD |
| GCC | gcc |
GCC |
| GCC High | gcc-high |
GCC_HIGH |
| DoD | dod |
DOD |
環境名は2つの動作を制御します:
- CLIは環境名に一致する環境スコープ変数を読み取ります。 例えば、
gcc-highではCLIがA365_GRAPH_BASE_URL_GCC_HIGHを読み込みます。 - セットアップは、選択したクラウドのAgent 365 Observabilityリソースに対して権限を付与します。 詳細については、可観測性の権限をご覧ください。
環境名自体は認証ホスト、Microsoft GraphのベースURL、またはAgent 365のサービスエンドポイント自体を変えません。 これらのエンドポイントは、「GCCの設定」および「GCC High または DoD の設定」で説明されているとおりにクラウド向けに設定してください。
Important
Azure CLI のクラウド名 AzureUSGovernment を環境として使用しないでください。 その名前はGCC、GCC High、DoDを区別しないため、CLIはクラウド固有の設定が必要なときに設定エラーを報告します。 代わりに gcc、 gcc-high、または dod を使いましょう。
CLIがクラウド設定を解決する方法
CLIはまず環境名を解決し、その後各エンドポイントを解決するためにそれを使用します。
環境名
CLIは最初に見つけた値を使います:
-
a365.config.jsonのenvironmentフィールド。 -
A365_ENVIRONMENT環境変数。 -
a365.config.jsonファイルなしで実行されるセットアップ コマンドの場合、アクティブな Azure CLI クラウド (az cloud show) の名前。 Azure CLI のクラウドがAzureUSGovernmentの場合、セットアップが停止し、A365_ENVIRONMENTをgcc、gcc-high、またはdodに設定するよう求められます。 - 既定値は
prodです。
セットアップが a365.config.json ファイルを生成すると、解決された environment、authorityHost、graphBaseUrl の値を記録し、後のコマンドは同じクラウドを対象にします。
develop list-availableコマンドはa365.config.jsonを読み取れません。 このコマンドは常に A365_ENVIRONMENT から環境変数を読み込むため、米国政府のクラウド環境でこのコマンドを使用する際は、その変数を設定します。
Authority ホストと Microsoft Graph のベース URL
各エンドポイントに対して、CLIは最初に見つけた値を使います:
- 環境スコープ付き環境変数(
A365_AUTHORITY_HOST_<ENV>またはA365_GRAPH_BASE_URL_<ENV>)。 -
a365.config.json内の一致するフィールド（authorityHostまたはgraphBaseUrl） - 商用クラウドのデフォルト(
https://login.microsoftonline.comまたはhttps://graph.microsoft.com)。
CLIは A365_GRAPH_BASE_URLのような接尾辞のない変数からこれらの設定を読み取りません。
解決された各値は、HTTPS オリジンでなければなりません。つまり、スキーム、ホスト、オプションのポートのみで構成される必要があります。 パス、クエリ文字列、フラグメント、ユーザー情報は含めないでください。 例えば、CLIは https://login.microsoftonline.us を受け入れますが、 https://login.microsoftonline.us/commonは拒否します。 値が検証に失敗すると、CLIはエラーで停止します。
CLI は、セットアップ、同意、認証、Microsoft Entra ID クエリ、クリーンアップ、create-instance の各フローにおいて、解決された権限ホストと Graph ベース URL の整合性を維持します。 各オーソリティホストごとにトークンを個別にキャッシュするため、クラウドを切り替えても他のクラウドのトークンを再利用しません。
Important
同じクラウドに対して、authority host と Graph ベース URL をペアリングします。 一方をオーバーライドしたら、もう一方も上書きして認証とGraphのデータプレーンコールが同じ環境をターゲットにするようにします。
Agent 365 サービスエンドポイント
CLIはAgent 365のサービスを呼び出し、モデルコンテキストプロトコル(MCP)サーバーの発見、MCPサーバーの管理、エージェントのメッセージングエンドポイントの登録を行います。 これらのサービスエンドポイントは環境変数のみで設定してください。 これらの端点には a365.config.json フィールドはありません。
| Variable | Description |
|---|---|
A365_DISCOVER_ENDPOINT_<ENV> |
Agent 365 Toolsの検出エンドポイントの完全なURLです。 CLIはこのURLを呼び出してMCPサーバーを検出します。 また、MCPサーバー管理やメッセージングエンドポイントの登録を含む関連するAgent 365サービスコールにもURLの発信元を使用しています。 既定値は https://agent365.svc.cloud.microsoft/agents/v2/discoverMCPServers です。 |
A365_CREATE_ENDPOINT_<ENV> |
CLIがエージェントのメッセージングエンドポイントを登録するために呼び出す完全なURL。 この値は A365_DISCOVER_ENDPOINT_<ENV> のオリジンよりも優先されます。 |
A365_DELETE_ENDPOINT_<ENV> |
CLIがエージェントのメッセージングエンドポイント登録を解除するために呼び出す完全なURL。 この値は、A365_DISCOVER_ENDPOINT_<ENV> のオリジンよりも優先されます。 |
各値は HTTPS の絶対 URL でなければなりません。 エンドポイントがパスを必要とする場合はパスを含めますが、クエリ文字列、フラグメント、ユーザー情報は含めないでください。
Important
環境名を設定するだけでは、Agent 365 サービスの呼び出しが商用サービスから切り替わることはありません。
A365_DISCOVER_ENDPOINT_<ENV> を設定しない場合、CLIは商用のAgent 365サービスを呼び出します。たとえ米国政府のクラウド内でも同じです。
GCCの設定
GCCは商用オーソリティホストとMicrosoft GraphのベースURLを使用しているため、それらを上書きする必要はありません。 詳細については、「 Microsoft Graph の国内クラウド展開」を参照してください。 環境を gcc に設定し、エージェント365のサービスコールをGCCサービスに向けます。
a365.config.jsonで、environmentフィールドを設定します:
{
"tenantId": "YOUR_TENANT_ID",
"environment": "gcc",
"messagingEndpoint": "https://your-app.azurewebsites.net/api/messages",
"deploymentProjectPath": "."
}
次に環境変数を設定します。 設定 A365_ENVIRONMENT は、 a365.config.jsonを読み取らないコマンド、例えば develop list-availableも含みます。 Bash で、次のコマンドを実行してください:
export A365_ENVIRONMENT="gcc"
export A365_DISCOVER_ENDPOINT_GCC="https://gcc.agent365.svc.cloud.microsoft/agents/v2/discoverMCPServers"
Windows PowerShell では、以下のコマンドを実行してください：
$env:A365_ENVIRONMENT = "gcc"
$env:A365_DISCOVER_ENDPOINT_GCC = "https://gcc.agent365.svc.cloud.microsoft/agents/v2/discoverMCPServers"
GCC HighまたはDoDの設定
GCC HighとDoDは独自のオーソリティホストとMicrosoft GraphのベースURLを使用しています:
| 雲 |
environment 値 |
オーソリティホスト(authorityHost) |
Microsoft Graph 基本URL(graphBaseUrl) |
|---|---|---|---|
| GCC High | gcc-high |
https://login.microsoftonline.us |
https://graph.microsoft.us |
| DoD | dod |
https://login.microsoftonline.us |
https://dod-graph.microsoft.us |
これらの値は以下の記事から得られています。 現在のエンドポイントを確認するには、以下を確認してください:
GCC HighやDoDのテナントはAzure Governmentを使用しています。 Agent 365 CLIは、テナントの検出など一部の操作でAzure CLIを使用しますので、Azure GovernmentでAzure CLIにサインインしてください。 手順については、Connect to Azure Government with Azure CLI をご覧ください。 Azure GovernmentのAzureサービスは、グローバルなAzureとは異なるドメイン名を使用しています。 例えば、エージェントをAzure App Serviceでホストしている場合、メッセージングエンドポイントはAzure Governmentドメインを使用します。 エンドポイント マッピングについては、「Azure Government とグローバル Azure の比較」をご覧ください。
これらの値を a365.config.json または環境変数で設定してください。 環境スコープ変数はマッチングする a365.config.json フィールドよりも優先されるため、チェックイン済みの設定をマシンごとまたはパイプラインごとに上書きするために使用します。
a365.config.json で構成する
以下の例はGCC Highを対象としています。
{
"tenantId": "YOUR_TENANT_ID",
"environment": "gcc-high",
"authorityHost": "https://login.microsoftonline.us",
"graphBaseUrl": "https://graph.microsoft.us",
"messagingEndpoint": "https://your-app.azurewebsites.us/api/messages",
"deploymentProjectPath": "."
}
環境変数を構成する
以下のBashの例はGCC Highを対象としています:
export A365_ENVIRONMENT="gcc-high"
export A365_AUTHORITY_HOST_GCC_HIGH="https://login.microsoftonline.us"
export A365_GRAPH_BASE_URL_GCC_HIGH="https://graph.microsoft.us"
以下のWindows PowerShellの例はGCC Highを対象としています:
$env:A365_ENVIRONMENT = "gcc-high"
$env:A365_AUTHORITY_HOST_GCC_HIGH = "https://login.microsoftonline.us"
$env:A365_GRAPH_BASE_URL_GCC_HIGH = "https://graph.microsoft.us"
DoDの場合は環境をdodに設定し、DODのサフィックスを使い、DoD Microsoft Graph のベース URL を使用します。
ご利用のクラウドで Agent 365 のサービスが利用可能な場合は、A365_DISCOVER_ENDPOINT_<ENV> にもそのクラウドのディスカバリー エンドポイントを設定してください。 そうでなければ、CLIは商用のAgent 365サービスを呼び出します。 詳細については、 Agent 365サービスエンドポイントをご覧ください。
構成の参照
このセクションでは、クラウド設定を制御する a365.config.json プロパティと環境変数を一覧にしています。
a365.config.json プロパティ
| 財産 | Description | 必須 | Default |
|---|---|---|---|
environment |
クラウド環境の名前。
prod、gcc、gcc-high、またはdodを使ってください。 この値によって、CLI が読み込む環境スコープの変数と、Observability リソースの設定で使用する変数が決まります。 |
No | prod |
authorityHost |
選択したクラウドの OAuth 認証ホスト。 値はHTTPSオリジンでなければなりません。 | No | https://login.microsoftonline.com |
graphBaseUrl |
選択したクラウドのMicrosoft Graphの基本URLです。 値はHTTPSオリジンでなければなりません。 | No | https://graph.microsoft.com |
環境変数
| Variable | Description |
|---|---|
A365_ENVIRONMENT |
クラウド環境の名前。 CLIは a365.config.json が environmentを設定しない場合や、 a365.config.jsonを読み取らないコマンドに対してこの値を使います。 既定値は prod です。 |
A365_AUTHORITY_HOST_<ENV> |
OAuth 認証ホスト。 この値はauthorityHost内のa365.config.jsonよりも優先されます。 |
A365_GRAPH_BASE_URL_<ENV> |
Microsoft Graphの基本URLです。 この値は、a365.config.json における graphBaseUrl よりも優先されます。 |
A365_DISCOVER_ENDPOINT_<ENV> |
Agent 365 Toolsのディスカバリーエンドポイント。 CLIはまた、関連するAgent 365サービスコールにも発信元を利用します。 |
A365_CREATE_ENDPOINT_<ENV> |
メッセージングエンドポイントの登録URLです。 |
A365_DELETE_ENDPOINT_<ENV> |
メッセージングエンドポイントの削除用 URL |
A365_MCP_APP_ID_<ENV> |
CLIがツールサーバー用のトークンを取得するために使用するエージェント365 ToolsリソースアプリケーションID。 ほとんどの開発者はこの変数を設定する必要はありません。 |
環境サフィックスの由来
CLI は、環境スコープの各変数について、その環境名から <ENV> というサフィックスを導出します。 CLIは名前の前後の空白を削除し、文字や数字以外の文字をアンダースコア(_)で置き換え、大文字に変換します。 空の名前は PROD になります。
| 環境名 | 正規化接尾辞 | 変数の例 |
|---|---|---|
gcc |
GCC |
A365_DISCOVER_ENDPOINT_GCC |
gcc-high |
GCC_HIGH |
A365_GRAPH_BASE_URL_GCC_HIGH |
dod |
DOD |
A365_AUTHORITY_HOST_DOD |
環境名と変数の接尾辞は同じ正規化された値になる必要があります。 例えば、A365_ENVIRONMENT=gcc-high は A365_AUTHORITY_HOST_GCC_HIGH と対になります。
オブザーバビリティの権限
セットアップ中に、CLI は、選択されたクラウドの「Agent 365 Observability」リソースに対して、エージェント ブループリントに Agent365.Observability.OtelWrite のアクセス許可を付与します。
| 雲 | オブザーバビリティリソースアプリケーションID |
|---|---|
| 商用 | 9b975845-388f-4429-889e-eab1ef63949c |
| GCC | 2c672ad5-b104-44ed-8069-bb68dd138546 |
| GCC High | 009c6bd0-82e4-4466-95b3-4c996521f3d7 |
| DoD | a9e04047-c6a7-430b-a7ae-faf8f8eed1b7 |
以前のCLIのバージョンでは、常に商用のObservabilityリソースに対して許可が付与されていました。 以前のバージョンで米国政府のクラウドにエージェントを設定した場合は、クラウドの環境を設定し、a365 setup all を再実行して、CLI がクラウドの Observability リソースに対してアクセス許可を付与するようにしてください。
構成を確認する
クラウド設定後は読み取り専用コマンドを実行し、CLIが期待されるエンドポイントを使用しているか確認してください。 例えば次が挙げられます。
-
develop list-availableコマンドを実行します。 出力は環境とCLIが呼び出すディスカバリーエンドポイントURLを示します。 -
develop get-tokenコマンドを使ってトークンを取得します。
クラウド設定のトラブルシューティング
以下の表は、一般的なクラウド設定エラーとその解決方法を示しています。
| 症状: | 原因 | Resolution |
|---|---|---|
Authority host must be an HTTPS origin without a path, query, fragment, or user info. (またはGraphベースのURLでも同じエラーが出ます) |
認証機関ホホストまたはグラフのベース URL には、パス、クエリ文字列、またはフラグメントが含まれています。 | HTTPS のみのオリジンを使用します。 たとえば、https://login.microsoftonline.usではなくhttps://login.microsoftonline.us/common/oauth2/v2.0/authorizeを使用します。 |
AzureUSGovernment または Azure CLI は、GCC Moderate (GCC)、GCC High、および DoD を区別していないというエラーが表示されます。 |
環境は AzureUSGovernment です。あるいは、Azure CLI からそのクラウドが検出されました。 |
環境を gcc、 gcc-high、または dodに設定してください。 |
| CLIは米国政府のクラウド上で商用サービスであるAgent 365を呼び出します。 |
A365_DISCOVER_ENDPOINT_<ENV> セットされていないか、その接尾辞が環境名と合わない。 |
ご利用の環境に応じた接尾辞を付けて A365_DISCOVER_ENDPOINT_<ENV> を設定してください。 |
| Setupは商用Observabilityリソースに対して権限を付与します。 | 環境が設定されていないため、CLIは prodを使用します。 |
クラウド環境を設定して、再度セットアップを実行してください。 |
PowerShell fallback is available only for commercial Graph and authority endpoints. |
Microsoft Graph へのサインインに失敗し、カスタムエンドポイントを使うとCLIがPowerShellConnect-MgGraphにフォールバックできません。 |
サインイン失敗を解決してください。 たとえば、クライアント アプリをクラウドに登録済みであること、クラウドのテナント内のアカウントでサインインしていることを確認してください。 |