Nasazení hostovaného agenta ze zdrojového kódu

V tomto článku se dozvíte, jak nasadit hostovaného agenta ve službě Foundry Agent Service ze zdrojového kódu v Pythonu nebo .NET, aniž byste museli sestavovat nebo odesílat image kontejneru. Nahrajete .zip svého kódu (a volitelně i svých závislostí) a Agent Service ho buď spustí tak, jak je, nebo za vás v cloudu sestaví vaše závislosti.

Tip

Ve většině scénářů nasaďte pomocí Azure Developer CLI (azd) nebo sady Foundry Toolkit for VS Code. Tyto nástroje za vás obstarají většinu práce: zabalí váš zdroj, nahrají ho, průběžně zjišťují stav active a automaticky nakonfigurují řízení přístupu na základě rolí. Začněte tím, že budete postupovat podle rychlého startu: Nasaďte svého prvního hostovaného agenta a po zobrazení výzvy k zadání metody nasazení zvolte Kód (nebo zdrojový kód (nahrání ZIP)).

Postupy SADY SDK a REST v tomto článku použijte v případě, že potřebujete nasadit agenty zdrojového kódu programově – ze sady Python SDK nebo sady .NET SDK ve vlastních aplikacích nebo přímo přes rozhraní REST API pro vlastní nástroje, automatizaci nezávislou na jazyce nebo integraci se stávajícími systémy průběžného doručování. V tomto článku dokončíte následující úlohy:

  • Vyberte režim rozlišení závislostí a zabalte zdroj.
  • Vytvořte agenta, počkejte, až dosáhne active, a vyvolejte jej.
  • Aktualizace, verze, stažení a streamování protokolů pro nasazeného agenta

Pokud potřebujete úplnou kontrolu nad imagí modulu runtime nebo už máte funkční soubor Dockerfile, použijte cestu založenou na kontejneru: Nasaďte hostovaného agenta.

Předpoklady

  • Projekt Microsoft Foundry v podporované oblasti.
  • Azure CLI verze 2.80 nebo novější, přihlášeni ke klientovi, který projekt vlastní.

  • pip z Pythonu 3.13 nebo novějšího k místnímu zabalení zdrojového kódu.

  • Verze azure-ai-projects 2.2.0 nebo novější a azure-identity balíčky.

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

Podporovaná běhová prostředí

Pole code_configuration.runtime v definici agenta přijímá následující hodnoty. Vyberte běhové prostředí, které odpovídá binárním souborům ve vašem ZIP archivu — linuxové x86_64 wheels pro Python nebo TargetFramework vašeho výstupu dotnet publish pro .NET.

Jazyk Hodnoty modulu runtime
Python python_3_13, python_3_14
platforma .NET dotnet_10

Zásady podpory jazykových verzí

Modul runtime služby agenta zahrnuje image kontejneru sestavenou platformou pro každou hodnotu code_configuration.runtime. Aby byli vaši nasazení agenti i nadále plně podporováni, Foundry slaďuje podporu jazyků hostovaných agentů s podporou do konce životnosti jednotlivých jazyků. Podpora končí datem ukončení podpory komunity pro jazykovou verzi. Microsoft může vyřadit hodnotu code_configuration.runtime dříve, když ji vyžadují omezení platformy (například základní základní image).

Upstreamové plány ukončení podpory najdete tady:

Fáze vyřazení

Po datu ukončení podpory jazyka můžete stále vytvářet, aktualizovat a spouštět hostované agenty, které používají vyřazenou hodnotu runtime. Tito agenti ale nemají nárok na podporu, nové funkce ani bezpečnostní opravy, dokud je neupgradujete na podporované runtime prostředí nastavením hodnoty code_configuration.runtime na aktuální hodnotu a opětovným nasazením.

Požadována oprávnění

K nasazení hostovaného agenta potřebujete roli Foundry Project Manager na úrovni projektu. Tato role uděluje oprávnění v datové rovině k vytváření a aktualizaci agentů a v případě potřeby také možnost vytvářet přiřazení rolí pro identitu agenta, kterou vytvořila platforma. Podrobný rozpis zahrnutých oprávnění najdete v referenčních informacích k oprávněním hostovaného agenta.

Important

Nedávno byly přejmenovány role Foundry RBAC. Foundry User, Foundry Owner, Foundry Account Owner a Foundry Project Manager se dříve nazývaly Uživatel Azure AI, Vlastník Azure AI, Vlastník účtu Azure AI a Správce projektů Azure AI. Během zavádění přejmenování se stále můžou zobrazovat předchozí názvy na některých místech. ID rolí a základní oprávnění se při přejmenování nezmění.

Váš agent běží jako spravovaná identita přiřazená platformou, která je oddělená od vaší identity uživatele. Tato identita může standardně přistupovat ke spouštění inferencí modelu prostřednictvím koncového bodu projektu a k úložišti relací. Pro externí prostředky (například vaše vlastní úložiště Azure) přiřaďte role RBAC ručně identitě Microsoft Entra ID agenta. Další informace najdete v tématu Přístup agenta nad rámec výchozích hodnot.

Životní cyklus nasazení

Každé nasazení zdrojového kódu probíhá podle stejné posloupnosti: zabalit -> vytvořit nebo aktualizovat -> dotazovat se, dokud active -> vyvolat. Cesta ke zdrojovému kódu používá v definici agenta code_configuration. Místo toho se používá container_configuration cesta založená na imagi. Tyto dvě možnosti se vzájemně vylučují v jedné verzi.

Zvolte cestu, která odpovídá vašemu pracovnímu postupu. Pokud si nejste jistí, začněte s Azure Developer CLI nebo VS Code – to je doporučený postup pro většinu zákazníků.

Cesta Nejvhodnější pro Balení
Azure Developer CLI nebo VS Code Většina nasazení, včetně prvních nasazení a nejrychlejšího interního cyklu. Nástroje za vás vytvoří a nahrají soubor ZIP.
Python SDK Automatizované nasazení z aplikací v Pythonu nebo pomocí automatizačních nástrojů. Sestavíš zip; sada SDK ji nahraje.
.NET SDK Programové nasazení z .NET aplikací nebo automatizace Sada SDK zazipuje složku za vás.
REST API Vlastní nástroje, automatizace nezávislá na jazyce a systémy CD Soubor ZIP sestavíte a odešlete žádost o více částí.

Volba způsobu řešení závislostí

Než začnete, vyberte hodnotu pro code_configuration.dependency_resolution. Tato volba má vliv na to, co vložíte do zipu.

Hodnota Behavior Použít, když
remote_build Služba agenta nainstaluje závislosti z requirements.txt (Python) nebo během zřizování obnoví soubor projektu (.NET). Chcete malý objem nahrávaných dat a co nejjednodušší interní cyklus. Doporučeno pro začínající uživatele.
bundled Soubor ZIP se spouští beze změn. Předem připravené závislosti Linuxu se dodávají ve výstupu packages/ (Python) nebo dotnet publish (.NET). Potřebujete reprodukovatelná sestavení, vaše závislosti jsou soukromé nebo dostupné pouze jako wheel balíčky, nebo se váš projekt na straně serveru neobnoví bez problémů.

V případě sbaleného režimu se podívejte na ruční zabalení souboru ZIP pro místní příkazy sestavení.

Požadavky na bránu firewall pro soukromé virtuální sítě

Pokud projekt zabezpečíte pomocí privátní virtuální sítě, aktualizujte zásady sítě tak, aby umožňovaly odchozí připojení k následujícím koncovým bodům před nasazením.

Všechna nasazení zdrojového kódu vyžadují odchozí přístup k:

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

Informace o konfiguraci sítě najdete v tématu Nasazení hostovaného agenta ve virtuální síti.

Nasazení pomocí Azure Developer CLI nebo VS Code

Rozhraní příkazového řádku pro vývojáře Azure (azd) a sada Foundry Toolkit for VS Code automatizují celý životní cyklus nasazení zdrojového kódu – zabalí váš zdroj do souboru ZIP, vypočítá SHA-256, nahraje ho, odešle dotaz na active a nakonfiguruje řízení přístupu na základě rolí za vás. Tyto nástroje představují doporučenou cestu pro většinu zákazníků a nejrychlejší vnitřní smyčku.

Podrobný návod najdete v rychlém startu: Nasazení prvního hostovaného agenta. Pokud rychlý start požádá o metodu nasazení, zvolte kód (nebo zdrojový kód (nahrání ZIP).

Výběr nasazení zdrojového kódu

Když spustíte azd ai agent init interaktivně, nástroj vás vyzve k výběru režimu nasazení. Místo sestavení image kontejneru zvolte kód , který se má nasadit ze zdroje jako nahrání ZIP. Nasazení kódu je výchozí režim pro agenty hostované Python a .NET. Sada Foundry Toolkit for VS Code vás stejným způsobem vyzve k zadání metody nasazení.

Chcete-li neinteraktivně vybrat nasazení zdrojového kódu, například v pipeline CI/CD, předejte --deploy-mode code. Tento režim vyžaduje --runtime a --entry-point a přijímá volitelnou hodnotu --dep-resolutionremote_build (výchozí) nebo bundled:

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

Po inicializaci azd zapíše nastavení nasazení zdrojového kódu do codeConfiguration pole ve službě azure.ai.agent v azure.yaml:

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

Spusťte azd up ke zřízení a nasazení. Použijte --deploy-mode container pouze v případech, kdy chcete vytvořit nebo odkazovat na image kontejneru.

Pokud potřebujete nasadit programovou aplikaci z vlastní aplikace nebo integrovat se stávajícími nástroji, použijte cesty SDK nebo REST v následujících částech.

Nasazení ze zdrojového kódu

Vyberte jazyk nebo rozhraní. Každá karta prochází stejným životním cyklem: vytvořit agenta, opakovaně kontrolovat jeho stav, dokud nedosáhne active, spustit ho a stáhnout nasazený kód.

Pomocí sady Python SDK nasaďte agenty zdrojového kódu z vlastních aplikací nebo automatizace. Soubor ZIP sestavíte sami a předáte jeho bajty a SHA-256 sadě SDK, která ho nahraje a zveřejní stejné operace vytvoření, hlasování, vyvolání a stahování jako rozhraní REST API. Nasazení kódu vyžaduje azure-ai-projects verzi 2.2.0 nebo novější.

Vytvořit ZIP archiv

Sada PYTHON SDK nahraje soubor ZIP, který sestavíte. Použijte stejné rozvržení a pravidla pro řešení závislostí popsaná v části Zabalení souboru zip ručně. Minimální payload remote_build je plochý ZIP archiv s main.py a requirements.txt v kořenovém adresáři.

Vytvoření agenta

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

Pro protokol Vyvolání nastavte protocol_versions položku na ProtocolVersionRecord(protocol="invocations", version="1.0.0"). Pro vyvolání (WebSocket) protokolu použijte ProtocolVersionRecord(protocol="invocations_ws", version="1.0.0"). Pro režim bundled nastavte dependency_resolution="bundled" a dodejte předem sestavené závislosti v ZIP souboru. Další informace najdete v tématu Místní sestavení závislostí Linuxu.

Hlasování pro aktivní

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)

Viz Poll for active, kde najdete úplný seznam stavových hodnot a informace o tom, jak číst objekt error v případě selhání.

Vyvolání agenta

Jakmile verze dosáhne active, připojte klienta OpenAI ke koncovému bodu agenta a volejte jej. V tomto příkladu se používá protokol Odpovědi:

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)

Pro protokol Invocations volejte koncový bod invoke přímo pomocí tokenu Bearer, jak je uvedeno v Vyvolání agenta.

Stažení nasazeného souboru ZIP

Ověřte, co přesně nasadíte stažením souboru ZIP a porovnáním jeho SHA-256 s hodnotou, kterou jste nahráli:

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

Úplný spustitelný příklad najdete v části ukázky hostovaného agenta v Pythonu.

Ruční zabalení zipu

Pokud použijete azd, přeskočte tuto část –azd sestaví zip za vás. Přečtěte si to, pokud používáte rozhraní REST API, pokud přepnete na sdružené řešení závislostí nebo pokud potřebujete úplnou kontrolu nad obsahem nahrávaných dat.

ZIP musí mít soubory přímo v kořenové složce – bez nadřazené složky nejvyšší úrovně.

Vyberte kartu pro jazyk vašeho agenta.

rozložení Python (režim vzdáleného sestavení)

Služba instaluje závislosti v cloudovém prostředí z requirements.txt.

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

Rozložení Pythonu (sdružený režim)

Dodáváte v packages/ předkompilované závislosti pro Linux.

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

Lokální sestavení linuxových závislostí (přibalené, Python)

Použijte značku platformy manylinux2014_x86_64, takže pip stáhne linuxová kola i z Windows nebo macOS.

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 cmd

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: vynutí kola (žádné zdrojové sestavení). Musí --python-version odpovídat hodnotě runtime v definici agenta.

Warning

Běžné chyby balení, které způsobují session_creation_failed nebo ModuleNotFoundError:

  • Zabalení zdroje do složky (my-agent/main.py místo main.py v kořenovém adresáři)
  • Zahrnutí nezpracovaných souborů .whl do packages/ místo extrahovaných modulů.
  • Přibalení binárních souborů pro Windows (.pyd, .dll) pro běhové prostředí Linuxu.

Omezení

Limit Hodnota
Maximální velikost ZIPu (vícedílné nahrávání) 250 MB

Informace o podporovaných kombinacích cpu a memory naleznete v tématu Velikosti sandboxu.

Troubleshooting

Symptom Pravděpodobná příčina Opravit
401 Unauthorized Token chybí nebo má nesprávný rozsah platnosti Získejte token pomocí --resource https://ai.azure.com.
403 Forbidden Volající nemá v projektu řízení přístupu na základě rolí Přidělte roli Foundry Agent Consumer (pouze pro vyvolávání) nebo Foundry User (také pro vývoj) na úrovni projektu.
409 conflict při akci Vytvořit (Agent '<name>' already exists) Název agenta už existuje Použijte možnost Aktualizovat (POST /agents/{name}) nebo vyberte nový název.
400 bad_request (CPU and Memory must be specified as a valid resource tier) při vytvoření či aktualizaci cpu / memory nejsou jednou z podporovaných úrovní. Nastavte cpu a memory na platný pár z velikostí sandboxu.
400 bad_request (Agent version is still being provisioned) při vyvolání Právě se nasazuje nová verze a aktivní verze se přepíná. Zjišťujte verzi status, dokud nenastane active, pak to zkuste znovu.
424 session_not_ready při vyvolání Kontejner se spustil, ale /readiness během časového limitu nevrátil HTTP 200 Sledujte logy pomocí :logstream, opravte sondu připravenosti nebo chybu při spuštění a znovu nasaďte.
409 conflict u agenta DELETE (Agent has active sessions) Odstranění blokování otevřených relací Počkejte, až relace přejdou do nečinnosti, nebo přidejte &force=true, aby se relace odstranily kaskádově.
Verze zaseknutá v creating (>10 min, vzdálené sestavení) Sestavení serveru se nezdařilo nebo se nepodařilo vyřešit requirements.txt Přepněte na dependency_resolution: bundled a sestavujte lokálně předem.
Nasazení selže v soukromé virtuální síti Požadované odchozí endpointy jsou blokovány bránou firewall. Povolte koncové body uvedené v Požadavky brány firewall pro privátní virtuální sítě a poté je znovu nasaďte.
Verze přechází na failed Chybné rozložení zip, chyba syntaxe nebo (remote_build) selhání obnovení nebo kompilace Nejprve si přečtěte objekt error verze – error.code klasifikuje selhání a error.message obsahuje základní řádek chyby obnovení nebo kompilace (pip pro Python, NuGet pro .NET) a odkaz pro řešení potíží. Ověřte strukturu složek. Použijte :logstream až po spuštění kontejneru.
ModuleNotFoundError za běhu packages/ chybí, obsahuje nezpracované soubory .whl nebo mají binární soubory Windows Znovu sestavte pomocí pip install --target packages/ --platform manylinux2014_x86_64 --only-binary=:all:.
409 AgentNotCodeBased ke stažení Agent je založený na imagích. Použijte dokumentaci k nasazení pomocí kontejnerů.

Vyčistěte zdroje

Pokud jste projekt vytvořili podle Quickstartu pomocí azd, spusťte azd down v kořenovém adresáři projektu a odstraňte celé zřízené prostředí.

Pokud chcete odstranit agenta, který jste nasadili pomocí sady SDK nebo rozhraní REST API, použijte odpovídající cestu níže.

# 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

Odstranění agenta odstraní všechny jeho verze a ukončí aktivní relace. Tuto akci nelze vrátit zpět.

Další kroky

Správa životního cyklu hostovaného agenta

Související obsah

  • Last updated on