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

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

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

前提条件

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

開始点を選択する

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

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

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

azd ai agent init

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

エージェント名はテンプレートから取得されます。 CLI は、azdという名前の<directory>-dev環境を作成し、選択した Foundry プロジェクトの詳細を使用して構成します。 各テンプレートには、エージェントのソース コード、 Dockerfile、 azure.yaml ファイルが含まれています。このファイルは、 azd プロジェクトとホステッド エージェント構成の統合プロジェクト マニフェストとして機能します。

azure.yaml URL から初期化する

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

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

-m オプションは引き続きレガシ エージェント マニフェスト URL を受け入れますが、現在のサンプルでは統合azure.yamlを発行しています。

モデルを指定する

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

azd ai agent init --model gpt-4.1

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

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

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

既定では、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

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

スキャフォールディングする前にカタログを検査したり、スクリプトから 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 が含まれています。

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

既存の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 ラッパーであるプロトコル アダプターを追加します。

既存の azd プロジェクトにエージェントを追加するには、 init プロジェクトを検出し、既存の azure.yamlに新しいサービス エントリを追加します。 --srcを使用してサブディレクトリを指定します。

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

既存の 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 の値をコピーします。

作成内容を確認する

initが完了すると、プロジェクト ディレクトリには次の構造が含まれます。

.
|-- 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 only after you eject infrastructure

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

関連するコンテンツ

• クイック スタート: 最初のホステッド エージェントをデプロイする
• ホステッド エージェント用の azure.yaml を作成する
• ホステッド エージェント向けの azure.yaml リファレンス
• Azure Developer CLI を使用したホステッド エージェント インフラストラクチャ