Azure Developer CLI を使用してホステッド エージェント プロジェクトを初期化する

Important

この記事でプレビューとしてマークされているアイテムは、現在プレビュー段階です。 このプレビューはサービス レベル アグリーメント(SLA)なしで提供されており、Microsoft はこれを運用ワークロードでの使用に推奨していません。 特定の機能がサポートされていないか、機能が制限されている可能性があります。 詳細については、「 Microsoft Azure プレビューの追加使用条件」を参照してください。

azd ai agent init を使用して、Microsoft Foundry に AI エージェントをビルド、テスト、デプロイするために必要なファイルが含まれたホステッド エージェント プロジェクトを作成します。 この記事では、開始点を選択し、テンプレート、独自のコード、または既存の Foundry プロジェクトに対してプロジェクトを初期化します。

GitHub Copilotなどのコーディング エージェントを使用する場合、Microsoft Foundry スキルは、開始テンプレートの選択、プロジェクトのスキャフォールディング、生成されたazd構成の解釈に役立ちます。

前提条件

  • Azure Developer CLI Foundry 拡張機能がインストールされています。
  • 認証されたAzure セッション (azd auth login)。
  • Azure サブスクリプションに対する共同作成者アクセス。

開始点を選択する

プロジェクトを開始するには、3 つの方法があります。 状況に一致するパスを選択します。

Consideration テンプレートから開始 Bring Your Own Code 既存のプロジェクトを接続する
最適な用途 新しいエージェント、ツールを学習します。 Foundry でホストする既存のエージェント コード。 Foundry プロジェクトで既に稼働しているエージェント。
命令 azd ai agent init を空のディレクトリに格納します。 azd ai agent init 既存のコードを含むディレクトリに格納されます。 azd ai agent initをクリックし、既存のプロジェクトを選択します。
受け取るもの 完全にスキャフォールドされたプロジェクト: 単一の azure.yaml、src/<agent-name>/ 配下のエージェントソース、およびコンテナー展開用の Dockerfile。 インフラストラクチャは既定では Bicep を使用せず、後からエクスポートできます。 生成された azure.yaml のサービスエントリ、コンテナー展開用の、コードをラップした Dockerfile。 インフラストラクチャは既定では Bicep を使用せず、後からエクスポートできます。 既存の Foundry プロジェクトに接続された azure.yaml。 インフラストラクチャは既定では Bicep を使用せず、後からエクスポートできます。
コードの変更 なし。 実行準備完了。 プロトコル アダプターが必要な場合があります。 なし。

テンプレートから初期化する

空のディレクトリで対話型ウィザードを実行し、[ テンプレートから新規に開始] を選択します。

azd ai agent init

ウィザードでは、次の選択肢について説明します。

プロンプト Description
エージェント テンプレート フレームワークと言語 (Pythonまたは.NET) 別に整理されたテンプレートから選択します。
Azure サブスクリプション Foundry プロジェクトの検索または作成に使用されるサブスクリプション。
鋳造プロジェクト 既存のプロジェクトを選択するか、新しいプロジェクトを作成します。 作成する場合は、リージョンも選択します。
モデルデプロイ テンプレートのモデル設定を確認してください。 テンプレートを既存のプロジェクトに導入する場合は、 --model-deployment <name> を使用してデプロイを明示的に再利用します。

エージェント名はテンプレートから取得されます。 CLI は、azdという名前の<directory>-dev環境を作成し、選択した Foundry プロジェクトの詳細を使用して構成します。 テンプレートは、azure.yamlでエージェントのソースとデプロイ設定を宣言します。コンテナー テンプレートには、Dockerfileも含まれます。

azure.yaml URL から初期化する

特定のエージェント サンプルがある場合は、--templateをそのサンプルのazure.yamlに指定してください。 CLI では、そのファイルがプロジェクト マニフェストとして採用され、参照されるエージェント ソースがダウンロードされます。

azd ai agent init --template https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/azure.yaml --src .

テンプレート導入の場合、 --src は、エージェントのソースだけでなく、プロジェクト全体の宛先を選択します。 上記のコマンドは、現在のディレクトリに azure.yaml を書き込み、テンプレートの相対ソース パスを保持します。 --src を指定しない場合、初期化処理により、テンプレート名と同じ名前のディレクトリが作成されることがあります。 生成されたazd envを含むディレクトリから、後続のazure.yaml、プロビジョニング、およびデプロイ コマンドを実行します。

テンプレートは、GitHub トークンやサービス エンドポイントなどの外部入力を参照できます。 初期化前にこれらの値を準備します。CLI は未解決の環境変数の入力を求め、選択した azd 環境に保存します。 資格情報や .azure ディレクトリはコミットしないでください。

Note

テンプレートの導入には、全面的な azure.yamlが必要です。 既存のプロジェクトに直接エージェント定義をアタッチするには、 agent add --fileを使用します。 パラメーター化された AgentManifest ラッパーは、どちらのパスでもサポートされていません。

azure.yaml プロジェクトのドキュメントには --template (-t) を使用してください。 --manifest (-m) iは非推奨の別名であり、以前のマニフェスト形式には対応していません。 スタンドアロン エージェント定義、 AgentManifest ラッパー、および azureml:// マニフェスト ポインターは、このワークフローでは受け入れられません。

モデルを指定する

初期化時にモデルを選択します。

azd ai agent init --model gpt-4.1

または、Foundry プロジェクトで既存のモデル 配置を使用します。

azd ai agent init --model-deployment my-deployment

azure.yaml テンプレートを採用するときは、同じ初期化コマンドに--model-deployment <name>を追加し、既存のプロジェクトを選択します。 現在、このパスには対話型の既存デプロイ ピッカーは用意されていません。 オーバーライドがない場合、採用された構成はテンプレートの要求されたモデルを保持することができます。 azd provision を実行する前に、プロジェクトのデプロイ宣言とエージェントのモデル設定の両方を確認してください。

デプロイ モードを選択する

既定では、azd ai agent initはPythonプロジェクトと.NET プロジェクトにコード展開を使用します。 コード展開では、ソースが ZIP パッケージとしてアップロードされます。 代わりにコンテナー ベースのプロジェクトをスキャフォールディングするには、 --deploy-mode container渡します。

azd ai agent init --deploy-mode container

事前構築済みのコンテナー イメージをデプロイするには、 --image と --agent-nameを渡します。 このオプションは、テンプレートと言語の選択、コード スキャフォールディング、Dockerfile の生成、およびAzure Container Registryセットアップをスキップします。

azd ai agent init --agent-name my-agent --image myregistry.azurecr.io/my-agent:v1

ソース コードを非対話で初期化する場合は、--runtime と --entry-point に --deploy-mode code を指定します。 生成された .agentignore では、.gitignore 構文を使用してデプロイ用の ZIP ファイルから特定のファイルを除外しています。ソースをアップロードする前に、これを確認してください。

テンプレートを非インターアクティブに参照する

スキャフォールディングする前にカタログを検査したり、スクリプトから azd ai agent init を実行したりするには、カタログを一覧表示します。

# Everything in the catalog
azd ai agent sample list

# Just the featured Python agent samples
azd ai agent sample list --featured-only --language python --type agent

# Full azd templates only, as JSON for scripting
azd ai agent sample list --type azd --output json

各エントリには、スキャフォールディング先のディレクトリでコピーして実行する、すぐに実行できる initCommand が含まれています。

Tip

別の Foundry エージェント ID でサンプルを再利用する場合は、--agent-name <new-name>にazd ai agent init渡して、azure.yamlに書き込まれた名前がサンプルの既定の名前と競合しないようにします。

既存のコードから初期化する

既存のPythonまたは.NETエージェント コードがある場合は、コードが既に含まれているディレクトリ内でazd ai agent initを実行します。

cd my-agent/
azd ai agent init

CLI は、既存のファイルを検出し、コードを上書きすることなく、それらのファイルの周囲に azure.yaml サービス エントリを生成します。 コンテナーのデプロイでは、Dockerfile も追加されます。 後で「インフラストラクチャ アズ コード」として書き出さない限り、インフラストラクチャはデフォルトでは bicep なしのままです。

エージェント コードは、 ホストされるエージェント ランタイム コントラクトを満たしている必要があります。

  • ポート 8088 でリッスンします。
  • GET /readiness でヘルス プローブを公開します。
  • サポートされているプロトコル (responses または invocations) のいずれかを処理します。

コードでこれらのプロトコルの 1 つがまだ読み上げられない場合は、 Foundry プロトコルとエージェントのロジックの間で変換される軽量 SDK ラッパーであるプロトコル アダプターを追加します。

初期化のソース ディレクトリまたはターゲット ディレクトリを指定するには、--src を使用してください:

azd ai agent init --src src/my-agent

ファイルベースのエージェントを既存のプロジェクトに追加する

YAML または JSON に直接エージェント定義がある場合は、テンプレート導入ではなく、 agent addを使用します。

azd ai agent add support-agent --file ./agents/support.yaml
azd deploy support-agent

support-agent は azure.yamlのサービス キーであり、Foundry エージェント名であるとは限りません。 このコマンドは、$refに対するルート azure.yamlを使用してサービスを追加または更新します。 ローカルで検証されます。認証、ソースのコピー、リモート リソースの作成、デプロイは行われません。

プロジェクトでは、1 つの azure.ai.project サービスを宣言する必要があります。 --project <service-key> を入力してそのサービスを確定し、--source <directory> を入力してエージェントのソースディレクトリを上書きしてください。 ディレクトリはプロジェクト内に既に存在している必要があります。

プロンプトエージェントと音声エージェントを初期化する

この拡張機能は、ソース コードがホストされていないエージェントにも対応しています。 迅速に対応するエージェントを選択するには、--kind prompt を選択し、その名前、モデル、指示を指定します。

azd ai agent init --kind prompt \
  --agent-name support-agent \
  --model <model-name> \
  --instructions "Answer support questions concisely."

プロンプト エージェントの要約には、 --description を使用します。 --rai-policy 既存のアカウント ポリシーを名前または ARM ID でアタッチします。 none はアカウントの既定値を継承します。 このオプションはポリシーを作成せず、ホストされているエージェントでは無視されます。 テンプレートを採用するときは、代わりに azure.yaml でポリシーを宣言します。

マネージド プロンプト音声エージェントの場合:

azd ai agent init --kind prompt-voice --agent-name support-voice

マネージド音声モデルのデフォルト値は gpt-realtime であり、モデルのデプロイは必要ありません。 --modelと--voiceを使用して、マネージド モデルと出力音声を選択します。 このパスでは、ソース、プロトコル、コード、コンテナーの設定が無効になります。 azd provisionとazd deployを使用してデプロイし、Voice Live クライアントでazd ai agent showから音声 WebSocket エンドポイントを使用します。 テキスト invoke は音声クライアントではありません。

ホスト型エージェントに音声機能を組み込むには、両方のサービスを宣言する完全な azure.yaml を採用します。 音声サービスは、 conversationEngine.type: hosted_agent と conversationEngine.name を使用して、ホステッド ターゲット サービスを参照します。 以前の modelType: hosted_agent フィールドと targetAgent フィールドはサポートされていません。

既存の Foundry プロジェクトに接続する

azdを使用して既存の Foundry プロジェクトを管理するには、ウィザードを実行し、既存のプロジェクトに接続するオプションを選択します。 また、プロジェクトのAzure リソース ID を直接指定することで、対話型の選択をスキップすることもできます。

azd ai agent init --project-id /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}

project ID を見つけるには、Foundry ポータルを開き、管理>Project詳細に移動し、リソース ID の値をコピーします。

Warnung

--project-idを使用して既存のプロジェクトに対して初期化すると、新しいプロジェクトの作成時に実行されるロールの自動割り当てがスキップされます。 必要なロールが既に割り当てられていることを確認します。 完全なマトリックスについては、 ホストされているエージェントのアクセス許可のリファレンスを参照してください。

作成内容を確認する

既定では、 init は次のプロジェクト構造を作成します。 コンテナーのデプロイにのみ Dockerfile が必要です。

.
|-- azure.yaml                  # Unified azd project and hosted agent configuration
|-- src/
|   \-- <agent-name>/
|       |-- Dockerfile          # Container build definition
|       \-- ...                 # Agent source code
|-- .azure/                     # Environment configuration
\-- infra/                      # Optional IaC, created when you pass --infra

テンプレートとサンプルは、統合された azure.yaml をプロジェクト ルートに発行します。 init 中に、 azd はそのファイルを採用または生成します。 既定では、インフラストラクチャを取り出す場合を除き、Bicepまたは Terraform ファイルを維持する必要はありません。

Python エージェントについては、生成されたエージェントサービスを確認し、ローカルでのテストや展開を行う前に、その env マップに PYTHONNOUSERSITE: "1" を追加します。 ユーザー サイト ディレクトリではなく、エージェントの仮想環境またはイメージに依存関係をインストールします。 「Pythonスタートアップの構成」を参照してください。

Terraform または Bicep インフラストラクチャの選択

Terraform を使用してインフラストラクチャを管理するには、プロジェクトを初期化するときにそれを選択します。

azd ai agent init --infra=terraform

インフラストラクチャとデプロイ モードは独立した選択肢です。 Terraform インフラストラクチャを使用するコンテナー ベースのエージェントの場合は、次を使用します。

azd ai agent init --infra=terraform --deploy-mode container

新しいプロジェクトの場合、コマンドは infra/ の下に Terraform ファイルを書き込み、 azure.yamlで Terraform インフラストラクチャ プロバイダーを構成します。 既存のインフラストラクチャを持つプロジェクトでは、Foundry インフラストラクチャを infra/foundry/ の下の別のレイヤーとして生成できます。 プロビジョニングする前に、生成された構成を確認します。

代わりにBicepを選択するには、--infra=bicepまたは短縮形の--infraを使用します。 --infraを省略すると、インフラストラクチャのない既定のワークフローが保持されます。

azd provision は、選択したインフラストラクチャを適用します。 azd deploy 引き続き hosted-agent バージョンが作成されます。Terraform を選択しても、エージェントバージョン管理は Terraform 状態に移行されません。

ファイル構造とカスタマイズについては、 ホストされるエージェントのインフラストラクチャに関するページを参照してください。 パイプラインで Terraform を使用する前に、 Terraform CI/CD とリモート状態を構成します。