Üzemeltetett ügynök üzembe helyezése forráskódból

Ez a cikk bemutatja, hogyan helyezhet üzembe Hosted ügynököt az Foundry Agent Service-ben Python vagy .NET forráskódból tárolólemezkép létrehozása vagy elküldése nélkül. Feltölt egy .zip kódot (és opcionálisan a függőségeit), és az Agent Service vagy futtatja as-is, vagy létrehozza a függőségeit a felhőben.

Tipp:

A legtöbb forgatókönyv esetében a Azure Fejlesztői parancssori felület (azd) vagy a VS Code-hoz készült Foundry Toolkit használatával telepíthet. Ezek az eszközök elvégzik Ön helyett a munka dandárját: becsomagolják a forrást, feltöltik, lekérdezik a active állapotát, és automatikusan konfigurálják a szerepköralapú hozzáférés-szabályozást. A kezdéshez kövesse a Rövid útmutató: Az első üzemeltetett ügynök üzembe helyezése című útmutatót, és válassza a Kód (vagy Forráskód (ZIP-feltöltés)) lehetőséget, amikor a rendszer a telepítési módszert kéri.

Az ebben a cikkben szereplő SDK- és REST-eljárásokat akkor érdemes használnia, ha a forráskód-ügynököket programozott módon kell üzembe helyeznie – a Python SDK-ból vagy .NET SDK-ból a saját alkalmazásaiban, vagy közvetlenül a REST API-n keresztül egyéni eszközhasználathoz, nyelvi-agnosztikus automatizáláshoz vagy meglévő folyamatos kézbesítési rendszerekkel való integrációhoz. Ebben a cikkben a következő feladatokat hajtja végre:

  • Válasszon függőségfeloldási módot , és csomagolja be a forrást.
  • Hozza létre az ügynököt, várja meg, amíg el nem éri a active értéket, majd indítsa el.
  • Frissítse, verziószámozza, töltse le és streamelje az üzembe helyezett ügynök naplóit.

Ha teljes mértékben szabályoznia kell a futtatókörnyezet rendszerképét, vagy már rendelkezik működő Dockerfile-fájlokkal, használja a tárolóalapú elérési utat: Üzemeltetett ügynök üzembe helyezése.

Ha olyan kódolóügynököt használ, mint a GitHub Copilot a forráskód csomagolásához és üzembe helyezéséhez, a Microsoft Foundry skill segíthet a projekt előkészítésében és a szükséges azdSDK- vagy REST-lépések követésében.

Prerequisites

  • pip Python 3.13-at vagy újabb verziót, hogy helyileg csomagolja be a forrást.

  • A azure-ai-projects 2.2.0 vagy újabb verziója és a azure-identity csomagok.

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

Támogatott futtatókörnyezetek

Az code_configuration.runtime ügynökdefiníció mezője a következő értékeket fogadja el. Válassza ki a zipben található bináris fájloknak megfelelő futtatókörnyezetet: Pythonhoz Linux x86_64 wheels, illetve .NET-hez a TargetFramework kimenetének dotnet publish-ja.

Nyelv Futásidejű értékek
Python python_3_13, python_3_14
.NET dotnet_10

Nyelvi verzió támogatási szabályzata

Az Agent Service futtatókörnyezete tartalmazza a platform által létrehozott tárolóképet code_configuration.runtime minden egyes értékéhez. A telepített ügynökök teljes körű támogatásának fenntartása érdekében a Foundry a hosztolt ügynökök nyelvi támogatását az egyes nyelvek életciklus végi támogatásához igazítja. A támogatás a nyelvi verzió közösségi támogatás megszűnésének dátumával fejeződik be. Microsoft visszavonhat egy code_configuration.runtime értéket korábban, amikor a platformkorlátozások (például az alapul szolgáló alaprendszerkép) megkövetelik.

A támogatás megszűnésének upstream ütemterveiért lásd:

Kivonási fázis

A nyelv lejárati dátuma után továbbra is létrehozhat, frissíthet és futtathat üzemeltetett ügynököket, amelyek a kivezetett futtatókörnyezeti értéket használják. Ezek az ügynökök azonban nem jogosultak a támogatásra, az új funkciókra vagy a biztonsági javításokra, amíg nem frissíti őket egy támogatott futtatókörnyezetre egy aktuális code_configuration.runtime érték beállításával és ismételt üzembe helyezésével.

Szükséges engedélyek

A hosztolt ügynök telepítéséhez a projekt hatókörében a Foundry Project Manager szerepkörre van szüksége. Ez a szerepkör biztosítja az adatsík-engedélyeket az ügynökök létrehozásához és frissítéséhez, valamint lehetővé teszi a szerepkör-hozzárendelések létrehozását a platform által létrehozott ügynökidentitáshoz, ha szükséges. Az érintett engedélyek részletes lebontásához tekintse meg az üzemeltetett ügynök engedélyeinek hivatkozását.

Important

Az Foundry RBAC-szerepköröket nemrég átnevezték. Foundry user, Foundry Owner, Foundry-fióktulajdonos és Foundry Project Manager korábban Azure AI-felhasználónak, Azure AI-tulajdonosnak, Azure AI-fióktulajdonosnak és Azure AI-Project-kezelőnek hívták. Előfordulhat, hogy egyes helyeken továbbra is a korábbi nevek jelennek meg, miközben az átnevezést fokozatosan bevezetik. A szerepkör-azonosítók és az alapvető jogosultságok az átnevezés miatt nem változnak.

Az ügynök platformhoz rendelt felügyelt identitásként fut, amely nem azonos a felhasználói identitással. Ez az identitás alapértelmezés szerint hozzáfér a modell következtetéséhez a projektvégponton és a munkamenet-tárolón keresztül. Külső erőforrásokhoz (például a saját Azure Storage-erőforrásához) manuálisan rendeljen hozzá RBAC-szerepköröket az ügynök Microsoft Entra ID-jához. További információ: Ügynökhozzáférés az alapértelmezett beállításokon túl.

Üzembe helyezés életciklusa

Minden forráskód üzembe helyezése ugyanazt a sorrendet követi: csomagolás -> létrehozás vagy frissítés -> lekérdezés addig, amíg active -> meghívás. A forráskód elérési útja az ügynök definíciójában használja a code_configuration elemet. A képalapú elérési út ehelyett a(z) container_configuration elemet használja. Ez a két lehetőség egyetlen verzión belül kizárja egymást.

Válassza ki a munkafolyamatnak megfelelő elérési utat. Ha nem biztos benne, kezdje a Azure fejlesztői parancssori felülettel vagy a VS Code-tal – ez a legtöbb ügyfél számára ajánlott elérési út.

Útvonal Legjobb a számára Csomagolás
Azure fejlesztői parancssori felület vagy VS Code A legtöbb üzembe helyezés, beleértve az első üzembe helyezéseket és a leggyorsabb belső hurkot. Az eszközök létrehozzák és feltöltik a ZIP-fájlt.
Python SDK Programozott üzembe helyezés Python alkalmazásokból vagy automatizálásból. Elkészítheti a zip-et; az SDK feltölti.
.NET SDK Programozott üzembe helyezés .NET alkalmazásokból vagy automatizálásból. Az SDK tömörít egy mappát.
JavaScript/TypeScript SDK Programozott üzembe helyezés Node.js alkalmazásokból vagy automatizálásból. Üzembe helyezi Python vagy .NET forrást; nincs Node.js üzemeltetett futtatókörnyezet. Elkészítheti a zip-et; az SDK feltölti.
REST API Egyéni eszközök, nyelvi-agnosztikus automatizálás és CD-rendszerek. Elkészítheti a zip-et, és elküldheti a többrészes kérelmet.

Függőségek megoldásának kiválasztása

Mielőtt hozzákezd, válasszon egy értéket a következőhöz code_configuration.dependency_resolution: . Ez a döntés befolyásolja, hogy mit tesz a ZIP-fájlba.

Érték Magatartás Használja amikor
remote_build Az Agent Service az üzembe helyezés során telepíti a függőségeket a(z) requirements.txt helyről (Python), illetve visszaállítja a .NET-projektfájlt. Kis feltöltési igényt és a lehető legegyszerűbb belső ciklust szeretné. Ajánlott az első felhasználók számára.
bundled A ZIP-fájl változtatás nélkül fut. Előre összeállított Linux-függőségeket packages/ (Python) vagy dotnet publish kimenetben (.NET) szállíthat. Reprodukálható összeállításokra van szüksége, a függőségei privátak vagy csak wheel csomagok érhetők el, illetve a projektje nem állítható helyre tisztán a kiszolgálón.

Kötegelt mód esetén a helyi buildparancsokat lásd itt: A zip manuális becsomagolása.

A magán virtuális hálózatok tűzfalkövetelményei

Ha privát virtuális hálózattal védi a projektet, frissítse a hálózati házirendet, hogy az üzembe helyezés előtt engedélyezze a kimenő kapcsolatokat az alábbi végpontokhoz.

Minden forráskód-üzembe helyezéshez kimenő hozzáférés szükséges a következőhöz:

  • mcr.microsoft.com
  • *.login.microsoft.com

A Foundry hosztolási könyvtárait (például azure-ai-agentserver-core vagy agent-framework-foundry-hosting) használó ügynökkód az ügynöktől származó telemetriai adatokat is küld. Engedélyezze ezeket a végpontokat, hogy a nyomkövetési adatok ne vesszenek el:

A hálózati konfigurációval kapcsolatban lásd: Üzemeltetett ügynök üzembe helyezése virtuális hálózaton.

Üzembe helyezés az Azure Developer CLI vagy a VS Code használatával

A Azure fejlesztői parancssori felület (azd) és a VS Code-hoz készült Foundry Toolkit automatizálja a teljes forráskód üzembehelyezési életciklusát – a forrást zip-be csomagolják, kiszámítják az SHA-256-ot, feltöltik, lekérdezik active, és konfigurálják a szerepköralapú hozzáférés-vezérlést. Ezek az eszközök jelentik a legtöbb ügyfél számára ajánlott megoldást, valamint a leggyorsabb iterációs ciklust.

Részletes útmutatót az első üzemeltetett ügynök üzembe helyezése című rövid útmutatóban talál. Válassza a Kód (vagy a forráskód (ZIP-feltöltés)) lehetőséget, amikor a gyorsútmutató a telepítési módot kéri.

Forráskód üzembe helyezésének kiválasztása

Interaktív futtatás azd ai agent init esetén az eszköz megkéri, hogy válasszon egy üzembe helyezési módot. A tárolólemezkép létrehozása helyett válassza ki a forrásból zip-feltöltésként üzembe helyezendő kódot . A kódtelepítés a Python és .NET üzemeltetett ügynökök alapértelmezett módja. A VS Code-hoz készült Foundry Toolkit ugyanígy kéri az üzembe helyezési módszert.

A forráskódalapú üzembe helyezés nem interaktív kiválasztásához, például egy CI/CD-folyamatban, adja meg a(z) --deploy-mode code paramétert. Ez a mód megköveteli a(z) --runtime és --entry-point elemeket, és elfogad egy opcionális --dep-resolution értéket, amelynek értéke remote_build (alapértelmezett) vagy bundled lehet:

azd ai agent init --no-prompt --project-id "<project-resource-id>" \
  --deploy-mode code --runtime python_3_13 --entry-point main.py

Az inicializálás után a azd a codeConfiguration található azure.ai.agent szolgáltatás azure.yaml mezőjébe írja a forráskód üzembehelyezési beállításait:

services:
  my-agent:
    host: azure.ai.agent
    project: src/my-agent
    kind: hosted
    codeConfiguration:
      runtime: python_3_13
      entryPoint:
        - python
        - main.py
      dependencyResolution: remote_build

Futtassa a azd up a kiépítéshez és üzembe helyezéséhez. Csak akkor használja a --deploy-mode container elemet, ha ehelyett konténerképet szeretne létrehozni vagy hivatkozni rá.

A következő szakaszokban az SDK- vagy REST-útvonalakat használhatja, ha programozott módon kell üzembe helyeznie a saját alkalmazását, vagy integrálnia kell a meglévő eszközkészlettel.

Üzembe helyezés forráskódból

Válassza ki a nyelvet vagy a felületet. Mindegyik fül ugyanazon az életcikluson megy végig: az ügynök létrehozása, állapotának ismételt lekérdezése, amíg el nem éri a active állapotot, meghívása és a telepített kód letöltése.

A Python SDK-val forráskódügynököket helyezhet üzembe saját alkalmazásaiból vagy automatizálásából. A zip-et saját maga hozhatja létre, és a bájtjait és az SHA-256-ot átadja az SDK-nak, amely feltölti, és ugyanazokat a létrehozási, lekérdezési, meghívási és letöltési műveleteket teszi elérhetővé, mint a REST API. A kódtelepítéshez a 2.2.0-s vagy újabb verzió szükséges azure-ai-projects .

Hozza létre a ZIP-fájlt

A Python SDK feltölt egy ön által létrehozott zip-et. Használja a zip manuális csomagolásában leírt elrendezési és függőségfeloldási szabályokat. A minimális remote_build csomag egy egyszintű ZIP-fájl, amelynek gyökérkönyvtárában a main.py és a requirements.txt található.

Az ügynök létrehozása

import hashlib
from pathlib import Path

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

# Format: "https://<account>.services.ai.azure.com/api/projects/<project>"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "my-code-agent"
ZIP_PATH = Path("agent-code.zip")

code_zip_bytes = ZIP_PATH.read_bytes()
code_zip_sha256 = hashlib.sha256(code_zip_bytes).hexdigest()

credential = DefaultAzureCredential()
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=credential,
)

created = project.agents.create_version_from_code(
    agent_name=AGENT_NAME,
    definition=HostedAgentDefinition(
        cpu="1",
        memory="2Gi",
        code_configuration=CodeConfiguration(
            runtime="python_3_13",
            entry_point=["python", "main.py"],
            dependency_resolution="remote_build",
        ),
        protocol_versions=[
            ProtocolVersionRecord(protocol="responses", version="2.0.0")
        ],
        environment_variables={"AZURE_AI_MODEL_DEPLOYMENT_NAME": "gpt-5.4-mini"},
    ),
    code=(ZIP_PATH.name, code_zip_bytes, "application/zip"),
    code_zip_sha256=code_zip_sha256,
    description="Hello-world code agent",
)
print(f"Created version: {created.version}")

Az Invocations protokoll esetében állítsa a protocol_versions bejegyzést ProtocolVersionRecord(protocol="invocations", version="2.0.0") értékre. Az Invocations (WebSocket) protokollhoz használja a következőt ProtocolVersionRecord(protocol="invocations_ws", version="2.0.0"): . A(z) bundled módhoz állítsa be a(z) dependency_resolution="bundled" értéket, és vegye bele az előre összeállított függőségeket a zip-fájlba. További információ: Linux-függőségek helyi létrehozása.

Lekérdezés az aktív állapotra

import time

while True:
    version = project.agents.get_version(
        agent_name=AGENT_NAME, agent_version=created.version
    )
    status = version["status"]
    print(f"Status: {status}")
    if status == "active":
        break
    if status == "failed":
        raise RuntimeError(f"Provisioning failed: {version.get('error')}")
    time.sleep(5)

Lásd: Poll for active a státuszértékek teljes listájáért, valamint azért, hogy hiba esetén hogyan kell értelmezni a error objektumot.

Az ügynök meghívása

Miután a verzió eléri a active értéket, kössön egy OpenAI-klienst az ügynök végpontjához, és hívja meg. Ez a példa a Responses protokollt használja:

openai_client = project.get_openai_client(agent_name=AGENT_NAME)

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

Az Invocations protokoll esetében hívja meg közvetlenül az invoke-végpontot egy bearer tokennel, ahogy az a Ügynök meghívása című részben látható.

A telepített ZIP-fájl letöltése

A ZIP-fájl letöltésével, majd a SHA-256 ellenőrzőösszegének az Ön által feltöltött értékkel való összehasonlításával ellenőrizze, hogy pontosan mi került üzembe helyezésre:

import hashlib
from pathlib import Path

out_path = Path(f"{AGENT_NAME}-{created.version}.zip")
sha = hashlib.sha256()
with open(out_path, "wb") as f:
    for chunk in project.agents.download_code(
        agent_name=AGENT_NAME, agent_version=created.version
    ):
        f.write(chunk)
        sha.update(chunk)

print(f"Downloaded {out_path} (matches upload: {sha.hexdigest() == code_zip_sha256})")

A teljes, futtatható példáért lásd a Pythonhoz készült üzemeltetettügynök-mintákat.

Csomagolja be manuálisan a ZIP-fájlt

Ha használja azd, hagyja ki ezt a szakaszt, ésazd hozza létre a zip-et. Olvassa el, ha a REST API-t használja, ha csomagalapú függőségfeloldásra vált, vagy ha teljes mértékben szabályoznia kell a feltöltés tartalmát.

A zip-nek laposnak kell lennie a gyökérnél – nincs legfelső szintű burkolómappa.

Válassza ki az ügynök nyelvének fülét.

Python elrendezés (távoli buildelési mód)

A szolgáltatás a felhőben a(z) requirements.txt helyről telepíti a függőségeket.

agent-code.zip
+-- main.py
+-- requirements.txt

Python elrendezés (csomagolt mód)

Előre összeállított Linux-függőségeket szállít a(z) packages/ helyen.

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

Linux-függőségek helyi létrehozása (csomagban, Python)

Használja a manylinux2014_x86_64 platformcímkét, hogy pip linuxos kerekeket töltsön le Windows vagy macOS rendszerről is.

Bash

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/

PowerShell / Windows parancssor

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: kerekek kényszerítése (nincsenek forrás buildek). Ennek --python-version meg kell egyeznie az runtime ügynökdefinícióban szereplő értékkel.

Warning

Gyakori csomagolási hibák, amelyek session_creation_failed vagy ModuleNotFoundError okoznak:

  • A forrás mappába helyezése (my-agent/main.py a gyökérben lévő main.py helyett).
  • Beleértve a nyers .whl fájlokat a packages/ fájlban a kinyert modulok helyett.
  • Windows bináris fájlok (.pyd, .dll) összekapcsolása Linux-futtatókörnyezetekhez.

Limits

Limit Érték
Maximális zip-méret (többrészes feltöltés) 250 MB

A támogatott cpu és memory a kombinációkkal kapcsolatban lásd a tesztkörnyezet méreteit.

Hibaelhárítás

Hibajelenség Valószínű ok Javítás
401 Unauthorized Hiányzó vagy hibás hatókörű token Szerezzen be egy tokent a(z) --resource https://ai.azure.com használatával.
403 Forbidden A hívó fél nem rendelkezik szerepköralapú hozzáférés-szabályozási jogosultsággal a projekthez. Adjon Foundry Agent Consumer (csak meghíváshoz) vagy Foundry User (fejlesztéshez is) szerepkört projekt szinten.
409 conflict létrehozás (Agent '<name>' already exists) Az ügynök neve már létezik Használja a Frissítés (POST /agents/{name}) elemet, vagy válasszon egy új nevet.
400 bad_request (CPU and Memory must be specified as a valid resource tier) létrehozás vagy frissítés esetén cpu / memory nem a támogatott szintek egyike Állítsa a(z) cpu és memory értékét a Sandbox-méretek közül egy érvényes párra.
400 bad_request (Agent version is still being provisioned) meghíváskor Egy új verzió telepítése folyamatban van, és az aktív verzió cseréje éppen zajlik. Kérdezze le a verziót status, amíg active, majd próbálja újra.
424 session_not_ready meghíváskor A tároló elindult, de /readiness nem adta vissza a HTTP 200-t az időkorláton belül Streamelje a naplókat a(z) :logstream használatával, javítsa ki a készenléti ellenőrzést vagy az indítási hibát, majd telepítse újra.
409 conflict a DELETE-ügynökön (Agent has active sessions) A megnyitott munkamenetek blokkolják a törlést Várjon, amíg a munkamenetek inaktívvá válnak, vagy fűzze hozzá a(z) &force=true elemet a munkamenetek kaszkádos törléséhez.
Verzió elakadt a(z) creating állapotban (>10 perc, távoli összeállítás) A kiszolgáló összeállítása sikertelen vagy nem oldható fel requirements.txt Váltson a(z) dependency_resolution: bundled használatára, és buildeljen helyben előre.
Az üzembe helyezés sikertelen egy privát virtuális hálózaton A szükséges kimenő végpontokat a tűzfal blokkolja Engedélyezze a tűzfal követelményeiben szereplő végpontokat a magánhálózatok számára, majd telepítse újra.
Verzióváltás erre: failed Hibás zip-elrendezés, szintaxishiba vagy (remote_build) visszaállítási/fordítási hiba Először olvassa el a verzió error objektumát – error.code osztályozza a hibát, és error.message tartalmazza az alapul szolgáló visszaállítási vagy fordítási hibasort (pip for Python, NuGet for .NET), valamint egy hibaelhárítási hivatkozást. Ellenőrizze a mappastruktúrát. Csak a tároló elindítása után használható :logstream .
ModuleNotFoundError futásidőben packages/ hiányzik, nyers .whl fájlokat tartalmaz, vagy Windows bináris fájlokat tartalmaz Építse újra ezzel: pip install --target packages/ --platform manylinux2014_x86_64 --only-binary=:all:.
409 AgentNotCodeBased letöltés után Agent képalapú Használja a tárolóalapú üzembe helyezési dokumentumot.

Erőforrások tisztítása

Ha a projektet a Quickstart alapján, a azd használatával hozta létre, futtassa a azd down parancsot a projekt gyökerében a teljes kiépített környezet eltávolításához.

Az SDK-val vagy a REST API-val üzembe helyezett ügynök törléséhez használja az alábbi elérési utat.

# Delete one version
project.agents.delete_version(agent_name=AGENT_NAME, agent_version=created.version)

# Delete the agent and all its versions
project.agents.delete(agent_name=AGENT_NAME)

Warning

Az ügynök törlése eltávolítja az összes verziót, és leállítja az aktív munkameneteket. Ez a művelet nem vonható vissza.

Következő lépések

Üzemeltetett ügynök életciklusának kezelése

Kapcsolódó tartalom

  • Utolsó frissítés időpontja: