Important
この記事で "(プレビュー)" と付記されている項目は、現在、パブリック プレビュー段階です。 このプレビューはサービス レベル アグリーメントなしで提供されており、運用環境ではお勧めしません。 特定の機能がサポートされていないか、機能が制限されている可能性があります。 詳細については、「 Microsoft Azure プレビューの追加使用条件」を参照してください。
azd ai コマンドは、azd プロジェクト内 (一般的なチーム ワークフロー) とスタンドアロン (アドホック作業、1 回限りのスクリプト、またはアンカーするazure.yamlがないオートメーションからの呼び出し) の 2 つのコンテキストで実行されます。 どちらのモードも、同じ Microsoft Foundry リソースを対象とします。 これらは、CLI が通信する Foundry プロジェクトを決定する方法でのみ異なります。 この記事では、解決順序とスタンドアロン コンテキストを設定する方法について説明します。
前提条件
- Azure Developer CLI Foundry 拡張機能がインストールされています。
- 認証されたAzure セッション (
azd auth login)。 - スタンドアロンで使用するための既存の Foundry プロジェクト エンドポイント。
各コンテキストを使用するタイミング
| Context | 見た目 | 次の場合に使用します。 |
|---|---|---|
azd プロジェクト内 |
azd ai ...は、azure.yamlとアクティブなazd環境を含むディレクトリから実行します。 |
追跡対象のプロジェクトの一部としてエージェントをビルドまたは運用し、ターゲットとする Foundry プロジェクトを環境で管理する必要があります。 |
| スタンドアロン | 他のディレクトリから azd ai ... を実行します。 |
既存の Foundry プロジェクトに対してアドホック作業を行うか、 azd プロジェクトを所有していないオートメーションから 1 回限りの操作をスクリプト化します。 |
リソース コマンド (azd ai connection、 azd ai toolbox、 azd ai skill、 azd ai routine) は 1 つの Foundry プロジェクトで動作するため、これらのコンテキストの 1 つから解決されたプロジェクト エンドポイントを実行する必要があります。
azd ai agent コマンド (run、invoke、optimizeなど) はスタンドアロンではありません。
azure.yaml と環境の解決には、azd プロジェクトが必要です。
--agent-endpointのazd ai agent invokeを使用して、ディスク上のazd プロジェクトなしでデプロイされたエージェントを呼び出します。
エンドポイント解決のしくみ
Foundry プロジェクトを対象とするすべてのコマンドについて、CLI はこの順序でエンドポイントを解決します。 値を返す最初のソースが優先され、以降のソースは参照されません。
- コマンドの
-pフラグまたは--project-endpointフラグ。 コンテキストに関係なく、常に優先されます。 -
azdプロジェクト ディレクトリ内にいる場合の、アクティブなazd環境 - グローバル設定（
~/.azd/config.jsonのextensions.ai-agents.context.endpointの下）。 これは、azd ai project setが書き込むものです。 - 現在のシェルの
FOUNDRY_PROJECT_ENDPOINT環境変数。 - エラー。 CLI は、
azd ai project setを実行するか、--project-endpoint渡す構造化された提案で終了します。
エンドポイントは、CLI に必要な唯一のものです。 呼び出し時にエンドポイントからAzure Resource Managerリソース ID (サブスクリプション、リソース グループ、アカウント、およびプロジェクト) が解決されるため、コマンドは、環境またはグローバル構成からエンドポイントを取得した場合でも同じように動作します。
スタンドアロン コンテキストを設定する
azd ai project set コマンドは、アクティブな Foundry プロジェクト エンドポイントをグローバル azd構成に書き込みます。そのため、以降のコマンドはどこからでも実行されるため、--project-endpointを省略できます。 このコマンドは、位置引数としてエンドポイントを受け取ります。
azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project
エンドポイントを渡すと、コマンドは完全に非対話型です。 スクリプトと CI に --no-prompt を追加し、値が欠落している場合や未解決の場合に、処理をブロックするのではなく早期に失敗させるようにします。
azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project --no-prompt
Note
エンドポイントのみが正規です。 リソース コマンドは、呼び出し時にエンドポイントからサブスクリプション、リソース グループ、アカウント、およびプロジェクトを再派生させます。
スタンドアロン コンテキストをクリアする
azd ai project unset
このコマンドは、contextから~/.azd/config.json ブロック全体を削除します。
azd 環境値には一切影響しません。
アクティブなコンテキストを検査する
azd ai project show コマンドは、完全な解決チェーンを示し、アクティブなエンドポイントを提供したソースを報告します。 これを使用して、実行する前に次のコマンドのターゲットを確認します。
azd ai project show
エンドポイントがグローバル構成からの場合の出力例:
Project endpoint: https://my-project.services.ai.azure.com/api/projects/my-project
Source: global config (~/.azd/config.json)
Tenant: contoso.onmicrosoft.com
Subscription: Contoso Dev (00000000-0000-0000-0000-000000000000)
Foundry project: my-project
azd プロジェクト内では、Source行は代わりにazd env <env-name>読み取り、表示される値はグローバル構成ではなく、環境の.env ファイルから取得されます。
ストレージの場所
スタンドアロン コンテキストは、extensions.ai-agentsの ~/.azd/config.json 名前空間の下に存在します。
{
"extensions": {
"ai-agents": {
"context": {
"endpoint": "https://my-project.services.ai.azure.com/api/projects/my-project",
"subscription": "00000000-0000-0000-0000-000000000000",
"tenant": "contoso.onmicrosoft.com",
"foundryProject": "my-project",
"setAt": "2026-01-15T10:23:00Z"
}
}
}
}
endpointのみが正規です。 他のフィールドは、 azd ai project show 読み取り可能にするために存在します。 CLI は、ターゲットを解決するときにそれらを読み取ることはありません。 ファイルは手動で編集できますが、 azd ai project set と azd ai project unset を使用してファイルを管理できます。
azd プロジェクト内の優先順位
azd プロジェクト内では、アクティブな環境のプロジェクト エンドポイントが常にグローバル コンテキストよりも優先されます。 プロジェクト内から azd ai project set を実行してもグローバル構成は更新されますが、CLI では、そのディレクトリから実行されるコマンドに対して環境が引き続き優先されることを示す 1 行の警告が出力されます。
この動作は意図的です。 Projectレベルの環境値はチームのワークフローの一部ですが、グローバル コンテキストはマシンごとの優先設定です。 プロジェクト内から 1 つのコマンドの環境をオーバーライドするには、グローバル構成に依存するのではなく、 --project-endpointを渡すか、シェルで FOUNDRY_PROJECT_ENDPOINT を設定します。