Distribuire un agente ospitato dal codice sorgente (anteprima)

• pip da Python 3.13 o versione successiva, per creare localmente un pacchetto sorgente.

• La azure-ai-projects versione 2.2.0 o successiva e azure-identity i pacchetti.

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

• SDK .NET 10, per creare localmente un pacchetto del codice sorgente.

• Pacchetti Azure.AI.Projects.Agents e Azure.Identity.

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

• Un client HTTP da riga di comando, curl ad esempio (gli esempi REST in questo articolo usano curl).
• Per creare localmente un pacchetto del codice sorgente, installa la toolchain per la lingua del tuo agente: pip da Python 3.13 o versione successiva oppure .NET 10 SDK.

Utilizza l'SDK Python per distribuire agenti basati su codice sorgente dalle tue applicazioni o automazioni. Si compila il file ZIP manualmente e si passano i byte e SHA-256 all'SDK, che lo carica ed espone le stesse operazioni di creazione, polling, richiamo e download dell'API REST. La distribuzione del codice richiede azure-ai-projects la versione 2.2.0 o successiva.

La distribuzione del codice sorgente usa l'interfaccia client in anteprima beta, quindi crea il client con allow_preview=True.

Compilare il file ZIP

L'SDK di Python carica un file ZIP compilato. Usare le stesse regole di layout e risoluzione delle dipendenze descritte in Creare manualmente il pacchetto zip. Il payload minimo remote_build è un file ZIP piatto con main.py e requirements.txt nella radice.

Creare l'agente

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

Per il protocollo Invocations, impostare la voce protocol_versions su ProtocolVersionRecord(protocol="invocations", version="1.0.0"). Per il protocollo Invocazioni (WebSocket), usa ProtocolVersionRecord(protocol="invocations_ws", version="1.0.0"). Per la modalità bundled, impostare dependency_resolution="bundled" e includere nel file ZIP le dipendenze precompilate. Per altre informazioni, vedere Creare dipendenze Linux in locale.

Eseguire il polling per l'attività attiva

I metodi di distribuzione del codice (create_version_from_code e download_code) si trovano nell'area di anteprima project.beta.agents , ma le operazioni di lettura ed eliminazione, get_version ad esempio sono in 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)

Per l'elenco completo dei valori di stato e per sapere come leggere l'oggetto in caso di errore, vedere error.

Invocare l'agente

Dopo che la versione raggiunge active, associare un client OpenAI all'endpoint dell'agente e chiamarlo. Questo esempio usa il protocollo Responses:

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)

Per il protocollo Invocations, chiamare direttamente l'endpoint invoke con un token bearer, come mostrato in Invocare l'agente.

Scaricare il file ZIP distribuito

Verificare esattamente ciò che viene distribuito scaricando il file ZIP e confrontando sha-256 con il valore caricato:

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

Per un esempio eseguibile completo, vedere gli esempi Python hosted-agent.

Usa l'SDK .NET per distribuire agenti del codice sorgente dalle tue applicazioni o automazioni. A differenza delle modalità Python e REST, l'SDK .NET comprime per te una cartella di origine: si specifica il percorso di una cartella invece di creare manualmente il file ZIP.

La distribuzione del codice sorgente è una funzionalità di anteprima. Sopprimere l'avviso AAIP001 sperimentale e aggiungere l'intestazione della funzionalità di anteprima a ogni chiamata tramite un criterio della pipeline.

Creare l'agente

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

Con remote_build, indirizzare filePath a una cartella contenente i file sorgente del progetto .NET. Il servizio Agent esegue dotnet restore e dotnet publish per l'utente durante il provisioning. entryPoint si riferisce al nome dell'assembly pubblicato, per esempio ["dotnet", "MyAgent.dll"] per un progetto denominato MyAgent.csproj.

FeaturePolicy è un piccolo PipelinePolicy che aggiunge l'intestazione Foundry-Features a ogni richiesta:

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

Per il protocollo Invocations, modificare la voce Versions su new ProtocolVersionRecord(ProjectsAgentProtocol.Invocations, "1.0.0"). Per il protocollo Invocazioni (WebSocket), utilizzare new ProtocolVersionRecord(ProjectsAgentProtocol.InvocationsWs, "1.0.0"). Per la modalità bundled, impostare dependencyResolution: CodeDependencyResolution.Bundled e far puntare filePath a una cartella che contiene l'output dotnet publish. Vedere Build .NET output (bundled).

Eseguire il polling per l'attività attiva

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

Scaricare il codice distribuito

Scaricare ed estrarre il codice distribuito in una directory locale per verificare cosa è in esecuzione. L'SDK scrive il contenuto decompresso in path:

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

Per un esempio eseguibile completo, vedere gli esempi .NET hosted-agent.

È possibile usare l'API REST per distribuzioni dirette basate su HTTP o strumenti personalizzati. Le sezioni illustrano una prima distribuzione nell'ordine: configurare le variabili, compilare un file ZIP, creare l'agente, eseguire il polling fino a activee richiamarlo. Gli endpoint di aggiornamento, versione, download e flusso di log sono raggruppati in Operazioni in corso.

Distribuire usando l'API REST

Usare l'API REST per distribuzioni dirette basate su HTTP o strumenti personalizzati. Le sezioni seguenti illustrano una prima distribuzione in ordine: configurare le variabili, compilare un file ZIP, creare l'agente, eseguire il polling fino a activee richiamarlo. Gli endpoint di aggiornamento, versione, download e flusso di log sono raggruppati in Operazioni in corso.

Configurare le variabili

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

Crea un archivio ZIP hello-world minimo

Prima di chiamare Create, compilare un file ZIP flat con due file. Questo è il payload minimo accettato da Agent Service per una distribuzione Python remote_build.

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 (la definizione dell'agente illustrata nell'esempio di metadati) si trova accanto al file ZIP sul disco e viene inviata come parte multipart separata, non si trova all'interno del file ZIP. Per i layout completi (inclusi la modalità bundled e .NET), consulta Creare manualmente il pacchetto zip. Per i file di origine funzionanti, vedere gli esempi Python e .NET.

Struttura della richiesta multipart

Tutti gli endpoint di modifica (Crea, Aggiorna) usano multipart/form-data con due parti:

Intestazioni obbligatorie su ogni chiamata multipart:

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

L'intestazione x-ms-code-zip-sha256 registra SHA-256 del file ZIP caricato. Il servizio lo archivia e lo ripete in code:download modo da poter rilevare la deviazione tra ciò che si prevede di distribuire e ciò che viene distribuito. Includilo sempre.

La chiamata Create richiede anche x-ms-agent-name: <agent-name>. Le chiamate di aggiornamento lo omettono perché il nome fa già parte dell'URL.

Esempio di metadati (compilazione remota, risposte)

Questi metadati corrispondono al file ZIP 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-5.4-mini"
    }
  }
}

Per il protocollo Invocations, sostituisci la voce protocol_versions con { "protocol": "invocations", "version": "1.0.0" }. Per il protocollo Invocazioni (WebSocket), utilizzare { "protocol": "invocations_ws", "version": "1.0.0" }. Per la modalità bundled, imposta "dependency_resolution": "bundled" e segui Compilare localmente le dipendenze Linux.

code_configuration e container_configuration si escludono a vicenda nella definizione dell'agente: includere code_configuration per la distribuzione del codice sorgente (questo articolo) o container_configuration per la distribuzione basata su immagini. Vedere Distribuire un agente ospitato (contenitore) per la variante di immagine.

Creare l'agente

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 è obbligatorio solo nella chiamata Crea. Il nome deve iniziare e terminare con caratteri alfanumerici, può contenere trattini al centro e non deve superare i 63 caratteri. La risposta comprende un status iniziale di creating.

Eseguire il polling per l'attività attiva

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

Invocare l'agente

Selezionare il protocollo dichiarato dall'agente in protocol_versions.

Protocollo di risposte:

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-5.4-mini","input":"Hello, agent!","stream":false}'

Protocollo invocazioni:

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

Protocollo Invocazioni (WebSocket):

Connettersi tramite un upgrade WebSocket invece di REST POST. Per gli esempi di formato dell'endpoint e client, vedere Creare un agente vocale con agenti ospitati.

Intestazioni di risposta utili:

Per il protocollo Risposte, l'identificatore di risposta per chiamata è il id campo nel corpo JSON della risposta (ad esempio, caresp_<random>). Usarlo per correlare la chiamata con i log del contenitore o per fare riferimento alla chiamata in una richiesta di supporto.

Operazioni in corso

Dopo la prima distribuzione, usare questi endpoint per evolvere e gestire l'agente.

Aggiornare o versionare un agente

Per distribuire una modifica del codice o un aggiornamento di una definizione, ripubblicare il contenuto multipart alla risorsa dell'agente. Il servizio usa un versionamento basato sul contenuto: una nuova versione viene generata solo quando lo SHA-256 del file ZIP o la definizione dell'agente cambiano effettivamente. Le ripubblicazioni identiche restituiscono l'ultima versione già esistente.

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"

La risposta è la busta completa dell'agente con versions.latest compilato. Sondare la versione risultante come mostrato in Poll per active.

Se gli strumenti preferiscono una risposta nel formato della versione (il solo AgentVersionObject anziché l’involucro dell’agente), inviare lo stesso corpo multipart a $ENDPOINT/agents/$AGENT/versions?api-version=$API_VERSION. La regola di deduplicazione è identica, entrambi gli endpoint condividono la stessa logica indirizzabile al contenuto.

Scaricare il file ZIP distribuito

Verificare esattamente ciò che viene distribuito scaricando il file ZIP. Omettere agent_version per scaricare la versione più recente; passare agent_version=<n> per specificare una versione particolare.

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"

Due intestazioni di risposta consentono di confermare ciò che è stato scaricato:

Gli agenti basati su immagini restituiscono 409 AgentNotCodeBased.

Trasmettere i log dei contenitori

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

I log vengono recapitati come eventi inviati dal server. {sessionId} è il valore di x-agent-session-id dalla risposta invoke. Usare questo endpoint per eseguire il debug di arresti anomali in fase di esecuzione e risposte 424 session_not_ready. L'endpoint di streaming dei log non richiede l'intestazione di anteprima Foundry-Features.

layout Python (modalità di compilazione remota)

Il servizio installa le dipendenze nel cloud da requirements.txt.

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

layout di Python (modalità integrata)

Le dipendenze predefinite di Linux vengono fornite in packages/.

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

Compilare le dipendenze di Linux in locale (incluso, Python)

Usare il tag della piattaforma manylinux2014_x86_64 in modo che pip scarica le ruote Linux anche da Windows o 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: forza le ruote (nessuna creazione dell'origine). Il --python-version deve corrispondere al valore di runtime nella definizione dell'agente.

layout di .NET (modalità di compilazione remota)

Comprimere solo i sorgenti del progetto, senza output bin/, obj/ o publish/. Il servizio Agent esegue dotnet restore e dotnet publish per l'utente durante il provisioning.

agent-code.zip
+-- MyAgent.csproj
+-- Program.cs
+-- ... (additional .cs files)

Il entry_point impostato nella definizione dell'agente continua a fare riferimento al nome dell'assembly pubblicato (ad esempio, ["dotnet", "MyAgent.dll"]), prodotto dalla pubblicazione lato server.

layout .NET (modalità aggregata)

Comprimere l'output di dotnet publish -c Release -r linux-x64 --self-contained false radicato direttamente nel file ZIP:

agent-code.zip
+-- MyAgent.dll
+-- MyAgent.runtimeconfig.json
+-- ... (publish output)

Uscita creazione .NET (in pacchetto)

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

Usare --self-contained true se si vuole spedire il runtime di .NET nel file ZIP. L'oggetto runtime impostato nella definizione dell'agente deve corrispondere a TargetFramework.

Vedere le schede Python o 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"