Implementar um agente hospedado a partir do código-fonte (pré-visualização)

• pip a partir do Python 3.13 ou posterior, para empacotar o código-fonte localmente.

• azure-ai-projects versão 2.2.0 ou posterior e os pacotes azure-identity.

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

• O SDK .NET 10, para empacotar a sua fonte localmente.

• Os pacotes Azure.AI.Projects.Agents e Azure.Identity.

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

• Um cliente HTTP de linha de comandos, como curl (os exemplos REST neste artigo usam curl).
• Para empacotar o seu código-fonte localmente, instale a cadeia de ferramentas para a linguagem do seu agente: pip a partir de Python 3.13 ou posterior, ou o SDK .NET 10.

Use o SDK Python para implementar agentes de código-fonte a partir das suas próprias aplicações ou automação. Cria tu mesmo o ficheiro ZIP e passa os respetivos bytes e o SHA-256 ao SDK, que o carrega e expõe as mesmas operações de criação, consulta do estado, invocação e transferência que a API REST. A implementação do código requer a versão 2.2.0 ou superior do azure-ai-projects.

A implementação a partir do código-fonte utiliza a interface de cliente em pré-visualização beta, por isso, crie o cliente com allow_preview=True.

Compilar o ficheiro ZIP

O SDK Python carrega um código zip que tu constróis. Utilize a mesma disposição e as regras de resolução de dependências descritas em Criar o ficheiro zip manualmente. O pacote mínimo remote_build é um ficheiro ZIP simples com main.py e requirements.txt na raiz.

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

Para o protocolo Invocations, defina a entrada protocol_versions como ProtocolVersionRecord(protocol="invocations", version="1.0.0"). Para o bundled modo, defina dependency_resolution="bundled" e envie dependências pré-construídas no zip — veja Construir dependências Linux localmente.

Inquérito para ativos

Os métodos de implementação de código (create_version_from_code e download_code) estão disponíveis na superfície de pré-visualização project.beta.agents, mas as operações de leitura e de eliminação, como get_version, estão em 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)

Consulte Poll for active para a lista completa de valores de estado e como ler o error objeto em caso de falha.

Invocar o agente

Depois de a versão atingir active, vincula um cliente OpenAI ao endpoint do agente e chama-o. Este exemplo utiliza o protocolo 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)

Para o protocolo Invocations, chama diretamente o endpoint de invocação com um token de portador, como mostrado em Invocar o agente.

Descarregue o ficheiro ZIP implantado

Verifique exatamente o que está implementado descarregando o zip e comparando o SHA-256 com o valor que carregou:

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

Para um exemplo completo executável, veja as amostras Python hosted-agent.

Use o .NET SDK para implementar agentes de código-fonte a partir das suas próprias aplicações ou automação. Ao contrário dos caminhos Python e REST, o SDK .NET comprime uma pasta de origem para ti—passas um caminho de pasta em vez de construir o zip tu próprio.

A implementação de código-fonte é uma funcionalidade em versão preliminar. Suprima o AAIP001 aviso experimental e adicione o cabeçalho da funcionalidade de pré-visualização a cada chamada com uma política de pipeline.

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

Com remote_build, aponte filePath para uma pasta com .NET fontes de projeto. O Serviço de Agente executa dotnet restore e dotnet publish por si durante o aprovisionamento. O entryPoint refere-se ao nome de assembleia publicado — por exemplo, ["dotnet", "MyAgent.dll"] para um projeto chamado MyAgent.csproj.

FeaturePolicy é um pequeno PipelinePolicy que adiciona o cabeçalho Foundry-Features a cada pedido:

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

Para o protocolo Invocations, altere a Versions entrada para new ProtocolVersionRecord(ProjectsAgentProtocol.Invocations, "1.0.0"). Para o modo bundled, defina dependencyResolution: CodeDependencyResolution.Bundled e aponte filePath para uma pasta que contenha a saída de dotnet publish. Consulte saída da compilação do .NET (agrupada).

Inquérito para ativos

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

Descarregue o código implementado

Descarregue e extraia o código implementado para um diretório local para verificar o que está a correr. O SDK escreve os conteúdos descomprimidos em path:

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

Para obter um exemplo completo e executável, consulte os exemplos de agente alojado do .NET.

Use a API REST para implementações diretas baseadas em HTTP ou ferramentas personalizadas. As secções percorrem uma primeira implementação por ordem: configurar variáveis, construir um zip, criar o agente, inquirir até active, e invocá-lo. Os endpoints de atualização, versão, download e streaming de registos estão agrupados em Operações em curso.

Configurar variáveis

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

Criar um ficheiro ZIP hello-world mínimo

Antes de chamar o Criar, constrói um zip plano com dois ficheiros. Esta é a carga útil mínima que o Serviço de Agente aceita para uma implementação em 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 (a definição de agente mostrada no exemplo de Metadados) fica ao lado do zip no disco e é enviado como uma parte multiparte separada — não está dentro do zip. Para esquemas completos (incluindo o modo bundled e o .NET), consulte Empacotar o ficheiro ZIP manualmente. Para ficheiros fonte em funcionamento, veja os exemplos Python e .NET.

Formulário de pedido multicomponente

Todos os endpoints de modificação (Create, Update) usam multipart/form-data com duas partes:

Cabeçalhos obrigatórios em cada chamada multiparte:

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

O cabeçalho x-ms-code-zip-sha256 regista o SHA-256 do ficheiro ZIP que carregou. O serviço armazena-o e devolve-o em code:download, para que possas detetar o desvio entre o que esperavas implementar e o que está implementado. Inclua-o sempre.

A chamada Create também requer x-ms-agent-name: <agent-name>. As chamadas de atualização omitem-na porque o nome já faz parte do URL.

Exemplo de metadados (compilação remota, Responses)

Estes metadados correspondem ao ficheiro 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-4.1-mini"
    }
  }
}

Para o protocolo Invocations, substitua a protocol_versions entrada por { "protocol": "invocations", "version": "1.0.0" }. No modo bundled, defina "dependency_resolution": "bundled" e siga Compilar dependências do Linux localmente.

code_configuration e container_configuration são mutuamente exclusivos na definição do agente: inclua code_configuration para implementação de código-fonte (neste artigo) ou container_configuration para implementação baseada em imagem. Veja Implementar um agente alojado (contentor) para a variante de imagem.

Criar o 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 é necessário apenas na chamada Create. O nome deve começar e terminar com caracteres alfanuméricos, pode conter hífens no meio e não deve exceder os 63 caracteres. A resposta inclui uma inicial status de creating.

Inquérito para ativos

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

Invocar o agente

Escolha o protocolo que o seu agente declarou em protocol_versions.

Protocolo de respostas:

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

Protocolo de invocações:

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

Cabeçalhos úteis para respostas:

Para o protocolo Respostas, o identificador de resposta por chamada é o id campo no corpo JSON da resposta (por exemplo, caresp_<random>). Use-o para correlacionar a chamada com registos de contentores ou para referenciar a chamada num pedido de suporte.

Operações em curso

Após a tua primeira implementação, usa estes endpoints para evoluir e operar o agente.

Atualizar ou versionar um agente

Para aplicar uma alteração ao código ou uma atualização da definição, submeta novamente o corpo em várias partes ao recurso do agente. O serviço utiliza versionamento endereçado pelo conteúdo: uma nova versão só é gerada quando o SHA-256 do ficheiro ZIP ou a definição do agente realmente muda. Reposts idênticos devolvem a versão mais recente existente.

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"

A resposta é o envelope completo do agente com versions.latest preenchido. Inquirir a versão resultante conforme mostrado na Sondagem para ativo.

Se a sua ferramenta preferir uma resposta no formato de versão (um simples AgentVersionObject em vez do envelope do agente), envie o mesmo corpo multiparte para $ENDPOINT/agents/$AGENT/versions?api-version=$API_VERSION. A regra de deduplicação é idêntica — ambos os extremos partilham a mesma lógica de conteúdo endereçável.

Descarregue o ficheiro ZIP implantado

Verifica exatamente o que está implementado descarregando o zip. Omita agent_version para transferir a versão mais recente; indique agent_version=<n> para especificar uma versão específica.

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"

Dois cabeçalhos de resposta ajudam-no a confirmar o que descarregou:

Os agentes baseados em imagem retornam 409 AgentNotCodeBased.

Transmitir registos de contentores

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

Os registos são entregues como eventos enviados pelo servidor. {sessionId} é o valor de x-agent-session-id da resposta de invocação. Utilize este endpoint para depurar falhas em tempo de execução e respostas 424 session_not_ready. O endpoint de streaming de logs não requer o cabeçalho Foundry-Features de pré-visualização.

Layout Python (modo de construção remota)

O serviço instala dependências na cloud a partir de requirements.txt.

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

Layout Python (modo agrupado)

Envias dependências Linux pré-construídas em packages/.

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

Construir dependências Linux localmente (agrupado, Python)

Use a etiqueta de plataforma manylinux2014_x86_64 para que pip transfira wheels de Linux mesmo a partir do Windows ou do 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: força o uso de wheels (sem compilações a partir do código-fonte). O --python-version deve corresponder ao runtime valor na definição do agente.

Layout .NET (modo de construção remota)

Comprima apenas os ficheiros-fonte do projeto — sem saída de bin/, obj/ nem publish/. O Serviço de Agente executa dotnet restore e dotnet publish por si durante o aprovisionamento.

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

O entry_point que definiu na definição do agente continua a referir-se ao nome do assembly publicado (por exemplo, ["dotnet", "MyAgent.dll"]), produzido pela publicação no lado do servidor.

Layout .NET (modo agrupado)

Comprime a saída de dotnet publish -c Release -r linux-x64 --self-contained false root diretamente no zip:

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

Compilar saída do .NET (em pacote)

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

Usa --self-contained true se quiseres enviar o tempo de execução .NET no zip. O runtime que você define na definição do agente deve corresponder ao TargetFramework.

Veja os separadores do Python ou do 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"