Wdrażanie hostowanego agenta

Wdrażanie przy użyciu interfejsu wiersza polecenia dewelopera Azure lub programu VS Code

Interfejs wiersza polecenia Azure Developer CLI (azd) oraz zestaw Microsoft Foundry Toolkit for Visual Studio Code automatyzują cały cykl życia wdrażania: kompilowanie kontenera, wypychanie go do usługi Azure Container Registry, tworzenie wersji agenta i przypisywanie ról RBAC. Aby zapoznać się z przewodnikiem po raz pierwszy, zobacz Przewodnik Szybki start: tworzenie i wdrażanie hostowanego agenta.

Wdrażanie za pomocą jednego polecenia

Z katalogu projektu agenta aprowizuj infrastrukturę i wdróż w jednym kroku:

azd up

azd up łączy azd provision, które tworzy projekt Foundry, wdrożenie modelu, rejestr kontenerów, usługę Application Insights i tożsamość zarządzaną, z azd deploy. Używaj go w przypadku wdrożeń po raz pierwszy lub za każdym razem, gdy zmieniasz zarówno infrastrukturę, jak i kod agenta.

Wdrażanie tylko zmian kodu

Jeśli zasoby platformy Azure zostały już aprowizowane i trzeba tylko wdrożyć nową wersję agenta:

azd deploy

Podczas azd deploy, CLI:

1. Tworzy obraz kontenera zdalnie w Azure Container Registry, więc nie potrzebujesz lokalnej platformy Docker.
2. Wysyła obraz do rejestru.
3. Tworzy hostowaną wersję agenta w usłudze Foundry Agent Service.
4. Tworzy dedykowaną tożsamość agenta Microsoft Entra i przypisuje role RBAC, których agent potrzebuje do uzyskiwania dostępu do modeli i narzędzi.

Zarządzanie wersjami

Każdy azd deploy tworzy nową wersję agenta. CLI zachowuje wcześniejsze wersje. Domyślnie punkt końcowy jest zgodny z najnowszą wersją; przypięty punkt końcowy nadal obsługuje wybraną wersję, chyba że zaktualizujesz konfigurację routingu.

Aby zweryfikować wersję kandydującą, zanim zacznie obsługiwać ruch produkcyjny, przypnij produkcję przed wdrożeniem i jawnie promuj. Przejrzyj ustawienia punktu końcowego w konfiguracji azd, aby wdrożenie nie zastępowało tego numeru PIN.

Weryfikowanie wdrożenia

azd ai agent show

Dane wyjściowe obejmują nazwę agenta, wersję, protokoły, zasoby kontenera, zmienne środowiskowe i znacznik czasu tworzenia. Użyj --output table, aby wyświetlić widok podsumowania.

Lokalne tworzenie obrazów

Domyślnie azd kompiluje obrazy kontenerów zdalnie w usłudze Azure Container Registry. Aby budować obrazy lokalnie, ustaw remoteBuild: false w azure.yaml. Kompilacje lokalne wymagają programu Docker Desktop.

Aby sprawdzać prompty i odpowiedzi pod kątem zasad bezpieczeństwa treści, dodaj do agenta zabezpieczenie bezpieczeństwa treści.

Wdrażanie przy użyciu zestawu SDK Python

Użyj zestawu SDK, jeśli chcesz zarządzać wdrożeniami agentów bezpośrednio z Python kodu.

Dodatkowe wymagania wstępne

• Python 3.10 lub nowszy

• Obraz kontenera w Azure Container Registry

• Rola zapisywania repozytorium usługi Container Registry lub AcrPush w rejestrze kontenerów (w celu wypychania obrazów)

• zestaw SDK projektów sztucznej inteligencji Azure w wersji 2.3.0 lub nowszej

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

Tworzenie i przesyłanie obrazu kontenera

1. Skompiluj obraz platformy Docker:

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

   Zobacz przykładowe pliki Dockerfile dla Python i C#.

2. Prześlij do Azure Container Registry:

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

Konfigurowanie uprawnień rejestru kontenerów

Udziel tożsamości zarządzanej projektu dostępu do pobierania obrazów.

1. W portalu Azure przejdź do zasobu projektu Foundry.

2. Wybierz Tożsamość i skopiuj identyfikator obiektu (podmiot) w obszarze Przypisane przez system.

3. Przypisz rolę Czytelnik repozytorium rejestru kontenerów do tej tożsamości w twoim rejestrze kontenerów. Zobacz Azure Container Registry role i uprawnienia.

Tworzenie wersji hostowanego agenta

Podczas tworzenia wersji platforma automatycznie udostępnia agenta. Nie ma oddzielnego kroku początkowego. Platforma tworzy migawkę kontenera i przygotowuje agenta do obsługi żądań.

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="2.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}")

Aby uwidocznić oba protokoły, przekaż oba w pliku protocol_versions:

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

Kluczowe parametry:

Aby ustawić czas bezczynności obliczeń sesji, zobacz Zarządzanie bezczynnością sesji.

Sonduj stan wersji

Po utworzeniu wersji monitoruj, aż stan zmieni się na active przed wywołaniem agenta. Konfigurowanie zwykle trwa mniej niż minutę w zależności od rozmiaru obrazu.

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)

Wartości stanu wersji:

Wywoływanie agenta

Po osiągnięciu active stanu wersji użyj polecenia get_openai_client , aby utworzyć klienta OpenAI powiązanego z punktem końcowym agenta.

Dla protokołu Odpowiedzi :

# 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)

W przypadku protokołu Invocations bezpośrednio wywołaj punkt końcowy wywołań.

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())

Aby zobaczyć bardziej kompletne przykłady, zobacz Przykłady hostowanych agentów.

Wdrażanie przy użyciu zestawu SDK .NET

Użyj zestawu SDK, aby zarządzać wdrożeniami agentów bezpośrednio z .NET kodu.

Dodatkowe wymagania wstępne

• zestaw SDK platformy .NET 10 lub nowszy

• Obraz kontenera w Azure Container Registry

• Rola zapisywania repozytorium usługi Container Registry lub AcrPush w rejestrze kontenerów (w celu wypychania obrazów)

• Zestaw SDK projektów sztucznej inteligencji Azure. Zainstaluj pakiet wstępnego wydania dla interfejsów API hostowanych agentów:

  dotnet add package Azure.AI.Projects --prerelease
  dotnet add package Azure.AI.Extensions.OpenAI
  dotnet add package Azure.Identity
  

Tworzenie i przesyłanie obrazu kontenera

1. Skompiluj obraz platformy Docker:

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

   Zobacz przykładowe pliki Dockerfile dla Python i C#.

2. Prześlij do Azure Container Registry:

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

Konfigurowanie uprawnień rejestru kontenerów

Udziel tożsamości zarządzanej projektu dostępu do pobierania obrazów.

1. W portalu Azure przejdź do zasobu projektu Foundry.

2. Wybierz Tożsamość i skopiuj identyfikator obiektu (podmiot) w obszarze Przypisane przez system.

3. Przypisz rolę Czytelnik repozytorium rejestru kontenerów do tej tożsamości w twoim rejestrze kontenerów. Zobacz Azure Container Registry role i uprawnienia.

Tworzenie wersji hostowanego agenta

Podczas tworzenia wersji platforma automatycznie udostępnia agenta. Nie ma oddzielnego kroku początkowego. Platforma tworzy migawkę kontenera i przygotowuje agenta do obsługi żądań.

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;

#pragma warning disable AAIP001

// Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
var projectEndpoint = "your_project_endpoint";

AIProjectClient projectClient = new(new Uri(projectEndpoint), new DefaultAzureCredential());
var agentsClient = projectClient.AgentAdministrationClient;

HostedAgentDefinition definition = new(cpu: "1", memory: "2Gi")
{
    Versions =
    {
        new ProtocolVersionRecord(ProjectsAgentProtocol.Responses, "2.0.0"),
    },
    ContainerConfiguration = new ContainerConfiguration("your-registry.azurecr.io/your-image:tag"),
};
definition.EnvironmentVariables.Add("MODEL_DEPLOYMENT_NAME", "gpt-4o");

ProjectsAgentVersion agent = agentsClient.CreateAgentVersion(
    "my-agent", new ProjectsAgentVersionCreationOptions(definition));
Console.WriteLine($"Agent created: {agent.Name}, version: {agent.Version}");

Aby uwidocznić więcej niż jeden protokół, dodaj więcej ProtocolVersionRecord wpisów:

Versions =
{
    new ProtocolVersionRecord(ProjectsAgentProtocol.Responses, "2.0.0"),
    new ProtocolVersionRecord(ProjectsAgentProtocol.Invocations, "2.0.0"),
    new ProtocolVersionRecord(ProjectsAgentProtocol.InvocationsWs, "2.0.0"),
},

Kluczowe parametry:

Aby ustawić czas bezczynności obliczeń sesji, zobacz Zarządzanie bezczynnością sesji.

Sonduj stan wersji

Po utworzeniu wersji monitoruj, aż stan zmieni się na Active przed wywołaniem agenta. Konfigurowanie zwykle trwa mniej niż minutę w zależności od rozmiaru obrazu.

while (true)
{
    ProjectsAgentVersion versionInfo = agentsClient.GetAgentVersion("my-agent", agent.Version);
    Console.WriteLine($"Status: {versionInfo.Status}");

    if (versionInfo.Status == AgentVersionStatus.Active)
    {
        Console.WriteLine("Agent is ready!");
        break;
    }

    if (versionInfo.Status == AgentVersionStatus.Failed)
    {
        Console.WriteLine("Provisioning failed.");
        break;
    }

    Thread.Sleep(TimeSpan.FromSeconds(5));
}

Wartości stanu wersji:

Wywoływanie agenta

Gdy wersja osiągnie stan Active, użyj GetProjectResponsesClientForAgentEndpoint, aby utworzyć klienta Responses połączonego z punktem końcowym agenta.

Dla protokołu Odpowiedzi :

using Azure.AI.Extensions.OpenAI;
using OpenAI.Responses;

#pragma warning disable OPENAI001

ProjectResponsesClient responsesClient = projectClient.ProjectOpenAIClient
    .GetProjectResponsesClientForAgentEndpoint("my-agent");

ResponseResult response = responsesClient.CreateResponse("Hello! What can you do?");
Console.WriteLine(response.GetOutputText());

W przypadku protokołu Invocations bezpośrednio wywołaj punkt końcowy wywołań.

using System.Net.Http.Json;
using Azure.Core;

var token = new DefaultAzureCredential()
    .GetToken(new TokenRequestContext(["https://ai.azure.com/.default"]))
    .Token;

using HttpClient http = new();
http.DefaultRequestHeaders.Authorization = new("Bearer", token);

var url = $"{projectEndpoint}/agents/my-agent/endpoint/protocols/invocations?api-version=v1";
HttpResponseMessage result = await http.PostAsJsonAsync(url, new { message = "Process this task" });
Console.WriteLine(await result.Content.ReadAsStringAsync());

Aby uzyskać więcej kompletnych przykładów, zobacz przykłady agentów hostowanych w języku C#.

Wdrażanie przy użyciu zestawu SDK języka JavaScript/TypeScript

Użyj zestawu SDK, jeśli chcesz zarządzać wdrożeniami agentów bezpośrednio z Node.js kodu. Kod wywołujący SDK działa w Node.js, ale sam obraz kontenera nadal uruchamia kod agenta w Pythonie lub .NET, zbudowany przy użyciu bibliotek protokołów Responses lub Invocations — nie ma hostowanego środowiska uruchomieniowego agenta dla Node.js.

Dodatkowe wymagania wstępne

• Node.js 22 lub nowszym

• Obraz kontenera w Azure Container Registry

• Rola zapisywania repozytorium usługi Container Registry lub AcrPush w rejestrze kontenerów (w celu wypychania obrazów)

• Pakiety @azure/ai-projects i @azure/identity

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

Przed rozpoczęciem skompiluj i prześlij obraz kontenera do usługi Azure Container Registry (zobacz przykładowe polecenia platformy Docker na karcie Python) oraz przypisz zarządzanej tożsamości projektu rolę Container Registry Repository Reader w rejestrze.

Tworzenie wersji hostowanego agenta

Podczas tworzenia wersji platforma automatycznie udostępnia agenta. Nie ma oddzielnego kroku początkowego. Platforma tworzy migawkę kontenera i przygotowuje agenta do obsługi żądań.

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: "2.0.0" }],
  environment_variables: { MODEL_DEPLOYMENT_NAME: "gpt-5-mini" },
});

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

Aby uwidocznić oba protokoły, przekaż oba w pliku protocol_versions:

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

Sonduj stan wersji

Po utworzeniu wersji monitoruj, aż stan zmieni się na active przed wywołaniem agenta. Konfigurowanie zwykle trwa mniej niż minutę w zależności od rozmiaru obrazu.

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);
}

Skieruj punkt końcowy agenta i wywołaj go

Skieruj punkt końcowy agenta do utworzonej wersji, a następnie przypisz klienta OpenAI do punktu końcowego.

Dla protokołu Odpowiedzi :

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);

W przypadku protokołu Invocations bezpośrednio wywołaj punkt końcowy wywołań.

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());

Dokumentacja: AIProjectClient

Wdrażanie przy użyciu interfejsu API REST

Użyj interfejsu API REST do bezpośrednich wdrożeń opartych na protokole HTTP lub podczas integracji z niestandardowymi narzędziami.

Przed rozpoczęciem skompiluj i wypchnij obraz kontenera do usługi Azure Container Registry oraz przyznaj zarządzanej tożsamości projektu rolę Container Registry Repository Reader w rejestrze.

Konfigurowanie zmiennych

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)

Tworzenie agenta

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": "2.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

Utworzenie agenta powoduje również utworzenie wersji 1 i uruchomienie aprowizacji.

Aby ustawić czas bezczynności obliczeń sesji, zobacz Zarządzanie bezczynnością sesji.

Aby sprawdzać prompty i odpowiedzi pod kątem zasad bezpieczeństwa treści, dołącz obiekt rai_config do obiektu definition. Zobacz Dodawanie bariery bezpieczeństwa zawartości do hostowanego agenta.

Sonduj stan wersji

Odpytuj punkt końcowy wersji, aż status ma wartość 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

Wywoływanie agenta

Użyj dedykowanego punktu końcowego agenta do wysyłania żądań. Ustaw "stream": true do odbierania zdarzeń wysyłanych przez serwer.

Protokół odpowiedzi:

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
  }'

Protokół wywołań:

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"
  }'

Tworzenie nowej wersji

Wdróż zaktualizowany kod lub konfigurację, tworząc nową wersję:

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": "2.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

czyszczenie Azure Developer CLI

azd down

Oczyszczanie zestawu SDK

Usuń jedną wersję:

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

Możesz też usunąć całego agenta i wszystkie jego wersje. Użyj force=True, aby kaskadowo usunąć aktywne sesje, na przykład zaraz po wywołaniu agenta; bez niego wywołanie kończy się błędem konfliktu, gdy aktywne są sesje:

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

Oczyszczanie zestawu SDK

Usuń jedną wersję:

agentsClient.DeleteAgentVersion("my-agent", agent.Version);

Możesz też usunąć całego agenta i wszystkie jego wersje. Użyj force: true, aby kaskadowo usunąć wszystkie aktywne sesje, na przykład bezpośrednio po wywołaniu agenta. Bez niego wywołanie kończy się niepowodzeniem z powodu błędu powodującego konflikt, gdy sesje są aktywne:

agentsClient.DeleteAgent("my-agent", force: true);

Oczyszczanie zestawu SDK

Usuń jedną wersję:

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

Możesz też usunąć całego agenta i wszystkie jego wersje:

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

Dokumentacja: AIProjectClient

Oczyszczanie interfejsu API REST

Usuń jedną wersję:

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

Możesz też usunąć całego agenta:

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