Distribuera en värdbaserad agent från källkoden (förhandsversion)

Den här artikeln visar hur du distribuerar en Hosted-agent i Foundry Agent Service från Python eller .NET källkod, utan att skapa eller push-överföra en containeravbildning. Du laddar upp en .zip av din kod (och eventuellt dina beroenden) och agenttjänsten kör den antingen as-is eller skapar dina beroenden åt dig i molnet.

Tip

I de flesta scenarier distribuerar du med Azure Developer CLI (azd) eller Foundry Toolkit för VS Code. De här verktygen gör det tunga jobbet åt dig: de paketerar din källa, laddar upp den, söker activeefter och konfigurerar rollbaserad åtkomstkontroll automatiskt. Kom igång genom att följa snabbstarten: Distribuera din första värdbaserade agent och välj Kod (eller Källkod (ZIP-uppladdning)) när du uppmanas att ange en distributionsmetod.

Använd SDK- och REST-procedurerna i den här artikeln när du behöver distribuera källkodsagenter programmatiskt – från Python SDK eller .NET SDK i dina egna program, eller direkt via REST-API:et för anpassade verktyg, språkagnostisk automatisering eller integrering med befintliga system för kontinuerlig leverans. I den här artikeln utför du följande uppgifter:

  • Välj ett beroendematchningsläge och paketera källan.
  • Skapa agenten, vänta tills den når activeoch anropa den.
  • Uppdatera, visa version, ladda ned och streama loggar för den driftsatta agenten.

Om du behöver fullständig kontroll över körningsmiljön eller redan har en fungerande Dockerfile, använder du den containerbaserade metoden: Distribuera en hostad agent.

Important

Källkodsdistributionen för värdbaserade agenter är i förhandsversion. Funktioner, regiontillgänglighet och API:er kan ändras före allmän tillgänglighet.

Förutsättningar

  • pip från Python 3.13 eller senare för att paketera källan lokalt.

  • azure-ai-projects-version 2.2.0 eller senare och azure-identity-paket.

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

Körmiljöer som stöds

Fältet code_configuration.runtime i agentdefinitionen accepterar följande värden. Välj den körmiljö som matchar binärfilerna i din ZIP-fil – Linux x86_64-wheel-filer för Python, eller TargetFramework för din dotnet publish-output för .NET.

Språk Körningsvärden
Python python_3_13, python_3_14
.NET dotnet_10

Stödprincip för språkversion

Agent service-körningen innehåller den plattformsbyggda containeravbildningen för varje värde för code_configuration.runtime. För att dina driftsatta agenter ska fortsätta omfattas av full support anpassar Foundry språkstödet för hostade agenter efter respektive språks livscykelslut. Support upphör på communityns slutdatum för support för språkversionen. Microsoft kan dra tillbaka ett code_configuration.runtime tidigare när plattformsbegränsningar (till exempel den underliggande basavbildningen) kräver det.

För tidsplaner för när support upphör för uppströmsprojekt, se:

Pensioneringsfas

Efter slutdatumet för ett språk kan du fortfarande skapa, uppdatera och köra hostade agenter som använder det utfasade värdet för körmiljön. Dessa agenter får dock inte support, nya funktioner eller säkerhetskorrigeringar förrän du uppgraderar dem till en version av körmiljön som stöds genom att ange ett aktuellt värde för code_configuration.runtime och distribuera om dem.

Behörigheter som krävs

Du behöver rollen Foundry Project Manager på projektnivå för att driftsätta en hostad agent. Den här rollen ger dataplanet behörighet att skapa och uppdatera agenter, plus möjligheten att skapa rolltilldelningar för den plattformsskapade agentidentiteten om det behövs. En detaljerad beskrivning av de behörigheter som berörs finns i Referens för värdbaserade agentbehörigheter.

Important

Foundrys RBAC-roller har nyligen namnändrats. Foundry User, Foundry Owner, Foundry Account Owner och Foundry Project Manager hette tidigare Azure AI-användare, Azure AI-ägare, Azure AI-kontoägare och Azure AI Project Manager. Du kanske fortfarande ser de tidigare namnen på vissa platser medan namnbytet distribueras. Roll-ID:na och kärnbehörigheterna ändras inte av namnbytet.

Din agent körs som en plattformstilldelad hanterad identitet som är separat från din användaridentitet. Den här identiteten kan komma åt modellinferenser via projektets slutpunkt och sessionslagring som standard. För externa resurser (till exempel din egen Azure Storage) tilldelar du RBAC-roller manuellt till agentens Microsoft Entra ID. Mer information finns i Agentåtkomst utöver standardvärden.

För REST-anrop inkluderar du funktionsrubriken för förhandsversionen för att mutera begäranden (Skapa, Uppdatera, Ta bort) medan funktionen är i förhandsversion:

Foundry-Features: CodeAgents=V1Preview,HostedAgents=V1Preview

GET-begäranden fungerar utan den idag, men ta med den i varje anrop för säkerhets skull – headern styr förhandsvisningsbeteendet och kan komma att tillämpas striktare före GA.

Distributionslivscykel

Varje distribution av källkod följer samma sekvens: paketera -> skapa eller uppdatera -> avfråga tills active -> anropa. Sökvägen till källkoden använder code_configuration i agentdefinitionen. Den bildbaserade sökvägen använder container_configuration i stället. Dessa två alternativ är ömsesidigt uteslutande för en enda version.

Välj den sökväg som passar ditt arbetsflöde. Om du inte är säker börjar du med Azure Developer CLI eller VS Code – det är den rekommenderade sökvägen för de flesta kunder.

Väg Passar bäst för Förpackning
Azure Developer CLI eller VS Code De flesta distributioner, inklusive första distributioner och den snabbaste inre loopen. Verktyg skapar och laddar upp zip-filen åt dig.
Python SDK Programstyrd driftsättning från Python-appar eller via automatisering. Du skapar zip; SDK:et laddar upp det.
.NET SDK Programstyrd distribution från .NET-appar eller automatisering. SDK:t zippar en mapp åt dig.
REST API Anpassade verktyg, språkagnostisk automatisering och CD-system. Du skapar zip-filen och skickar multipart-begäran.

Välj hur beroenden löses

Innan du börjar väljer du ett värde för code_configuration.dependency_resolution. Det här valet påverkar vad du lägger i zip-filen.

Value Behavior Använd när
remote_build Agenttjänsten installerar beroenden från requirements.txt (Python) eller återställer projektfilen (.NET) under etableringen. Du vill ha en liten uppladdning och den enklaste inre loopen. Rekommenderas för förstagångsanvändare.
bundled zip-filen körs i befintligt skick. Du skickar fördefinierade Linux-beroenden i packages/ (Python) eller dotnet publish utdata (.NET). Du behöver reproducerbara byggen, dina beroenden är privata eller endast hjul, eller så återställs inte projektet på en ren serversida.

För paketerat läge, se Paketera zip-filen manuellt för de lokala byggkommandona.

Brandväggskrav för privata virtuella nätverk

Om du skyddar projektet med ett privat virtuellt nätverk uppdaterar du nätverksprincipen så att utgående anslutningar tillåts till följande slutpunkter innan du distribuerar.

Alla källkodsdistributioner kräver utgående åtkomst till:

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

Beroendematchningen bundled kräver också utgående åtkomst till:

  • deb.debian.org
  • packages.microsoft.com

Utan dessa utgående anslutningsvägar kan provisioneringen inte ladda ned det som behövs och driftsättningen misslyckas. Mer information om nätverkskonfiguration finns i Distribuera en värdbaserad agent i ett virtuellt nätverk.

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

AZURE Developer CLI (azd) och Foundry Toolkit för VS Code automatiserar hela livscykeln för källkodsdistribution – de paketerar din källa i en zip, beräknar SHA-256, laddar upp den, söker efter active och konfigurerar rollbaserad åtkomstkontroll åt dig. Dessa verktyg är den rekommenderade sökvägen för de flesta kunder och den snabbaste inre loopen.

En stegvis genomgång finns i Snabbstart: Distribuera din första värdbaserade agent. Välj Kod (eller källkod (ZIP-uppladdning)) när snabbstarten frågar efter en distributionsmetod.

Välj distribution av källkod

När du kör azd ai agent init interaktivt uppmanar verktyget dig att välja ett distributionsläge. Välj kod som ska distribueras från källan som en ZIP-uppladdning i stället för att skapa en containeravbildning. Koddistribution är standardläget för Python och .NET värdbaserade agenter. Foundry Toolkit för VS Code frågar dig om distributionsmetoden på samma sätt.

Om du vill välja källkodsdistribution icke-interaktivt, till exempel i en CI/CD-pipeline, skickar du --deploy-mode code. Det här läget kräver --runtime och --entry-point, och accepterar ett valfritt värde för --dep-resolution på remote_build (standard) eller bundled:

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

Efter initieringen azd skriver du inställningarna för källkodsdistribution till codeConfiguration fältet på azure.ai.agent tjänsten i 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

Kör azd up för att förbereda och distribuera. Använd --deploy-mode container endast när du vill skapa eller referera till en containeravbildning i stället.

Använd SDK eller REST-sökvägar i följande avsnitt när du behöver distribuera programmatiskt från ditt eget program eller integrera med befintliga verktyg.

Distribuera från källkod

Välj språk eller gränssnitt. Varje flik följer samma livscykel: skapa agenten, gör upprepade statuskontroller tills den når active, anropa den och ladda ned den distribuerade koden.

Använd Python SDK för att distribuera källkodsagenter från dina egna program eller automatisering. Du skapar zip-filen själv och skickar dess byte och SHA-256 till SDK:n, som laddar upp den och exponerar samma åtgärder för att skapa, avsöka, anropa och ladda ned som REST-API:et. Koddistribution kräver azure-ai-projects version 2.2.0 eller senare.

Källkodsdistributionen använder förhandsgranskningsklientytan beta , så skapa klienten med allow_preview=True.

Skapa zip-filen

Python SDK laddar upp en zip som du skapar. Använd samma layout och regler för beroendematchning som beskrivs i Paketera zip-filen manuellt. Det minimala remote_build paketet är ett platt ZIP-arkiv med main.py och requirements.txt i rotkatalogen.

Skapa agenten

import hashlib
from pathlib import Path

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    CodeConfiguration,
    CreateAgentVersionFromCodeContent,
    CreateAgentVersionFromCodeMetadata,
    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,
    allow_preview=True,
)

content = CreateAgentVersionFromCodeContent(
    metadata=CreateAgentVersionFromCodeMetadata(
        description="Hello-world code agent",
        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"),
)

created = project.beta.agents.create_version_from_code(
    agent_name=AGENT_NAME,
    content=content,
    code_zip_sha256=code_zip_sha256,
)
print(f"Created version: {created.version}")

För anropsprotokollet anger du posten protocol_versions till ProtocolVersionRecord(protocol="invocations", version="1.0.0"). För protokollet Anrop (WebSocket) använder du ProtocolVersionRecord(protocol="invocations_ws", version="1.0.0"). För bundled läge ställer du in dependency_resolution="bundled" och skickar fördefinierade beroenden i zip-filen. Mer information finns i Skapa Linux-beroenden lokalt.

Sök efter aktiv

Koddistributionsmetoderna (create_version_from_code och ) finns på förhandsgranskningsytandownload_code, men läs- och borttagningsåtgärder som project.beta.agents finns på get_versionproject.agents.

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)

Se Polla efter aktiv för en fullständig lista över statusvärden och hur du läser error-objektet vid fel.

Anropa agenten

När versionen har nått activebinder du en OpenAI-klient till agentslutpunkten och anropar den. I det här exemplet används protokollet Svar:

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)

För Invocations-protokollet anropar du invoke-slutpunkten direkt med en bearer-token, som visas i Anropa agenten.

Ladda ned den distribuerade zip-filen

Kontrollera exakt vad som distribueras genom att ladda ned zip-filen och jämföra dess SHA-256 med det värde som du laddade upp:

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

Ett fullständigt körbart exempel finns i Python hosted-agent-exempel.

Paketera zip-filen manuellt

Om du använder azd, hoppar du över det här avsnittet –azd skapar zip-filen åt dig. Läs om du använder REST-API:et, om du växlar till paketerad beroendematchning eller om du behöver fullständig kontroll över uppladdningsinnehållet.

Zip-filen måste vara platt vid roten – ingen omslutningsmapp på den översta nivån.

Välj fliken för agentens språk.

Python-layout (läge för fjärrbygge)

Tjänsten installerar beroenden i molnet från requirements.txt.

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

Python layout (paketerat läge)

Du skickar fördefinierade Linux-beroenden i packages/.

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

Skapa Linux-beroenden lokalt (paketerade, Python)

Använd plattformstaggen manylinux2014_x86_64 så pip laddar ned Linux-hjul även från Windows eller 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: tvingar hjul (inga källbyggen). --python-version Måste matcha runtime värdet i agentdefinitionen.

Varning

Vanliga förpackningsmisstag som orsakar session_creation_failed eller ModuleNotFoundError:

  • Omsluter källan i en mapp (my-agent/main.py i stället main.py för vid roten).
  • Inkludera råa .whl filer i packages/ i stället för extraherade moduler.
  • Att paketera Windows-binärfiler (.pyd, .dll) för en Linux-körmiljö.

Limits

Limit Value
Maximal zip-storlek (uppladdning i flera delar) 250 MB

För kombinationer som stöds av cpu och memory, se Sandboxstorlekar.

Troubleshooting

Symptom Sannolik orsak Åtgärda
401 Unauthorized Token för saknat eller felaktigt omfång Hämta en token med --resource https://ai.azure.com.
403 Forbidden Anroparen saknar rollbaserad Access Control i projektet Tilldela Foundry Agent Consumer (endast för att anropa) eller Foundry User (för att även utveckla) på projektnivå.
409 conflict på Skapa (Agent '<name>' already exists) Agentnamnet finns redan Använd Update (POST /agents/{name}) eller välj ett nytt namn.
400 bad_request (CPU and Memory must be specified as a valid resource tier) vid skapa eller uppdatera cpu / memory är inte en av nivåerna som stöds Ange cpu och memory som ett giltigt par från Sandboxstorlekar.
400 bad_request (Agent version is still being provisioned) vid anrop En ny version är mellandistribuerad och den aktiva versionen byts in Kontrollera versionen status tills active, och försök sedan igen.
424 session_not_ready vid anrop Containern startade men /readiness returnerade inte HTTP 200 inom tidsgränsen Strömma loggar med :logstream, åtgärda beredskapsavsökningen eller startfelet och distribuera om.
409 conflict på DELETE-agenten (Agent has active sessions) Blockera borttagning vid öppna sessioner Vänta tills sessionerna är inaktiva eller lägg till i kaskadborttagningssessioner &force=true .
Versionen har fastnat i creating (>10 min, fjärrbygge) Serverkompileringen misslyckades eller kunde inte lösa requirements.txt Växla till dependency_resolution: bundled och förbygg lokalt.
Distributionen misslyckas i ett privat virtuellt nätverk Nödvändiga utgående slutpunkter blockeras av brandväggen Tillåt slutpunkterna i brandväggskrav för privata virtuella nätverk och distribuera sedan om.
Versionen övergår till failed Felaktig zip-layout, syntaxfel eller (remote_build) ett återställnings-/kompileringsfel Läs versionens error objekt först – error.code klassificerar felet och error.message innehåller den underliggande återställnings- eller kompileringsfelraden (pip för Python, NuGet för .NET) plus en felsökningslänk. Kontrollera mappstrukturen. Använd :logstream endast när containern har startats.
ModuleNotFoundError vid körning packages/ saknas, innehåller rådatafiler .whl eller har Windows binärfiler Bygg om med pip install --target packages/ --platform manylinux2014_x86_64 --only-binary=:all:.
409 AgentNotCodeBased vid nedladdning Agenten är bildbaserad Använd det containerbaserade distributionsdokumentet.

Rensa resurser

Om du skapade projektet från Quickstart med azd, kör azd down från projektroten för att ta bort hela den provisionerade miljön.

Om du vill ta bort en agent som du har distribuerat med SDK eller REST API använder du den matchande sökvägen nedan.

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

Varning

Om du tar bort en agent tas alla dess versioner bort och aktiva sessioner avslutas. Det går inte att ångra den här åtgärden.

Nästa steg

Hantera värdbaserad agentlivscykel

Relaterat innehåll

  • Last updated on