Bereitstellen eines gehosteten Agents aus Quellcode (Vorschau)

• pip ab Python 3.13, um Ihren Quellcode lokal zu paketieren.

• Die azure-ai-projects Version 2.2.0 oder höher und azure-identity-Pakete.

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

• Das .NET 10 SDK, um Ihre Quelle lokal zu verpacken.

• Die Pakete Azure.AI.Projects.Agents und Azure.Identity.

  dotnet add package Azure.AI.Projects.Agents
  dotnet add package Azure.Identity
  

• Ein HTTP-Client für die Befehlszeile wie curl (die REST-Beispiele in diesem Artikel verwenden curl).
• Um Ihre Quelle lokal zu verpacken, installieren Sie die Toolkette für die Sprache Ihres Agents: pip von Python 3.13 oder höher oder dem .NET 10 SDK.

Verwenden Sie das Python SDK, um Quellcode-Agents aus Ihren eigenen Anwendungen oder Automatisierungen bereitzustellen. Sie erstellen die ZIP-Datei selbst und übergeben die Bytes und SHA-256 an das SDK, das sie hochlädt und die gleichen Erstellungs-, Abruf-, Aufruf- und Downloadvorgänge wie die REST-API verfügbar macht. Für die Codebereitstellung ist azure-ai-projects Version 2.2.0 oder höher erforderlich.

Die Quellcodebereitstellung verwendet die Vorschauclientoberfläche beta , erstellen Sie also den Client mit allow_preview=True.

Erstellen der ZIP-Datei

Das Python SDK lädt eine zip-Datei hoch, die Sie erstellen. Verwenden Sie die gleichen Layout- und Abhängigkeitsauflösungsregeln, die in "Packen der ZIP"-Datei manuell beschrieben sind. Das minimale remote_build-Payload ist ein flaches ZIP-Archiv mit main.py und requirements.txt im Stammverzeichnis.

Erstellen des Agents

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

Legen Sie für das Aufrufprotokoll den protocol_versions Eintrag auf ProtocolVersionRecord(protocol="invocations", version="1.0.0"). Für den Modus bundled legen Sie dependency_resolution="bundled" fest und liefern vorgefertigte Abhängigkeiten im ZIP-Archiv mit – siehe Linux-Abhängigkeiten lokal erstellen.

Umfrage für „Aktiv“

Die Methoden für die Codebereitstellung (create_version_from_code und download_code) sind auf der Vorschauschnittstelle project.beta.agents verfügbar, aber Lese- und Löschvorgänge wie get_version befinden sich auf project.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)

Eine vollständige Liste der Statuswerte und wie das Objekt im Fehlerfall zu lesen ist, finden Sie unter error.

Agenten aufrufen

Sobald die Version active erreicht, verbinden Sie einen OpenAI-Client mit dem Agent-Endpunkt und rufen Sie ihn auf. In diesem Beispiel wird das Antwortprotokoll verwendet:

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)

Rufen Sie für das Invocations-Protokoll den Invoke-Endpunkt direkt mit einem Bearer-Token auf, wie unter Den Agent aufrufen gezeigt.

Herunterladen der bereitgestellten ZIP-Datei

Überprüfen Sie genau, was bereitgestellt wird, indem Sie die ZIP-Datei herunterladen und ihre SHA-256 mit dem wert vergleichen, den Sie hochgeladen haben:

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

Ein vollständiges ausführungsfähiges Beispiel finden Sie in den Beispielen Python Hosted-Agent.

Verwenden Sie das .NET SDK, um Quellcode-Agents aus Ihren eigenen Anwendungen oder Automatisierungen bereitzustellen. Im Gegensatz zu den Python- und REST-Pfaden zippt das .NET SDK einen Quellordner für Sie – Sie übergeben einen Ordnerpfad, anstatt die ZIP-Datei selbst zu erstellen.

Die Bereitstellung von Quellcode ist eine Vorschaufunktion. Unterdrücken Sie die AAIP001-Warnung zu experimentellen Features und fügen Sie bei jedem Aufruf mithilfe einer Pipelinerichtlinie den Header für Previewfunktionen hinzu.

Erstellen des Agents

using System;
using System.ClientModel.Primitives;
using Azure.AI.Projects.Agents;
using Azure.Identity;

#pragma warning disable AAIP001 // Hosted agents are an experimental preview feature.

// Format: "https://<account>.services.ai.azure.com/api/projects/<project>"
string projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");

var options = new AgentAdministrationClientOptions();
options.AddPolicy(
    new FeaturePolicy("HostedAgents=V1Preview,CodeAgents=V1Preview"),
    PipelinePosition.PerCall);

var agentsClient = new AgentAdministrationClient(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential(),
    options: options);

var agentDefinition = new HostedAgentDefinition(cpu: "1", memory: "2Gi")
{
    Versions = { new ProtocolVersionRecord(ProjectsAgentProtocol.Responses, "1.0.0") },
    CodeConfiguration = new(
        runtime: "dotnet_10",
        entryPoint: ["dotnet", "MyAgent.dll"],
        dependencyResolution: CodeDependencyResolution.RemoteBuild),
};

var metadata = new CreateAgentVersionFromCodeMetadata(agentDefinition);

ProjectsAgentVersion agentVersion = agentsClient.CreateAgentVersionFromCode(
    agentName: "my-code-agent",
    filePath: "./AgentCode",
    metadata: metadata);

Console.WriteLine($"Created version: {agentVersion.Version}");

Zeigen Sie mit remote_build auf filePath auf einen Ordner mit .NET-Projektquellen. Der Agentdienst führt während der Bereitstellung dotnet restore und dotnet publish für Sie aus. Das entryPoint bezieht sich auf den Namen der veröffentlichten Assembly – zum Beispiel ["dotnet", "MyAgent.dll"] für ein Projekt namens MyAgent.csproj.

FeaturePolicy ist ein kleines PipelinePolicy, das jeder Anfrage die Foundry-Features-Kopfzeile hinzufügt:

internal class FeaturePolicy(string feature) : PipelinePolicy
{
    private const string FeatureHeader = "Foundry-Features";

    public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
    {
        message.Request.Headers.Add(FeatureHeader, feature);
        ProcessNext(message, pipeline, currentIndex);
    }

    public override async ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
    {
        message.Request.Headers.Add(FeatureHeader, feature);
        await ProcessNextAsync(message, pipeline, currentIndex);
    }
}

Ändern Sie für das Aufrufprotokoll den Versions Eintrag in new ProtocolVersionRecord(ProjectsAgentProtocol.Invocations, "1.0.0"). Legen Sie für den Modus bundleddependencyResolution: CodeDependencyResolution.Bundled fest und lassen Sie filePath auf einen Ordner verweisen, der Ihre dotnet publish-Ausgabe enthält. Siehe Build .NET Output (gebündelt).

Umfrage für „Aktiv“

while (agentVersion.Status != AgentVersionStatus.Active &&
       agentVersion.Status != AgentVersionStatus.Failed)
{
    Thread.Sleep(500);
    agentVersion = agentsClient.GetAgentVersion(
        agentName: agentVersion.Name,
        agentVersion: agentVersion.Version);
}

if (agentVersion.Status != AgentVersionStatus.Active)
{
    throw new InvalidOperationException($"Deployment failed, status: {agentVersion.Status}");
}

Herunterladen des bereitgestellten Codes

Laden Sie den bereitgestellten Code in ein lokales Verzeichnis herunter, und extrahieren Sie diesen, um zu überprüfen, was ausgeführt wird. Das SDK schreibt den entzippten Inhalt in path:

agentsClient.DownloadAgentCode(agentName: agentVersion.Name, path: "./downloaded");
Console.WriteLine("Downloaded agent code to ./downloaded");

Ein vollständiges lauffähiges Beispiel finden Sie in den Beispielen für gehostete .NET-Agents.

Sie können die REST-API für direkte HTTP-basierte Bereitstellungen oder benutzerdefinierte Tools verwenden. In den Abschnitten wird eine erste Bereitstellung Schritt für Schritt erläutert: Variablen einrichten, ZIP-Datei erstellen, den Agent erstellen, abfragen, bis der Wert active erreicht ist, und den Agent aufrufen. Update-, Versions-, Download- und Protokollstreaming-Endpunkte werden unter laufenden Vorgängen gruppiert.

Einrichten von Variablen

Bash

ENDPOINT="https://{account}.services.ai.azure.com/api/projects/{project}"
API_VERSION="2025-11-15-preview"
TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
AGENT=my-code-agent
ZIP=./agent-code.zip
SHA=$(sha256sum "$ZIP" | cut -d' ' -f1)

PowerShell

$Endpoint    = "https://{account}.services.ai.azure.com/api/projects/{project}"
$ApiVersion  = "2025-11-15-preview"
$Token       = az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv
$Agent       = "my-code-agent"
$Zip         = "./agent-code.zip"
$Sha         = (Get-FileHash $Zip -Algorithm SHA256).Hash.ToLower()

Erstellen einer minimalen Zip-Datei für hello-world

Erstellen Sie vor dem Aufrufen von Create eine flache ZIP-Datei mit zwei Dateien. Dies ist die minimale Payload, die vom Agent Service für eine Python-remote_build-Bereitstellung akzeptiert wird.

agent-code.zip
├── main.py            # your agent loop (starts a Foundry hosting server)
└── requirements.txt   # dependencies (for example, agent-framework, agent-framework-foundry-hosting)

metadata.json (die im Metadatenbeispiel gezeigte Agentdefinition) befindet sich neben der ZIP-Datei und wird als separate mehrteilige Komponente gesendet – sie befindet sich nicht innerhalb der ZIP-Datei. Für vollständige Layouts (einschließlich bundled-Modus und .NET) siehe die ZIP-Datei manuell packen. Informationen zu Arbeitsquelldateien finden Sie in den Beispielen Python und .NET.

Form einer Multipart-Anfrage

Alle mutierenden Endpunkte (Create, Update) verwenden multipart/form-data mit zwei Teilen:

Erforderliche Header für jeden mehrteiligen Aufruf:

Authorization: Bearer <token>
Accept: application/json
Foundry-Features: CodeAgents=V1Preview,HostedAgents=V1Preview
x-ms-code-zip-sha256: <sha256-hex-of-zip>

Die x-ms-code-zip-sha256 Kopfzeile zeichnet die SHA-256 der zip-Datei auf, die Sie hochgeladen haben. Der Dienst speichert dies und gibt es über code:download zurück, sodass Sie Abweichungen zwischen dem, was Sie bereitzustellen erwartet haben, und dem, was tatsächlich bereitgestellt ist, erkennen können. Fügen Sie sie immer hinzu.

Der Aufruf „Create“ erfordert auch x-ms-agent-name: <agent-name>. Aktualisierungsaufrufe lassen sie aus, da der Name bereits Teil der URL ist.

Metadatenbeispiel (Remotebuild, Antworten)

Diese Metadaten entsprechen der Zip-Datei "hello-world".

{
  "description": "Hello-world code agent",
  "definition": {
    "kind": "hosted",
    "protocol_versions": [
      { "protocol": "responses", "version": "1.0.0" }
    ],
    "cpu": "1",
    "memory": "2Gi",
    "code_configuration": {
      "runtime": "python_3_13",
      "entry_point": ["python", "main.py"],
      "dependency_resolution": "remote_build"
    },
    "environment_variables": {
      "AZURE_AI_MODEL_DEPLOYMENT_NAME": "gpt-4.1-mini"
    }
  }
}

Ersetzen Sie für das Aufrufprotokoll den protocol_versions Eintrag durch { "protocol": "invocations", "version": "1.0.0" }. Für bundled-Modus legen Sie "dependency_resolution": "bundled" fest und folgen Sie Build Linux dependencies locally.

code_configuration und container_configuration schließen sich gegenseitig in der Agentdefinition aus: Schließen Sie code_configuration die Bereitstellung von Quellcode (in diesem Artikel) oder container_configuration die imagebasierte Bereitstellung ein. Siehe Bereitstellen eines gehosteten Agents (Container) für die Imagevariante.

Erstellen des Agents

curl -X POST "$ENDPOINT/agents?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Foundry-Features: CodeAgents=V1Preview,HostedAgents=V1Preview" \
  -H "x-ms-agent-name: $AGENT" \
  -H "x-ms-code-zip-sha256: $SHA" \
  -F "metadata=@metadata.json;type=application/json" \
  -F "code=@$ZIP;type=application/zip;filename=$AGENT.zip"

x-ms-agent-name ist nur für den Create-Aufruf erforderlich. Der Name muss mit alphanumerischen Zeichen beginnen und enden, kann Bindestriche in der Mitte enthalten und darf 63 Zeichen nicht überschreiten. Die Antwort enthält eine Initiale status von creating.

Umfrage für „Aktiv“

while true; do
  STATUS=$(curl -s -H "Authorization: Bearer $TOKEN" \
    -H "Foundry-Features: CodeAgents=V1Preview,HostedAgents=V1Preview" \
    "$ENDPOINT/agents/$AGENT/versions/1?api-version=$API_VERSION" | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "active" ] && break
  [ "$STATUS" = "failed" ] && echo "Provisioning failed." && exit 1
  sleep 5
done

Agenten aufrufen

Wählen Sie das Protokoll aus, das Ihr Agent in protocol_versions angegeben hat.

Antwortprotokoll:

curl -X POST "$ENDPOINT/agents/$AGENT/endpoint/protocols/openai/responses?api-version=v1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: CodeAgents=V1Preview,HostedAgents=V1Preview" \
  -d '{"model":"gpt-4.1-mini","input":"Hello, agent!","stream":false}'

Aufrufprotokoll:

curl -X POST "$ENDPOINT/agents/$AGENT/endpoint/protocols/invocations?api-version=v1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: CodeAgents=V1Preview,HostedAgents=V1Preview" \
  -d '{"input":"Hello, this is a test invocation!"}'

Nützliche Antwortheader:

Für das Response-Protokoll ist der Antwortbezeichner pro Aufruf das id Feld im JSON-Antworttext der Antwort (z. B caresp_<random>. ). Verwenden Sie ihn, um den Anruf mit Containerprotokollen zu korrelieren oder um auf den Anruf in einer Supportanfrage zu verweisen.

Laufende Vorgänge

Verwenden Sie nach der ersten Bereitstellung diese Endpunkte, um den Agent zu entwickeln und zu betreiben.

Agent aktualisieren oder versionieren

Um eine Codeänderung oder eine Aktualisierung einer Definition zu übertragen, senden Sie den Multipart-Body erneut an die Agent-Ressource. Der Dienst verwendet inhaltsadressierbare Versionsverwaltung: Eine neue Version wird nur verwendet, wenn die SHA-256 der Zip-Datei oder die Agentdefinition tatsächlich geändert wird. Identische Reposts geben die vorhandene neueste Version zurück.

curl -X POST "$ENDPOINT/agents/$AGENT?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Foundry-Features: CodeAgents=V1Preview,HostedAgents=V1Preview" \
  -H "x-ms-code-zip-sha256: $SHA" \
  -F "metadata=@metadata.json;type=application/json" \
  -F "code=@$ZIP;type=application/zip;filename=$AGENT.zip"

Die Antwort ist das vollständige Agent-Envelope mit ausgefülltem versions.latest. Abrufen der resultierenden Version wie in Umfrage für „Aktiv“ dargestellt.

Wenn Ihre Tools eine Antwort im Versionsformat bevorzugen (ein bloßes AgentVersionObject statt des Agent-Envelopes), senden Sie denselben Multipart-Body an $ENDPOINT/agents/$AGENT/versions?api-version=$API_VERSION. Die Dedupregel ist identisch – beide Endpunkte verwenden dieselbe Inhaltsadressierungslogik.

Herunterladen der bereitgestellten ZIP-Datei

Überprüfen Sie genau, was bereitgestellt wird, indem Sie die ZIP-Datei herunterladen. Lassen Sie agent_version weg, um die neueste Version herunterzuladen; übergeben Sie agent_version=<n>, um eine bestimmte Version anzugeben.

VERSION=1

# Latest version
curl -O -J "$ENDPOINT/agents/$AGENT/code:download?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/zip" \
  -H "Foundry-Features: CodeAgents=V1Preview,HostedAgents=V1Preview"

# Specific version
curl -O -J "$ENDPOINT/agents/$AGENT/code:download?api-version=$API_VERSION&agent_version=$VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/zip" \
  -H "Foundry-Features: CodeAgents=V1Preview,HostedAgents=V1Preview"

Mit zwei Antwortheadern können Sie bestätigen, was Sie heruntergeladen haben:

Bildbasierte Agenten geben 409 AgentNotCodeBased zurück.

Streamcontainerprotokolle

curl -N "$ENDPOINT/agents/$AGENT/sessions/<sessionId>:logstream?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream"

Protokolle werden als servergesendete Ereignisse übermittelt. {sessionId} ist der Wert von x-agent-session-id aus der Antwort des Aufrufs. Verwenden Sie diesen Endpunkt, um Laufzeitfehler und 424 session_not_ready -antworten zu debuggen. Für den Protokollstreamingendpunkt ist der Foundry-Features Vorschauheader nicht erforderlich.

Python-Layout (Remote-Build-Modus)

Der Dienst installiert Abhängigkeiten in der Cloud von requirements.txt.

agent-code.zip
├── main.py
└── requirements.txt

Python Layout (gebündelter Modus)

Sie liefern vorkompilierte Linux-Abhängigkeiten in packages/ mit.

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

Lokales Erstellen von Linux-Abhängigkeiten (gebündelt, Python)

Verwenden Sie das Plattformtag manylinux2014_x86_64, damit pip auch unter Windows oder macOS Linux-Wheels herunterlädt.

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: erzwingt Wheels (keine Quellbuilds). Der --python-version Wert muss mit dem runtime Wert in der Agentdefinition übereinstimmen.

.NET-Layout (Remotebuildmodus)

Komprimieren Sie nur die Projektquellen – keine bin/-, obj/- oder publish/-Ausgabe. Der Agentdienst führt während der Bereitstellung dotnet restore und dotnet publish für Sie aus.

agent-code.zip
├── MyAgent.csproj
├── Program.cs
└── ... (additional .cs files)

Die in der Agentdefinition festgelegte entry_point bezieht sich weiterhin auf den Namen der veröffentlichten Assembly (z. B. ["dotnet", "MyAgent.dll"]), die durch den serverseitigen Publish-Vorgang erzeugt wird.

.NET Layout (gebündelter Modus)

Komprimieren Sie die Ausgabe von dotnet publish -c Release -r linux-x64 --self-contained false, sodass sie sich direkt im Stammverzeichnis der ZIP-Datei befindet:

agent-code.zip
├── MyAgent.dll
├── MyAgent.runtimeconfig.json
└── ... (publish output)

.NET-Ausgabe (gebündelt) erstellen

dotnet publish -c Release -r linux-x64 --self-contained false -o publish/
cd publish && zip -r ../agent-code.zip .

Verwenden Sie --self-contained true, wenn Sie die .NET Laufzeit in der ZIP-Datei versenden möchten. Der Wert runtime, den Sie in der Agentdefinition festlegen, muss mit der TargetFramework übereinstimmen.

Weitere Informationen finden Sie auf den Registerkarten Python oder C#.

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

// Delete the agent and all its versions (force cascades to active sessions)
agentsClient.DeleteAgent(agentName: "my-code-agent", force: true);

# Delete one version
curl -X DELETE "$ENDPOINT/agents/$AGENT/versions/1?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

# Delete the agent and all its versions
curl -X DELETE "$ENDPOINT/agents/$AGENT?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

# Force-delete the agent (cascades to any active sessions)
curl -X DELETE "$ENDPOINT/agents/$AGENT?api-version=$API_VERSION&force=true" \
  -H "Authorization: Bearer $TOKEN"