Distribuera en värdbaserad agent

Distribuera med hjälp av Azure Developer CLI eller VS Code

AZURE Developer CLI (azd) och Microsoft Foundry Toolkit för Visual Studio Code automatisera hela distributionslivscykeln: skapa containern, push-överföra den till Azure Container Registry, skapa agentversionen och tilldela RBAC-roller. En guidad genomgång för första gången finns i Snabbstart: Skapa och distribuera en värdbaserad agent.

Distribuera med ett kommando

Från din agentprojektkatalog etablerar du infrastruktur och distribuerar i ett enda steg:

azd up

azd up kombinerar azd provision, som skapar Foundry-projektet, modelldistributionen, containerregistret, Application Insights och den hanterade identiteten med azd deploy. Använd den för första gången distributioner eller när du ändrar både infrastruktur och agentkod.

Endast distribuera kodändringar

Om du redan har etablerat dina Azure resurser och bara behöver skicka en ny agentversion:

azd deploy

Under azd deploy kommer CLI:n att:

1. Skapar containeravbildningen via fjärranslutning i Azure Container Registry, så du behöver inte lokal Docker.
2. Skickar avbilden till registret.
3. Skapar en värdbaserad agentversion på Foundry Agent Service.
4. Skapar en dedikerad Microsoft Entra agentidentitet och tilldelar de RBAC-roller som agenten behöver för att komma åt modeller och verktyg.

Hantera versioner

Varje azd deploy skapar en ny version av agenten. CLI bevarar tidigare versioner och den senaste versionen är aktiv som standard.

Verifiera driftsättningen

azd ai agent show

Utdata innehåller agentnamn, version, protokoll, containerresurser, miljövariabler och tidsstämpel för skapande. Använd --output table för sammanfattningsvy.

Skapa avbildningar lokalt

Som standard bygger azd containeravbilder på distans i Azure Container Registry. Om du vill skapa avbildningar lokalt anger du remoteBuild: false i azure.yaml. Lokala versioner kräver Docker Desktop.

För att granska uppmaningar och svar mot en policy för innehållssäkerhet lägger du till ett skyddsräcke för innehållssäkerhet i din agent.

Distribuera med hjälp av Python SDK

Använd SDK när du vill hantera agentdistributioner direkt från Python kod.

Ytterligare förutsättningar

• Python 3.10 eller senare

• En containeravbildning i Azure Container Registry

• Container Registry Repository Writer eller AcrPush-rollen i containerregistret (för att skicka avbildningar)

• Azure AI Projects SDK version 2.3.0 eller senare

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

Skapa och push-överföra containeravbildningen

1. Skapa docker-avbildningen:

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

   Se Dockerfiles-exempel för Python och C#.

2. Push-överför till Azure Container Registry:

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

Konfigurera behörigheter för containerregister

Ge projektets hanterade identitet åtkomst för att hämta bilder:

1. I Azure-portalen går du till din Foundry-projektresurs.

2. Välj Identitet och kopiera objekt-ID (huvudnamn) under Systemtilldelad.

3. Tilldela rollen Container Registry Repository Reader till den här identiteten i containerregistret. Se Azure Container Registry roller och behörigheter.

Skapa en värdbaserad agentversion

När du skapar en version etablerar plattformen automatiskt agenten. Det finns inget separat startsteg. Plattformen skapar en ögonblicksbild av containern och gör agenten redo att hantera begäranden.

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

Om du vill exponera båda protokollen skickar du båda i 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"),
],

Nyckelparametrar:

Information om hur du anger när sessionsberäkningen blir inaktiv finns i Hantera sessionsinaktivitet.

Sök efter versionsstatus

När du har skapat en version, kontrollera regelbundet tills statusen är active innan du anropar agenten. Konfigureringen tar vanligtvis mindre än en minut beroende på bildstorleken.

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)

Versionsstatusvärden:

Anropa agenten

När versionen har nått active status använder du get_openai_client för att skapa en OpenAI-klient som är bunden till agentens slutpunkt.

För protokollet Svar :

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

För protokollet Anrop anropar du slutpunkten för anrop direkt:

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

Mer fullständiga exempel finns i exemplen på värdbaserad agent.

Distribuera med JavaScript/TypeScript SDK

Använd SDK när du vill hantera agentdistributioner direkt från Node.js kod. SDK-anroparen körs i Node.js, men själva containeravbildningen kör fortfarande din Python- eller .NET agentkod som skapats med protokollbiblioteken Svar eller anrop – det finns ingen Node.js värdbaserad agentkörning.

Ytterligare förutsättningar

• Node.js 22 eller senare

• En containeravbildning i Azure Container Registry

• Container Registry Repository Writer eller AcrPush-rollen i containerregistret (för att skicka avbildningar)

• Paketen @azure/ai-projects och @azure/identity

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

Innan du börjar skapar och överför du containeravbildningen till Azure Container Registry (se fliken Python för exempel på Docker-kommandon) och beviljar projektets hanterade identitet rollen Container Registry Repository Reader på registret.

Skapa en värdbaserad agentversion

När du skapar en version etablerar plattformen automatiskt agenten. Det finns inget separat startsteg. Plattformen skapar en ögonblicksbild av containern och gör agenten redo att hantera begäranden.

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

Om du vill exponera båda protokollen skickar du båda i protocol_versions:

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

Sök efter versionsstatus

När du har skapat en version, kontrollera regelbundet tills statusen är active innan du anropar agenten. Konfigureringen tar vanligtvis mindre än en minut beroende på bildstorleken.

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

Dirigera agentslutpunkten och anropa den

Dirigera agentslutpunkten till den version som du skapade och bind sedan en OpenAI-klient till slutpunkten.

För protokollet Svar :

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

För protokollet Anrop anropar du slutpunkten för anrop direkt:

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

Referens: AIProjectClient

Distribuera med REST API:et

Använd REST-API:et för direkta HTTP-baserade distributioner eller när du integrerar med anpassade verktyg.

Innan du börjar, bygg och pusha din containeravbildning till Azure Container Registry och tilldela projektets hanterade identitet rollen Container Registry Repository Reader för registret.

Konfigurera variabler

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)

Skapa en agent

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

När du skapar en agent skapas även version 1 och provisionering initieras.

Information om hur du anger när sessionsberäkningen blir inaktiv finns i Hantera sessionsinaktivitet.

Om du vill skärma uppmaningar och svar mot en innehållssäkerhetsprincip inkluderar du ett rai_config objekt i definition. Se Lägga till ett skyddsräcke för innehåll till en värdbaserad agent.

Sök efter versionsstatus

Kontrollera versionsslutpunkten tills status är 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

Anropa agenten

Använd agentens dedikerade slutpunkt för att skicka begäranden. Ange "stream": true för att ta emot server-skickade händelser.

Svarsprotokoll:

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

Anropsprotokoll:

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

Skapa en ny version

Distribuera uppdaterad kod eller konfiguration genom att skapa en ny version:

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 CLI-rensning för utvecklare

azd down

SDK-rensning

Ta bort en enskild version:

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

Eller ta bort hela agenten och alla dess versioner. Använd force=True för att ta bort aktiva sessioner, till exempel direkt efter att du anropat agenten. Utan det misslyckas anropet med ett konfliktfel medan sessioner är aktiva:

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

SDK-rensning

Ta bort en enskild version:

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

Eller ta bort hela agenten och alla dess versioner:

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

Referens: AIProjectClient

REST API-rensning

Ta bort en enskild version:

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

Eller ta bort hela agenten:

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