Een gehoste agent implementeren

Implementeren met behulp van de Azure Developer CLI of VS Code

De Azure Developer CLI (azd) en de Microsoft Foundry Toolkit voor Visual Studio Code de volledige levenscyclus van de implementatie automatiseren: de container bouwen, naar Azure Container Registry pushen, de agentversie maken en RBAC-rollen toewijzen. Zie de quickstart: Een gehoste agent maken en implementeren voor een stapsgewijze handleiding voor de eerste keer.

Implementeren met één opdracht

Richt vanuit uw agentprojectmap de infrastructuur in en implementeer deze in één stap:

azd up

azd up combineert azd provision, waarmee het Foundry-project, modelimplementatie, containerregister, Application Insights en beheerde identiteit wordt gemaakt, met azd deploy. Gebruik deze voor de eerste implementaties of wanneer u zowel infrastructuur- als agentcode wijzigt.

Alleen codewijzigingen implementeren

Als u uw Azure resources al hebt ingericht en u alleen een nieuwe agentversie hoeft te pushen:

azd deploy

Tijdens azd deploy voert de CLI het volgende uit:

1. Bouwt uw containerimages extern in Azure Container Registry, zodat u Docker niet lokaal nodig hebt.
2. Pusht de image naar de registry.
3. Hiermee maakt u een gehoste agentversie op Foundry Agent Service.
4. Hiermee maakt u een toegewezen Microsoft Entra agentidentiteit en wijst u de RBAC-rollen toe die de agent nodig heeft voor toegang tot modellen en hulpprogramma's.

Versies beheren

Elk azd deploy maakt een nieuwe versie van de agent. De CLI behoudt eerdere versies en de nieuwste versie is standaard actief.

De implementatie controleren

azd ai agent show

De uitvoer bevat de agentnaam, versie, protocollen, containerbronnen, omgevingsvariabelen en aanmaaktijdstempel. Gebruiken --output table voor een overzichtsweergave.

Images lokaal bouwen

Standaard bouwt azd containerimages op afstand in Azure Container Registry. Als u lokaal images wilt bouwen, stelt u remoteBuild: false in in azure.yaml. Voor lokale builds is Docker Desktop vereist.

Als u vragen en antwoorden wilt screenen op basis van een beleid voor inhoudsveiligheid, voegt u een veiligheidsbeschermingsrail voor inhoud toe aan uw agent.

Implementeren met behulp van de Python SDK

Gebruik de SDK wanneer u agentimplementaties rechtstreeks vanuit Python code wilt beheren.

Aanvullende vereisten

• Python 3.10 of hoger

• Een containerimage in Azure Container Registry

• De rol van Container Registry Repository Writer of AcrPush in het containerregister (om afbeeldingen te pushen)

• Azure AI Projects SDK versie 2.3.0 of hoger

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

Uw containerinstallatiekopieën bouwen en pushen

1. Bouw uw Docker-image:

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

   Zie voorbeeld-Dockerfiles voor Python en C#.

2. Pushen naar Azure Container Registry:

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

Containerregistermachtigingen configureren

Verleent de beheerde identiteit van uw project toegang tot het ophalen van afbeeldingen.

1. Ga in de Azure-portal naar je Foundry-projectresource.

2. Selecteer Identiteit en kopieer de object-id (principal) onder Toegewezen systeem.

3. Wijs de rol Lezer van containerregisteropslagplaats toe aan deze identiteit in uw containerregister. Zie Azure Container Registry rollen en machtigingen.

Een gehoste agentversie maken

Wanneer u een versie maakt, richt het platform de agent automatisch in. Er is geen afzonderlijke beginstap. Het platform bouwt een momentopname van een container en maakt de agent gereed voor het verwerken van aanvragen.

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

Als u beide protocollen beschikbaar wilt maken, geeft u beide door: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"),
],

Belangrijkste parameters:

Zie Sessie-inactiviteit beheren om in te stellen wanneer de rekenkracht van de sessie inactief wordt.

Poll voor versiestatus

Nadat u een versie hebt gemaakt, wacht u totdat de status active is voordat u de agent activeert. Het inrichten duurt doorgaans minder dan één minuut, afhankelijk van de grootte van de afbeelding.

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)

Versiestatuswaarden:

De agent aanroepen

Nadat de versie de status active heeft bereikt, gebruikt u get_openai_client om een OpenAI-client te maken die is verbonden met het eindpunt van de agent.

Voor het protocol Antwoorden :

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

Voor het protocol Aanroepen roept u het eindpunt voor aanroepen rechtstreeks aan:

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

Zie de voorbeelden van gehoste agents voor uitgebreidere voorbeelden.

Implementeren met behulp van de JavaScript/TypeScript SDK

Gebruik de SDK als u agentimplementaties rechtstreeks vanuit Node.js code wilt beheren. De SDK-aanroeper wordt uitgevoerd in Node.js, maar de containerinstallatiekopie zelf voert nog steeds uw Python- of .NET agentcode uit die is gebouwd met de protocolbibliotheken voor antwoorden of aanroepen. Er is geen Node.js runtime voor gehoste agent.

Aanvullende vereisten

• Node.js 22 of hoger

• Een containerimage in Azure Container Registry

• De rol van Container Registry Repository Writer of AcrPush in het containerregister (om afbeeldingen te pushen)

• De @azure/ai-projects en @azure/identity pakketten

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

Voordat u begint, bouwt u uw containerinstallatiekopie en pusht u deze naar Azure Container Registry (zie het tabblad Python voor voorbeelden van Docker-opdrachten), en verleent u de beheerde identiteit van het project de rol Container Registry Repository Reader voor het register.

Een gehoste agentversie maken

Wanneer u een versie maakt, richt het platform de agent automatisch in. Er is geen afzonderlijke beginstap. Het platform bouwt een momentopname van een container en maakt de agent gereed voor het verwerken van aanvragen.

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

Als u beide protocollen beschikbaar wilt maken, geeft u beide door:protocol_versions

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

Poll voor versiestatus

Nadat u een versie hebt gemaakt, wacht u totdat de status active is voordat u de agent activeert. Het inrichten duurt doorgaans minder dan één minuut, afhankelijk van de grootte van de afbeelding.

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

Het eindpunt van de agent routeren en aanroepen

Routeer het agenteindpunt naar de versie die u hebt gemaakt en bind vervolgens een OpenAI-client aan het eindpunt.

Voor het protocol Antwoorden :

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

Voor het protocol Aanroepen roept u het eindpunt voor aanroepen rechtstreeks aan:

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

Referentie: AIProjectClient

Implementeren met behulp van de REST API

Gebruik de REST API voor directe HTTP-implementaties of bij het integreren met aangepaste hulpprogramma's.

Voordat u begint, bouwt en pusht u uw containerinstallatiekopie naar Azure Container Registry en verleent u de beheerde identiteit van het project de rol Container Registry Repository Reader op het register.

Variabelen instellen

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)

Een agent maken

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

Het maken van een agent maakt ook versie 1 en activeert provisioning.

Zie Sessie-inactiviteit beheren om in te stellen wanneer de rekenkracht van de sessie inactief wordt.

Als u prompts en antwoorden wilt screenen op basis van een beleid voor inhoudsveiligheid, moet u een rai_config object opnemen in de definition. Zie Een veiligheidsbeschermingsrail voor inhoud toevoegen aan een gehoste agent.

Poll voor versiestatus

Controleer het versie-eindpunt totdat statusactive:

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

De agent aanroepen

Gebruik het toegewezen eindpunt van de agent om aanvragen te verzenden. Stel "stream": true in om door de server verzonden gebeurtenissen te ontvangen.

Antwoordprotocol:

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

Protocol voor aanroepen:

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

Een nieuwe versie maken

Bijgewerkte code of configuratie implementeren door een nieuwe versie te maken:

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 opschonen

azd down

SDK opschoning

Eén versie verwijderen:

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

Of verwijder de volledige agent en alle bijbehorende versies. Gebruik force=True om actieve sessies in cascade te verwijderen, bijvoorbeeld direct nadat u de agent hebt aangeroepen; zonder dit mislukt de aanroep met een conflictfout terwijl er actieve sessies zijn:

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

SDK opschoning

Eén versie verwijderen:

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

Of verwijder de volledige agent en alle bijbehorende versies:

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

Referentie: AIProjectClient

REST API opschonen

Eén versie verwijderen:

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

Of verwijder de hele agent:

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