ホストされるエージェントをデプロイする

Azure Developer CLI または VS Code を使用してデプロイする

Azure Developer CLI (azd) と Microsoft Foundry Toolkit for Visual Studio Codeは、コンテナーの構築、Azure Container Registryへのプッシュ、エージェント バージョンの作成、RBAC ロールの割り当てなど、デプロイ ライフサイクル全体を自動化します。 ガイド付き初めてのチュートリアルについては、「 クイック スタート: ホスト型エージェントの作成とデプロイ」を参照してください。

1 つのコマンドでデプロイする

エージェント プロジェクト ディレクトリから、インフラストラクチャをプロビジョニングし、1 つの手順でデプロイします。

azd up

azd up は azd provisionを組み合わせて、Foundry プロジェクト、モデル デプロイ、コンテナー レジストリ、Application Insights、マネージド ID を azd deployと共に作成します。 初めてのデプロイ、またはインフラストラクチャとエージェントのコードの両方を変更する場合に使用します。

コードの変更のみをデプロイする

Azure リソースを既にプロビジョニングしていて、新しいエージェント バージョンをプッシュするだけで済む場合:

azd deploy

azd deploy中、CLI は次の処理を行います。

1. ローカル Docker を必要としないため、Azure Container Registryでコンテナー イメージをリモートでビルドします。
2. イメージをレジストリにプッシュします。
3. Foundry Agent Service でホストされるエージェント バージョンを作成します。
4. 専用のMicrosoft Entra エージェント ID を作成し、エージェントがモデルとツールにアクセスするために必要な RBAC ロールを割り当てます。

バージョンの管理

各 azd deploy は、エージェントの新しいバージョンを作成します。 CLI では以前のバージョンが保持され、最新バージョンは既定でアクティブになっています。

デプロイメントを確認する

azd ai agent show

出力には、エージェント名、バージョン、プロトコル、コンテナー リソース、環境変数、作成タイムスタンプが含まれます。 概要ビューには --output table を使用します。

イメージをローカルでビルドする

既定では、azdはAzure Container Registryでリモートでコンテナー イメージをビルドします。 イメージをローカルでビルドするには、remoteBuild: falseでazure.yamlを設定します。 ローカル ビルドには Docker Desktop が必要です。

コンテンツの安全性ポリシーに対するプロンプトと応答を表示するには、 エージェントにコンテンツ セーフティ ガードレールを追加します。

Python SDK を使用してデプロイする

エージェントのデプロイをコードから直接管理する場合は、SDK Python使用します。

その他の前提条件

• Python 3.10 以降

• Azure Container Registry のコンテナー イメージ

• コンテナー レジストリのリポジトリ ライター または AcrPush 役割 (イメージをプッシュするための役割)

• Azure AI Projects SDK バージョン 2.3.0 以降

  pip install "azure-ai-projects>=2.3.0"
  

コンテナー イメージをビルドしてプッシュする

1. Docker イメージをビルドします。

   docker build --platform linux/amd64 -t myagent:v1 .
   

   Python および C# の Dockerfile のサンプルを参照してください。

2. Azure Container Registryにプッシュする:

   az acr login --name myregistry
   docker tag myagent:v1 myregistry.azurecr.io/myagent:v1
   docker push myregistry.azurecr.io/myagent:v1
   

コンテナー レジストリのアクセス許可を構成する

プロジェクトのマネージド ID にプル イメージへのアクセス権を付与します。

1. Azure ポータルで、Foundry プロジェクト リソースに移動します。

2. Identity を選択し、システム割り当て済み の下にあるオブジェクト (プリンシパル) ID をコピーします。

3. コンテナー レジストリのリポジトリ閲覧者ロールを、コンテナー レジストリのこの ID に割り当てます。 Azure Container Registryのロールとアクセス許可についてご参照ください。

ホストされるエージェントのバージョンを作成する

バージョンを作成すると、プラットフォームによってエージェントが自動的にプロビジョニングされます。 別の開始手順はありません。 プラットフォームによってコンテナー スナップショットが作成され、エージェントが要求を処理する準備が整います。

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AgentEndpointProtocol,
    ContainerConfiguration,
    HostedAgentDefinition,
    ProtocolVersionRecord,
)
from azure.identity import DefaultAzureCredential

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create project client
credential = DefaultAzureCredential()
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=credential,
)

# Create a hosted agent version
agent = project.agents.create_version(
    agent_name="my-agent",
    definition=HostedAgentDefinition(
        protocol_versions=[
            ProtocolVersionRecord(protocol=AgentEndpointProtocol.RESPONSES, version="1.0.0")
        ],
        cpu="1",
        memory="2Gi",
        container_configuration=ContainerConfiguration(
            image="your-registry.azurecr.io/your-image:tag"
        ),
        environment_variables={
            "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
        },
    )
)

print(f"Agent created: {agent.name}, version: {agent.version}")

両方のプロトコルを公開するには、両方を protocol_versions渡します。

protocol_versions=[
    ProtocolVersionRecord(protocol=AgentEndpointProtocol.RESPONSES, version="1.0.0"),
    ProtocolVersionRecord(protocol=AgentEndpointProtocol.INVOCATIONS, version="1.0.0"),
    ProtocolVersionRecord(protocol=AgentEndpointProtocol.INVOCATIONS_WS, version="1.0.0"),
],

キー パラメーター:

セッション コンピューティングがアイドル状態になったときに設定するには、「 セッションのアイドル状態を管理する」を参照してください。

バージョンのステータスを確認する

バージョンを作成した後、エージェントを呼び出す前に状態が active されるまでポーリングします。 通常、プロビジョニングにはイメージ サイズに応じて 1 分未満かかります。

import time

# Poll until the agent version is active
while True:
    version_info = project.agents.get_version(
        agent_name="my-agent",
        agent_version=agent.version
    )
    status = version_info["status"]
    print(f"Status: {status}")

    if status == "active":
        print("Agent is ready!")
        break
    elif status == "failed":
        print(f"Provisioning failed: {version_info['error']}")
        break

    time.sleep(5)

バージョンの状態の値:

エージェントを呼び出す

バージョンが active 状態になったら、 get_openai_client を使用して、エージェントのエンドポイントにバインドされた OpenAI クライアントを作成します。

応答プロトコルについて

# Create an OpenAI client bound to the agent endpoint
openai_client = project.get_openai_client(agent_name="my-agent")

response = openai_client.responses.create(
    input="Hello! What can you do?",
)

print(response.output_text)

呼び出しプロトコルの場合は、呼び出しエンドポイントを直接呼び出します。

import requests

token = credential.get_token("https://ai.azure.com/.default").token
url = f"{PROJECT_ENDPOINT}/agents/my-agent/endpoint/protocols/invocations"

response = requests.post(url, headers={
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}, params={"api-version": "v1"}, json={
    "message": "Process this task"
})

print(response.json())

詳細な例については、 ホストされるエージェントのサンプルを参照してください。

JavaScript/TypeScript SDK を使用してデプロイする

エージェントのデプロイをコードから直接管理する場合は、SDK Node.js 使用します。 SDK 呼び出し元は Node.jsで実行されますが、コンテナー イメージ自体は、応答または呼び出しプロトコル ライブラリを使用して構築されたPythonまたは.NETエージェント コードを実行します。Node.js ホストされたエージェント ランタイムはありません。

その他の前提条件

• Node.js 22 以降

• Azure Container Registry のコンテナー イメージ

• コンテナー レジストリのリポジトリ ライター または AcrPush 役割 (イメージをプッシュするための役割)

• @azure/ai-projectsパッケージと@azure/identity パッケージ

  npm install @azure/ai-projects @azure/identity
  

開始する前に、コンテナー イメージをビルドしてAzure Container Registryにプッシュし (Docker コマンドなど、Python タブを参照)、プロジェクトマネージド ID にレジストリの Container Registry Repository Reader ロールを付与します。

ホストされるエージェントのバージョンを作成する

バージョンを作成すると、プラットフォームによってエージェントが自動的にプロビジョニングされます。 別の開始手順はありません。 プラットフォームによってコンテナー スナップショットが作成され、エージェントが要求を処理する準備が整います。

import { AIProjectClient } from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

// Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
const projectEndpoint =
  process.env["FOUNDRY_PROJECT_ENDPOINT"] || "your_project_endpoint";
const agentName = "my-agent";

const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
);

// Create a hosted agent version
const agent = await project.agents.createVersion(agentName, {
  kind: "hosted",
  cpu: "1",
  memory: "2Gi",
  container_configuration: {
    image: "your-registry.azurecr.io/your-image:tag",
  },
  protocol_versions: [{ protocol: "responses", version: "1.0.0" }],
  environment_variables: { MODEL_DEPLOYMENT_NAME: "gpt-5-mini" },
});

console.log(`Agent created: ${agent.name}, version: ${agent.version}`);

両方のプロトコルを公開するには、両方を protocol_versions渡します。

protocol_versions: [
  { protocol: "responses", version: "1.0.0" },
  { protocol: "invocations", version: "1.0.0" },
  { protocol: "invocations_ws", version: "1.0.0" },
],

バージョンのステータスを確認する

バージョンを作成した後、エージェントを呼び出す前に状態が active されるまでポーリングします。 通常、プロビジョニングにはイメージ サイズに応じて 1 分未満かかります。

function sleep(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

// Poll until the agent version is active
for (;;) {
  const versionInfo = await project.agents.getVersion(
    agentName,
    agent.version,
  );
  console.log(`Status: ${versionInfo.status}`);
  if (versionInfo.status === "active") {
    break;
  }
  if (versionInfo.status === "failed") {
    console.log(`Provisioning failed: ${versionInfo.error}`);
    break;
  }
  await sleep(5_000);
}

エージェント エンドポイントをルーティングして呼び出す

エージェント エンドポイントを作成したバージョンにルーティングし、OpenAI クライアントをエンドポイントにバインドします。

応答プロトコルについて

await project.agents.patchAgentObject(agentName, {
  agentEndpoint: {
    version_selector: {
      version_selection_rules: [
        {
          type: "FixedRatio",
          agent_version: agent.version,
          traffic_percentage: 100,
        },
      ],
    },
    protocol_configuration: { responses: {} },
  },
});

// Create an OpenAI client bound to the agent endpoint
const openAIClient = project.getOpenAIClient({
  azureConfig: { allowPreview: true, agentName },
});

const response = await openAIClient.responses.create({
  input: "Hello! What can you do?",
});
console.log(response.output_text);

呼び出しプロトコルの場合は、呼び出しエンドポイントを直接呼び出します。

const credential = new DefaultAzureCredential();
const token = await credential.getToken("https://ai.azure.com/.default");
if (!token) {
  throw new Error("Failed to acquire an access token.");
}
const url = `${projectEndpoint}/agents/my-agent/endpoint/protocols/invocations`;

const response = await fetch(`${url}?api-version=v1`, {
  method: "POST",
  headers: {
    Authorization: "Bearer " + token.token,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ message: "Process this task" }),
});
console.log(await response.json());

リファレンス: AIProjectClient

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

HTTP ベースの直接デプロイやカスタム ツールとの統合に REST API を使用します。

開始する前に、コンテナー イメージをビルドしてAzure Container Registryにプッシュし、プロジェクトマネージド ID にレジストリの Container Registry Repository Reader ロールを付与します。

変数を設定する

BASE_URL="https://{account}.services.ai.azure.com/api/projects/{project}"
API_VERSION="v1"
TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)

エージェントを作成する

curl -X POST "$BASE_URL/agents?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "definition": {
      "kind": "hosted",
      "container_configuration": {
        "image": "myacr.azurecr.io/my-agent:v1"
      },
      "cpu": "1",
      "memory": "2Gi",
      "protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

エージェントを作成すると、バージョン 1 も作成され、プロビジョニングがトリガーされます。

セッション コンピューティングがアイドル状態になったときに設定するには、「 セッションのアイドル状態を管理する」を参照してください。

コンテンツの安全性ポリシーに対するプロンプトと応答を画面に表示するには、rai_configにdefinition オブジェクトを含めます。 ホストされるエージェントにコンテンツ セーフティ ガードレールを追加するを参照してください。

バージョンのステータスを確認する

statusがactiveされるまで、バージョン エンドポイントをポーリングします。

while true; do
  STATUS=$(curl -s -X GET "$BASE_URL/agents/my-agent/versions/1?api-version=$API_VERSION" \
    -H "Authorization: Bearer $TOKEN" | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "active" ] && echo "Ready!" && break
  [ "$STATUS" = "failed" ] && echo "Provisioning failed." && exit 1
  sleep 5
done

エージェントを呼び出す

エージェントの専用エンドポイントを使用して要求を送信します。 サーバー送信イベントを受信するように "stream": true を設定します。

応答プロトコル:

curl -X POST "$BASE_URL/agents/my-agent/endpoint/protocols/openai/responses?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Hello! What can you do?",
    "store": true
  }'

呼び出しプロトコル:

curl -X POST "$BASE_URL/agents/my-agent/endpoint/protocols/invocations?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Process this task"
  }'

新しいバージョンを作成する

新しいバージョンを作成して、更新されたコードまたは構成をデプロイします。

curl -X POST "$BASE_URL/agents/my-agent/versions?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": {
      "kind": "hosted",
      "container_configuration": {
        "image": "myacr.azurecr.io/my-agent:v2"
      },
      "cpu": "1",
      "memory": "2Gi",
      "protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

Azure Developer CLI のクリーンアップ

azd down

SDK のクリーンアップ

1 つのバージョンを削除します。

project.agents.delete_version(agent_name="my-agent", agent_version=agent.version)

または、エージェント全体とそのすべてのバージョンを削除します。 エージェントを呼び出した直後など、アクティブなセッションを連鎖削除するには、 force=True を使用します。エージェントを呼び出さないと、セッションがアクティブな間に競合エラーが発生して呼び出しが失敗します。

project.agents.delete(agent_name="my-agent", force=True)

SDK のクリーンアップ

1 つのバージョンを削除します。

await project.agents.deleteVersion("my-agent", agent.version);

または、エージェント全体とそのすべてのバージョンを削除します。

await project.agents.delete("my-agent", { force: true });

リファレンス: AIProjectClient

REST API のクリーンアップ

1 つのバージョンを削除します。

curl -X DELETE "$BASE_URL/agents/my-agent/versions/1?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

または、エージェント全体を削除します。

curl -X DELETE "$BASE_URL/agents/my-agent?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"