Implantar um agente hospedado a partir do código-fonte

Este artigo mostra como implantar um agente hospedado no Foundry Agent Service a partir de código-fonte em Python ou .NET, sem criar nem enviar uma imagem de contêiner. Você faz upload de um .zip do seu código (e, opcionalmente, das suas dependências), e o Agent Service o executa como está ou compila suas dependências para você na nuvem.

Dica

Para a maioria dos cenários, implante com o Azure Developer CLI (azd) ou o Foundry Toolkit for VS Code. Essas ferramentas fazem o trabalho pesado para você: empacotam seu código-fonte, fazem o upload dele, consultam periodicamente active e configuram automaticamente o controle de acesso baseado em funções. Para começar, siga o Início Rápido: implante seu primeiro agente hospedado e escolha Código (ou Código-Fonte (upload zip)) quando solicitado para um método de implantação.

Use os procedimentos SDK e REST neste artigo quando precisar implantar agentes de código-fonte programaticamente , do SDK Python ou do SDK .NET em seus próprios aplicativos ou diretamente pela API REST para ferramentas personalizadas, automação independente de linguagem ou integração com sistemas de entrega contínua existentes. Neste artigo, você concluirá as seguintes tarefas:

  • Escolha um modo de resolução de dependência e empacote sua origem.
  • Crie o agente, aguarde até que ele alcance activee invoque-o.
  • Atualizar, ver a versão, baixar e transmitir os logs do agente implantado.

Se você precisar de controle total da imagem de runtime ou já tiver um Dockerfile funcionando, use o caminho baseado em contêiner: implantar um agente hospedado.

Pré-requisitos

  • Um projeto Microsoft Foundry em uma região com suporte.
  • CLI do Azure versão 2.80 ou posterior, conectado ao locatário proprietário do projeto.

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

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

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

Runtimes suportados

O code_configuration.runtime campo na definição do agente aceita os valores a seguir. Escolha o runtime correspondente aos binários no zip – rodas x86_64 linux para Python ou o TargetFramework da saída dotnet publish para .NET.

Linguagem Valores de runtime
Python python_3_13, python_3_14
.NET dotnet_10

Política de suporte à versão do idioma

O ambiente de execução do Serviço de Agente inclui a imagem de contêiner gerada pela plataforma para cada valor de code_configuration.runtime. Para manter os agentes implantados totalmente compatíveis, o Foundry alinha o suporte à linguagem do agente hospedado com suporte de fim de vida útil para cada idioma. O suporte termina na data de encerramento do suporte pela comunidade para a versão de idioma. Microsoft pode desativar um valor code_configuration.runtime anteriormente quando restrições de plataforma (como a imagem base subjacente) exigem isso.

Para cronogramas upstream de fim de suporte, consulte:

Fase de retirada

Após uma data de fim de vida útil do idioma, você ainda pode criar, atualizar e executar agentes hospedados que usem o valor de runtime desativado. No entanto, esses agentes não têm direito a suporte, novos recursos nem patches de segurança até que você os atualize para um runtime com suporte, definindo um valor atual para code_configuration.runtime e fazendo nova implantação.

Permissões necessárias

Você precisa ter a função Gerenciador de Projeto do Foundry no escopo do projeto para implantar um agente hospedado. Essa função concede permissões de plano de dados para criar e atualizar agentes, além da capacidade de criar atribuições de função para a identidade do agente criada pela plataforma, se necessário. Para obter um detalhamento das permissões envolvidas, consulte a referência de permissões do agente hospedado.

Importante

As funções RBAC do Foundry foram renomeadas recentemente. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager eram anteriormente chamados de Usuário do Azure AI, Proprietário do Azure AI, Proprietário da conta do Azure AI e Gerente de Projeto do Azure AI. Você ainda pode ver os nomes anteriores em alguns lugares enquanto essa mudança de nome está sendo implementada. Os IDs das funções e as permissões principais não são alterados com a mudança de nome.

Seu agente é executado usando uma identidade gerenciada atribuída pela plataforma, separada da sua identidade de usuário. Essa identidade tem acesso à inferência de modelos por meio do endpoint do projeto e do armazenamento de sessão por padrão. Para recursos externos (por exemplo, seu próprio Armazenamento do Azure), atribua funções RBAC manualmente à Microsoft Entra ID do agente. Para obter mais informações, consulte o acesso do Agente além dos padrões.

Ciclo de vida da implantação

Cada implantação de código-fonte segue a mesma sequência: pacote -> criar ou atualizar -> sondar até active -> invocar. O caminho do código-fonte usa code_configuration na definição do agente. O caminho baseado em imagem usa container_configuration em vez disso. Essas duas opções são mutuamente exclusivas em uma única versão.

Escolha o caminho que se ajusta ao fluxo de trabalho. Se você não tiver certeza, comece com a CLI do desenvolvedor Azure ou o VS Code, é o caminho recomendado para a maioria dos clientes.

Caminho Melhor para Embalagem
Azure Developer CLI ou VS Code A maioria das implantações, incluindo as primeiras implantações e o loop interno mais rápido. A ferramenta cria e carrega o zip para você.
SDK do Python Implantação programática a partir de aplicativos em Python ou automação. Você cria o zip; o SDK o carrega.
SDK do .NET Implantação programática por meio de aplicativos .NET ou automação. O SDK compacta uma pasta para você.
REST API Ferramentas personalizadas, automação independente de linguagem e sistemas de CD. Você cria o arquivo ZIP e envia a requisição multipart.

Escolha como as dependências são resolvidas

Antes de começar, escolha um valor para code_configuration.dependency_resolution. Essa escolha afeta o que você inclui no arquivo ZIP.

Valor Behavior Usar quando
remote_build O Serviço de Agente instala dependências de requirements.txt (Python) ou restaura o arquivo de projeto (.NET) durante o provisionamento. Você deseja um pequeno upload e o loop interno mais simples. Recomendado para usuários iniciantes.
bundled O arquivo ZIP é executado como está. Você fornece dependências de Linux pré-compiladas em packages/ (Python) ou dotnet publish de saída (.NET). Você precisa de compilações reproduzíveis, pois as dependências são privadas ou apenas rodas, ou o projeto não é restaurado de maneira limpa no servidor.

Para o modo de pacote, consulte Gerar o arquivo zip manualmente para ver os comandos de compilação locais.

Requisitos de firewall para redes virtuais privadas

Se proteger o seu projeto com uma rede virtual privada, atualize a sua política de rede para permitir ligações de saída aos seguintes pontos finais antes de implementar.

Todas as implantações de código-fonte exigem acesso de saída para:

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

Para a configuração de rede, consulte Implantar um agente hospedado em uma rede virtual.

Implantar usando a CLI do Desenvolvedor do Azure ou o VS Code

O Azure Developer CLI (azd) e o Foundry Toolkit para VS Code automatizam todo o ciclo de vida de implantação do código-fonte: empacotam seu código-fonte em um arquivo zip, calculam o SHA-256, fazem upload dele, monitoram active e configuram o controle de acesso baseado em função (RBAC) para você. Essas ferramentas são o caminho recomendado para a maioria dos clientes e o loop interno mais rápido.

Para obter um passo a passo, confira o Início Rápido: Implantar seu primeiro agente hospedado. Escolha Código (ou Código-fonte (upload do ZIP)) quando o início rápido solicitar um método de implantação.

Selecionar implantação de código-fonte

Quando você executa azd ai agent init em modo interativo, a ferramenta solicita que você escolha um modo de implantação. Escolha código para implantar a partir do código-fonte por upload de um arquivo ZIP, em vez de criar uma imagem de contêiner. A implantação de código é o modo padrão para Python e .NET agentes hospedados. O Foundry Toolkit para VS Code solicita o método de implantação da mesma maneira.

Para selecionar a implantação de código-fonte de forma não interativa, por exemplo, em um pipeline de CI/CD, passe --deploy-mode code. Esse modo requer --runtime e --entry-pointaceita um valor opcional --dep-resolution de remote_build (padrão) ou bundled:

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

Após a inicialização, azd grava as configurações de implantação do código-fonte no campo codeConfiguration do serviço azure.ai.agent em 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

Execute azd up para provisionar e implantar. Use --deploy-mode container somente quando quiser criar ou referenciar uma imagem de contêiner.

Use os caminhos do SDK ou da API REST nas seções a seguir quando precisar implantar de forma programática a partir do seu próprio aplicativo ou integrar-se às ferramentas existentes.

Implantar do código-fonte

Selecione seu idioma ou interface. Cada aba percorre o mesmo ciclo de vida: criar o agente, verificar periodicamente até que ele atinja active, invocá-lo e baixar o código implantado.

Use o SDK Python para implantar agentes de código-fonte de seus próprios aplicativos ou automação. Você cria o zip por conta própria e passa seus bytes e SHA-256 para o SDK, que o carrega e expõe as mesmas operações de criação, votação, invocação e download que a API REST. A implantação de código requer a azure-ai-projects versão 2.2.0 ou posterior.

Gerar o arquivo ZIP

O SDK do Python carrega um zip que você compila. Use o mesmo layout e as regras de resolução de dependências descritas em Empacote o arquivo zip manualmente. O pacote mínimo remote_build é um arquivo ZIP sem subpastas, 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,
    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}")

Para o protocolo Invocações, defina a protocol_versions entrada como ProtocolVersionRecord(protocol="invocations", version="1.0.0"). Para o protocolo de Invocations (WebSocket), use ProtocolVersionRecord(protocol="invocations_ws", version="1.0.0"). Para o modo bundled, defina dependency_resolution="bundled" e inclua dependências pré-compiladas no arquivo zip. Para obter mais informações, consulte Criar dependências do Linux localmente.

Sondagem de ativo

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 status e como ler o objeto error em caso de falha.

Invocar o agente

Depois que a versão atingir active, vincule um cliente OpenAI ao ponto de extremidade do agente e faça a chamada. Este exemplo usa o protocolo Respostas:

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, chame diretamente o ponto de extremidade de invocação com um token Bearer, conforme mostrado em Invocar o agente.

Baixar o zip implantado

Verifique exatamente o que é implantado baixando o zip e comparando seu SHA-256 com o valor que você 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.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 ver um exemplo completo e executável, consulte os exemplos de agente hospedado em Python.

Compacte o arquivo ZIP manualmente

Se você usar azd, ignore esta seção — azd gera o arquivo zip para você. Leia-a se você usar a API REST, se mudar para a resolução de dependência agrupada ou se precisar de controle total sobre o conteúdo de upload.

O zip deve ser simples na raiz, sem pasta de wrapper de nível superior.

Selecione a aba correspondente ao idioma do agente.

layout do Python (modo de compilação remota)

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

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

Layout do Python (modo empacotado)

Você envia dependências do Linux predefinidas 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

Criar dependências do Linux localmente (agrupadas, Python)

Use a marcação da plataforma manylinux2014_x86_64 para que pip baixe rodas do Linux até mesmo pelo Windows ou pelo 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 rodas (sem compilações de código-fonte). O --python-version deve corresponder ao valor de runtime na definição do agente.

Warning

Erros comuns de empacotamento que causam session_creation_failed ou ModuleNotFoundError:

  • Encapsulando a origem em uma pasta (my-agent/main.py em vez de main.py na raiz).
  • Inclusão de arquivos .whl brutos em packages/, em vez de módulos extraídos.
  • Empacotar binários do Windows (.pyd, .dll) para um ambiente de execução Linux.

Limits

Limit Valor
Tamanho máximo do zip (upload de várias partes) 250 MB

Para ver as combinações compatíveis de cpu e memory, consulte Tamanhos de sandbox.

Troubleshooting

Sintoma Causa provável Corrigir
401 Unauthorized Token ausente ou com escopo incorreto Obtenha um token com --resource https://ai.azure.com.
403 Forbidden O chamador não tem controle de acesso baseado em função no projeto Conceda Consumidor do Agente de Fundição (para invocar apenas) ou Usuário de Fundição (para também desenvolver) no escopo do projeto.
409 conflict na criação (Agent '<name>' already exists) O nome do agente já existe Use Atualização (POST /agents/{name}) ou escolha um novo nome.
400 bad_request (CPU and Memory must be specified as a valid resource tier) em Criar ou Atualizar cpu / memory não são uma das camadas com suporte Defina cpu e memory como um par válido de tamanhos de sandbox.
400 bad_request (Agent version is still being provisioned) na invocação Uma nova versão está em implantação, e a versão ativa está sendo substituída. Verifique a versão status até active e, em seguida, tente novamente.
424 session_not_ready na invocação O contêiner foi iniciado, mas /readiness não retornou HTTP 200 dentro do tempo limite Transmita logs com :logstream, corrija a investigação de preparação ou o erro de inicialização e reimplante.
409 conflict no agente DELETE (Agent has active sessions) Sessões abertas bloqueiam a exclusão Aguarde as sessões ficarem ociosas ou acrescente &force=true a sessões de exclusão em cascata.
Versão presa em creating (>10 min, criação remota) Falha no build do servidor ou não foi possível resolver requirements.txt Alterne para dependency_resolution: bundled e pré-compile localmente.
A implantação falha em uma rede virtual privada Os pontos de extremidade de saída necessários estão bloqueados pelo firewall Permita os endpoints listados em Requisitos de firewall para redes virtuais privadas e, em seguida, implante novamente.
A versão passa para failed Layout zip incorreto, erro de sintaxe ou (remote_build) uma falha de restauração/compilação Leia o objeto error da versão primeiro— error.code classifica a falha e error.message contém a linha de erro de restauração ou compilação subjacente (pip for Python, NuGet for .NET) e um link de solução de problemas. Verifique a estrutura da pasta. Use :logstream somente depois que o contêiner for iniciado.
ModuleNotFoundError em tempo de execução packages/ ausente, contém arquivos .whl brutos ou tem binários Windows Recrie com pip install --target packages/ --platform manylinux2014_x86_64 --only-binary=:all:.
409 AgentNotCodeBased durante o download O agente é baseado em imagem Consulte a documentação de implantação baseada em contêineres.

Limpar os recursos

Se você tiver feito o scaffolding do projeto pelo Início Rápido com azd, execute azd down na raiz do projeto para remover todo o ambiente provisionado.

Para excluir um agente implantado com o SDK ou a API REST, use o caminho correspondente abaixo.

# 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

Excluir um agente remove todas as suas versões e encerra as sessões ativas. Esta ação não pode ser desfeita.

Próximas Etapas 

Gerenciar o ciclo de vida do agente hospedado

Conteúdo relacionado

  • Last updated on