ソースコードからホストされたエージェントをデプロイする (プレビュー)

この記事では、コンテナーイメージをビルドしたりプッシュしたりせずに、foundry Agent Service に Hosted agent をPythonまたは.NETソースコードからデプロイする方法について説明します。コードの .zip (および必要に応じて依存関係) をアップロードすると、Agent Service はそれを as-is 実行するか、クラウドで依存関係を構築します。

初めてデプロイする場合、または最速のパスが必要な場合は、「クイックスタート: 最初のホステッドエージェントをデプロイする」を使用してください。このクイックスタートでは、Azure Developer CLI (azd) または Foundry Toolkit for VS Code を使用します。このツールキットは、ソースをパッケージ化し、アップロードし、active をポーリングし、ロールベースのアクセス制御を自動的に構成します。クイックスタートでデプロイ方法を求められたら、[コード] (または [ソースコード (ZIP アップロード)]) を選択します。

この記事は、カスタムツール、言語に依存しない自動化、または既存の CD システムとの統合のために、REST API を使用してソースコードエージェントを直接デプロイする場合に使用します。この記事では、次のタスクを完了します。

ソース .zip をビルドし、依存関係解決モードを選択します。
REST 経由でエージェントを作成し、エージェントが activeに到達するまで待ってから呼び出します。
デプロイされたエージェントのログを更新、バージョン管理、ダウンロード、ストリーム配信します。

ランタイムイメージを完全に制御する必要がある場合、または既に動作する Dockerfile がある場合は、コンテナーベースのパスを使用します。ホストされたエージェントをデプロイします。

Important

ホストされているエージェントのソースコードのデプロイは プレビュー段階です。機能、リージョンの可用性、API は、一般提供前に変更される可能性があります。

Prerequisites

サポートされているリージョンの Microsoft Foundry プロジェクト。
Azure CLI バージョン 2.80 以降。プロジェクトを所有するテナントにサインインしています。
curlなどのコマンドライン HTTP クライアント (この記事の REST の例では、curlを使用します)。
ローカル Python パッケージの場合: Python 3.13 以降の pip。
ローカル .NET パッケージの場合: .NET 10 SDK。

サポートされているランタイム

エージェント定義の code_configuration.runtime フィールドには、次の値を指定できます。 zip に含まれるバイナリに対応するランタイムを選択します。Python の場合は Linux x86_64 ホイール、.NET の場合は TargetFramework 出力の dotnet publish を選択します。

Language	ランタイム値
Python	`python_3_13`、`python_3_14`
.NET	`dotnet_10`

言語バージョンのサポートポリシー

エージェントサービスランタイムには、 code_configuration.runtimeの値ごとにプラットフォームで構築されたコンテナーイメージが含まれています。デプロイされたエージェントを完全にサポートし続けるために、Foundry はホストされるエージェント言語のサポートを、各言語のサポート終了に合わせて調整します。サポートは、言語バージョンのコミュニティのサポート終了日に終了します。 Microsoft は、プラットフォームの制約（基盤となるベースイメージなど）により必要な場合、code_configuration.runtime 値を予定より早く廃止することがあります。

アップストリームのサポート終了スケジュールについては、以下を参照してください。

Python: Python バージョンの状態 (python.org)。
.NET: .NETと.NET Core サポートポリシー。

提供終了フェーズ

言語の有効期限が切れた後も、廃止されたランタイム値を使用するホストされたエージェントを作成、更新、実行できます。ただし、これらのエージェントは、現在の code_configuration.runtime 値を設定して再デプロイすることによって、サポートされているランタイムにアップグレードするまで、サポート、新機能、またはセキュリティパッチの対象になりません。

必要なアクセス許可

ホスト型エージェントを展開するにはprojectスコープで Foundry Project Manager が必要です。このロールは、エージェントを作成および更新するためのデータプレーンアクセス許可と、実行中のコードがモデルとツールの呼び出しに使用するプラットフォームで作成されたエージェント ID に Foundry User を割り当てる機能を付与します。

エージェントは、ユーザー ID とは別のプラットフォーム割り当てマネージド ID として実行されます。この ID には、コンテナー内からモデルを呼び出すために Foundry ユーザー が必要です。 azdまたは Foundry Toolkit for VS Code を使用してデプロイすると、ツールによってこのロールが自動的に割り当てられます。 REST を使用してデプロイする場合は、自分で付与します。ホストされるエージェントのアクセス許可のリファレンスを参照してください。

REST 呼び出しの場合は、機能がプレビュー中の間に変更要求 (作成、更新、削除) にプレビュー機能ヘッダーを含めます。

Foundry-Features: CodeAgents=V1Preview,HostedAgents=V1Preview

現在は、それがなくても GET リクエストは動作しますが、念のため毎回の呼び出しに含めてください。このヘッダーはプレビュー動作を制御しており、GA 前により厳密に適用される可能性があります。

デプロイのライフサイクル

すべてのソースコードのデプロイは、同じ手順に従います: パッケージ化 → 作成または更新 → active になるまでポーリング → 呼び出し。ソースコードパスはエージェント定義で code_configuration を使用します。イメージベースのパスでは代わりに container_configuration が使用されます。2 つのパスは 1 つのバージョンで相互に排他的です。

azdまたは Foundry Toolkit を使用したガイド付きチュートリアルについては、クイックスタートを参照してください。この記事の残りの部分では、REST API を使用して同じライフサイクルについて説明します。

依存関係の解決方法を選択する

開始する前に、 code_configuration.dependency_resolutionの値を選択します。この選択は、zip に入れる内容に影響します。

価値	Behavior	次の場合に使用します。
`remote_build`	エージェントサービスは、`requirements.txt` (Python) から依存関係をインストールするか、プロビジョニング中にプロジェクトファイル (.NET) を復元します。	小さなアップロードと最も単純な内部ループが必要です。初めてのユーザーに推奨されます。
`bundled`	ZIP はそのまま実行されます。ビルド済みの Linux 依存関係は、`packages/` (Python) または `dotnet publish` の出力 (.NET) に含めます。	再現可能なビルドが必要です。依存関係がプライベートまたはホイールのみの場合、またはプロジェクトがサーバー側でクリーンに復元されない場合。

バンドルモードについては、ローカルビルドコマンドの zip を手動でパッケージ化するを参照してください。

REST API を使用してデプロイする

直接 HTTP ベースのデプロイまたはカスタムツールに REST API を使用します。以下のセクションでは、変数の設定、zip のビルド、エージェントの作成、 activeまでポーリング、呼び出しの順に、最初のデプロイについて説明します。更新、バージョン、ダウンロード、およびログストリーミングエンドポイントは、進行中の操作の下にグループ化されます。

ENDPOINT="https://{account}.services.ai.azure.com/api/projects/{project}"
API_VERSION="2025-11-15-preview"
TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
AGENT=my-code-agent
ZIP=./agent-code.zip
SHA=$(sha256sum "$ZIP" | cut -d' ' -f1)

$Endpoint    = "https://{account}.services.ai.azure.com/api/projects/{project}"
$ApiVersion  = "2025-11-15-preview"
$Token       = az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv
$Agent       = "my-code-agent"
$Zip         = "./agent-code.zip"
$Sha         = (Get-FileHash $Zip -Algorithm SHA256).Hash.ToLower()

Note

残りの REST の例では、Bash スタイルの curl コマンドを使用します。 Windows では、curl.exe を使って PowerShell でそれらを実行します。行継続には、バックスラッシュの代わりにバッククォート（`）を使用してください。

最小限の hello-world zip を構築する

Create を呼び出す前に、2 つのファイルを含むフラット zip を作成します。これは、エージェントサービスが Python remote_build デプロイに対して受け入れる最小ペイロードです。

agent-code.zip
├── main.py            # your agent loop (starts a Foundry hosting server)
└── requirements.txt   # dependencies (for example, agent-framework, agent-framework-foundry-hosting)

metadata.json ( メタデータの例に示されているエージェント定義) はディスク上の zip の横にあり、別のマルチパートパーツとして送信されます。zip 内にありません。完全なレイアウト (bundled モードと.NETを含む) については、「 zip を手動でパッケージ化するを参照してください。動作するソースファイルについては、Python および .NET サンプルを参照してください。

マルチパートリクエストの形式

すべての変更エンドポイント (作成、更新) では、次の 2 つの部分で multipart/form-data が使用されます。

要素	Content-Type	Body
`metadata`	`application/json`	エージェント定義。
`code`	`application/zip`	未加工の zip バイト。 `filename=<agent>.zip`を設定します。

すべてのマルチパート呼び出しで必要なヘッダー:

Authorization: Bearer <token>
Accept: application/json
Foundry-Features: CodeAgents=V1Preview,HostedAgents=V1Preview
x-ms-code-zip-sha256: <sha256-hex-of-zip>

x-ms-code-zip-sha256 ヘッダーには、アップロードした zip の SHA-256 が記録されます。サービスはそれを格納し、 code:download にエコーバックして、デプロイする予定とデプロイされた内容の間の誤差を検出できるようにします。必ず含めてください。

Create 呼び出しには、 x-ms-agent-name: <agent-name>も必要です。名前は既に URL の一部であるため、更新呼び出しでは省略されます。

メタデータの例 (リモートビルド、応答)

このメタデータは hello-world zip と一致します。

{
  "description": "Hello-world code agent",
  "definition": {
    "kind": "hosted",
    "protocol_versions": [
      { "protocol": "responses", "version": "1.0.0" }
    ],
    "cpu": "1",
    "memory": "2Gi",
    "code_configuration": {
      "runtime": "python_3_13",
      "entry_point": ["python", "main.py"],
      "dependency_resolution": "remote_build"
    },
    "environment_variables": {
      "AZURE_AI_MODEL_DEPLOYMENT_NAME": "gpt-4.1-mini"
    }
  }
}

呼び出しプロトコルの場合は、 protocol_versions エントリを { "protocol": "invocations", "version": "1.0.0" }に置き換えます。 bundled モードの場合は、"dependency_resolution": "bundled"を設定し、Linux の依存関係をローカルでビルドします。

code_configuration および container_configuration は、エージェント定義内で相互に排他的です。ソースコードデプロイの code_configuration (この記事) またはイメージベースのデプロイの container_configuration を含めます。イメージバリアントについては、ホストされたエージェント (コンテナー) のデプロイを参照してください。

エージェントを作成する

curl -X POST "$ENDPOINT/agents?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Foundry-Features: CodeAgents=V1Preview,HostedAgents=V1Preview" \
  -H "x-ms-agent-name: $AGENT" \
  -H "x-ms-code-zip-sha256: $SHA" \
  -F "metadata=@metadata.json;type=application/json" \
  -F "code=@$ZIP;type=application/zip;filename=$AGENT.zip"

x-ms-agent-name は、Create 呼び出しでのみ必要です。名前は英数字で始まり終わる必要があり、中央にハイフンを含めることができます。また、63 文字以下にする必要があります。この応答には、creating のうちの最初の status が含まれています。

アクティブな対象者向けのアンケート

while true; do
  STATUS=$(curl -s -H "Authorization: Bearer $TOKEN" \
    -H "Foundry-Features: CodeAgents=V1Preview,HostedAgents=V1Preview" \
    "$ENDPOINT/agents/$AGENT/versions/1?api-version=$API_VERSION" | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "active" ] && break
  [ "$STATUS" = "failed" ] && echo "Provisioning failed." && exit 1
  sleep 5
done

地位	意味
`creating`	プロビジョニング中です。
`active`	呼び出す準備ができました。
`failed`	プロビジョニングが失敗しました。バージョンの `error` オブジェクトを確認します。`error.code`（たとえば `ProvisioningError`）と `error.message` には、障害の概要が示されます。 `remote_build`の場合、`error.message` には、最終的な復元またはコンパイルエラー行 (Python の pip、.NETの NuGet)、終了コード、および `aka.ms` トラブルシューティングリンクが含まれます。 (コンテナーログストリーミングはプロビジョニングの失敗には適用されません。コンテナーは開始されません。原因には `error.message` を使用してください)。)

エージェントを呼び出す

protocol_versionsで宣言されているエージェントのプロトコルを選択します。

応答プロトコル:

curl -X POST "$ENDPOINT/agents/$AGENT/endpoint/protocols/openai/responses?api-version=v1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: CodeAgents=V1Preview,HostedAgents=V1Preview" \
  -d '{"model":"gpt-4.1-mini","input":"Hello, agent!","stream":false}'

呼び出しプロトコル:

curl -X POST "$ENDPOINT/agents/$AGENT/endpoint/protocols/invocations?api-version=v1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: CodeAgents=V1Preview,HostedAgents=V1Preview" \
  -d '{"input":"Hello, this is a test invocation!"}'

便利な応答ヘッダー:

Header	Use
`x-agent-session-id`	コンテナーセッション ID。 `:logstream`に渡します。 `424` / `500`でも返されます。
`x-ms-region`	呼び出しを処理したリージョン。サポートチケットを提出するときに便利です。

応答プロトコルの場合、呼び出しごとの応答識別子は、応答 JSON 本文の id フィールドです (たとえば、 caresp_<random>)。これを使用して、呼び出しをコンテナーログに関連付けるか、サポート要求で呼び出しを参照します。

進行中の操作

最初のデプロイ後、これらのエンドポイントを使用してエージェントを進化させて運用します。

エージェントを更新またはバージョン管理する

コード変更または定義の更新をデプロイするには、マルチパート本文をエージェントリソースに再ポストします。このサービスでは 、コンテンツアドレス指定可能なバージョン管理が使用されます。新しいバージョンは、zip の SHA-256 またはエージェント定義が実際に変更された場合にのみ作成されます。同一の再ポストは、既存の最新バージョンを返します。

curl -X POST "$ENDPOINT/agents/$AGENT?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Foundry-Features: CodeAgents=V1Preview,HostedAgents=V1Preview" \
  -H "x-ms-code-zip-sha256: $SHA" \
  -F "metadata=@metadata.json;type=application/json" \
  -F "code=@$ZIP;type=application/zip;filename=$AGENT.zip"

応答は、versions.latest が設定された完全なエージェントエンベロープです。結果のバージョンをポーリングします( 「アクティブなバージョンをポーリングする」を参照)。

お使いのツールでバージョン形式のレスポンス（エージェントエンベロープではなく、AgentVersionObject のみ）を必要とする場合は、同じマルチパート本文を $ENDPOINT/agents/$AGENT/versions?api-version=$API_VERSION に投稿してください。重複除去ルールは同じです。両方のエンドポイントが同じコンテンツアドレス指定可能なロジックを共有します。

デプロイされた zip をダウンロードする

zip をダウンロードして、デプロイされている内容を正確に確認します。最新のバージョンをダウンロードする agent_version を省略します。特定のバージョンを対象とする agent_version=<n> を渡します。

VERSION=1

# Latest version
curl -O -J "$ENDPOINT/agents/$AGENT/code:download?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/zip" \
  -H "Foundry-Features: CodeAgents=V1Preview,HostedAgents=V1Preview"

# Specific version
curl -O -J "$ENDPOINT/agents/$AGENT/code:download?api-version=$API_VERSION&agent_version=$VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/zip" \
  -H "Foundry-Features: CodeAgents=V1Preview,HostedAgents=V1Preview"

2 つの応答ヘッダーは、ダウンロードした内容を確認するのに役立ちます。

Header	Use
`x-ms-agent-version`	サービスが提供したバージョン番号。 `agent_version`を省略する場合は、このヘッダーを使用して、現在 "最新" になっているバージョンを確認します。
`x-ms-code-zip-sha256`	SHA-256 アップロードされた zip 用に格納されたサービス。それをローカルの計算と比較して、デプロイする予定とデプロイされた内容の間の誤差を検出します。

イメージベースのエージェントは 409 AgentNotCodeBasedを返します。

コンテナーログをストリーミング

curl -N "$ENDPOINT/agents/$AGENT/sessions/<sessionId>:logstream?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream"

ログはサーバー送信イベントとして配信されます。 {sessionId} は、呼び出し応答からの x-agent-session-id の値です。このエンドポイントを使用して、ランタイムエラーと 424 session_not_ready 応答をデバッグします。ログストリーミングエンドポイントには、 Foundry-Features プレビューヘッダーは必要ありません。

zip を手動でパッケージ化する

azdを使用する場合は、このセクションをスキップazd、zip をビルドします。 REST API を使用する場合、 バンドルされた 依存関係の解決に切り替える場合、またはアップロードコンテンツを完全に制御する必要がある場合は、読み取ります。

zip は ルートにフラットである必要があります。最上位のラッパーフォルダーはありません。

Python レイアウト (リモートビルドモード)

サービスは、 requirements.txtからクラウドに依存関係をインストールします。

agent-code.zip
├── main.py
└── requirements.txt

Python レイアウト (バンドルモード)

事前構築済みの Linux 依存関係を packages/に出荷します。

agent-code.zip
├── main.py                    # entry point
├── requirements.txt
└── packages/                  # extracted modules (not raw .whl files)
    ├── azure/identity/__init__.py
    └── requests/__init__.py

.NET レイアウト (リモートビルドモード)

bin/、obj/、またはpublish/出力なしで、プロジェクトソースのみを zip 圧縮します。エージェントサービスは、プロビジョニング中に dotnet restore と dotnet publish を実行します。

agent-code.zip
├── MyAgent.csproj
├── Program.cs
└── ... (additional .cs files)

エージェント定義で設定した entry_point は、サーバー側の発行によって生成された発行済みアセンブリ名 ( ["dotnet", "MyAgent.dll"] など) を参照します。

.NET レイアウト (バンドルモード)

dotnet publish -c Release -r linux-x64 --self-contained false の出力を、zip ファイル内に直接格納して圧縮します:

agent-code.zip
├── MyAgent.dll
├── MyAgent.runtimeconfig.json
└── ... (publish output)

Warning

session_creation_failedまたはModuleNotFoundErrorの原因となる一般的なパッケージ化の間違い:

ソースをフォルダーにラップします (ルートにmy-agent/main.pyするのではなく、main.py)。
抽出されたモジュールの代わりに、生の .whl ファイルを packages/ に含めます。
Linux ランタイムWindowsバイナリ (.pyd、.dll) のバンドル。

Linux の依存関係をローカルにビルドする (バンドル、Python)

manylinux2014_x86_64 プラットフォームタグを使用すると、pip は Windows や macOS からでも Linux 用の wheel をダウンロードできます。

Bash
PowerShell/Windows cmd

pip install -r requirements.txt \
    --target packages/ \
    --platform manylinux2014_x86_64 \
    --python-version 3.13 \
    --implementation cp \
    --only-binary=:all:

zip -r agent-code.zip main.py requirements.txt packages/

pip install -r requirements.txt --target packages --platform manylinux2014_x86_64 --python-version 3.13 --implementation cp --only-binary=:all:

tar -a -c -f agent-code.zip main.py requirements.txt packages

--only-binary=:all: はホイールを強制します (ソースビルドはありません)。 --python-versionは、エージェント定義のruntime値と一致する必要があります。

.NET 出力をビルドする（バンドル済み）

dotnet publish -c Release -r linux-x64 --self-contained false -o publish/
cd publish && zip -r ../agent-code.zip .

.NET ランタイムを zip に発送する場合は、--self-contained true を使用します。エージェント定義で設定する runtime は、 TargetFrameworkと一致している必要があります。

制限

制限	価値
最大 zip サイズ (マルチパートアップロード)	250MB

Troubleshooting

症状:	考えられる原因	修正
`401 Unauthorized`	不足している、またはスコープが誤ったトークン	`--resource https://ai.azure.com`を使用してトークンを取得します。
`403 Forbidden`	呼び出し元には、プロジェクトに対する RBAC 権限がありません	プロジェクトのスコープにおいて、Foundry User (またはそれ以上の権限) を付与します。
`409 conflict` 作成時 (`Agent '<name>' already exists`)	エージェント名は既に存在します	Update (POST `/agents/{name}`) を使用するか、新しい名前を選択します。
`400 bad_request` 呼び出し時の (`Agent version is still being provisioned`)	新しいバージョンは現在デプロイ中で、アクティブなバージョンへの切り替えが行われています	`status`までバージョン `active`をポーリングしてから、再試行します。
`424 session_not_ready` 呼び出し時	コンテナーは開始されましたが、タイムアウト中 `/readiness` HTTP 200 が返されませんでした	`:logstream`を使用してログをストリーミングし、準備プローブまたはスタートアップエラーを修正し、再デプロイします。
`409 conflict` DELETE エージェントの場合 (`Agent has active sessions`)	セッションを開いて削除をブロックする	セッションがアイドル状態になるまで待つか、連鎖削除セッションに `&force=true` を追加します。
バージョンが `creating` で停止しています（>10 分、リモートビルド）	サーバーのビルドが失敗したか、解決できませんでした `requirements.txt`	`dependency_resolution: bundled`に切り替え、ローカルで事前構築します。
バージョンは `failed` に切り替わります	不適切な zip レイアウト、構文エラー、または (`remote_build`) 復元/コンパイルエラー	バージョンの `error` オブジェクトを最初に読み取ります。`error.code` はエラーを分類し、`error.message` には、基になる復元またはコンパイルエラー行 (Python の pip、.NET の NuGet) とトラブルシューティングリンクが含まれています。フォルダー構造を確認します。コンテナーの起動後にのみ、 `:logstream` を使用します。
`ModuleNotFoundError` 実行時	`packages/` が見つからないか、生の `.whl` ファイルが含まれているか、Windows バイナリが含まれている	`pip install --target packages/ --platform manylinux2014_x86_64 --only-binary=:all:`を使用して再構築します。
`409 AgentNotCodeBased` ダウンロード時	エージェントはイメージベースです	コンテナーベースのデプロイドキュメントを使用します。

リソースをクリーンアップする

# Delete one version
curl -X DELETE "$ENDPOINT/agents/$AGENT/versions/1?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

# Delete the agent and all its versions
curl -X DELETE "$ENDPOINT/agents/$AGENT?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

# Force-delete the agent (cascades to any active sessions)
curl -X DELETE "$ENDPOINT/agents/$AGENT?api-version=$API_VERSION&force=true" \
  -H "Authorization: Bearer $TOKEN"

を使用してazdからプロジェクトをスキャフォールディングした場合は、プロジェクトルートからazd down実行して、代わりにプロビジョニングされた環境全体を削除します。

Warning

エージェントを削除すると、そのバージョンがすべて削除され、アクティブなセッションが終了します。この操作を元に戻すことはできません。

次のステップ

ホストされるエージェントのライフサイクルを管理する

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-06-01