Implantar um agente hospedado

Este artigo mostra como implantar um agente em contêineres no Serviço do Foundry Agent usando o SDK do Python ou a API REST. Use essas abordagens quando quiser gerenciar implantações de agente diretamente de seus próprios aplicativos ou serviços.

Se você estiver implantando pela primeira vez ou quiser o caminho mais rápido, use o Início Rápido: Criar e implantar um agente hospedado . O início rápido usa a CLI do Desenvolvedor do Azure (azd) ou a extensão do VS Code, que manipula a criação, o envio por push, o controle de versão e a configuração do RBAC automaticamente.

Ciclo de vida da implantação

Cada implantação de agente hospedado segue esta sequência:

1. Compilar e enviar – empacotar o código do agente em uma imagem de contêiner e enviá-la para o Azure Container Registry.
2. Criar uma versão do agente – registre a imagem com o Serviço Foundry Agent. A plataforma provisiona a infraestrutura e cria uma identidade de agente do Entra dedicada.
3. Sondar o status — aguarde até que o status da versão alcance active.
4. Invocar – Enviar solicitações para a interface dedicada do agente.

Pré-requisitos

• Um projeto Microsoft Foundry.
• Código do agente usando uma estrutura com suporte.
• Docker Desktop instalado para desenvolvimento de contêiner local.
• CLI do Azure versão 2.80 ou posterior.

Permissões necessárias

Você precisa do Gerenciador de Projetos de IA do Azure no escopo do projeto para criar e implantar agentes hospedados. Essa função inclui as permissões do plano de dados para criar agentes e a capacidade de atribuir a função de usuário de IA do Azure à identidade do agente criada pela plataforma. A identidade do agente precisa do usuário de IA do Azure no projeto para acessar modelos e artefatos em runtime.

Se você usar azd ou a extensão do VS Code, a ferramenta manipulará a maioria das atribuições de RBAC automaticamente, incluindo:

• Leitor do Repositório do Registro de Contêiner para a identidade gerenciada do projeto (extração de imagens)
• Usuário de IA do Azure para a identidade do agente criada pela plataforma (modelo de runtime e acesso à ferramenta)

Para obter mais informações, confira Autenticação e autorização.

Requisitos de contêiner

Sua imagem de contêiner deve atender aos seguintes requisitos para ser executada na plataforma do agente hospedado.

Bibliotecas de protocolo

Os agentes hospedados se comunicam com o gateway do Foundry por meio de bibliotecas de protocolo. Escolha o protocolo que corresponde ao padrão de interação do agente:

Um único contêiner pode expor os dois protocolos simultaneamente declarando ambos quando você cria o agente — no agent.yaml arquivo, na chamada do SDK ou na solicitação da API REST — e importando ambas as bibliotecas. Use as bibliotecas de protocolo em sua estrutura existente, seja o Microsoft Agent Framework, o LangChain ou o código personalizado.

Pontos de verificação de integridade

As bibliotecas de protocolo expõem automaticamente um /readiness endpoint para checagens de saúde da plataforma. Você não precisa implementar isso por conta própria.

Porto

Os contêineres atendem o tráfego na porta 8088 localmente. Em produção, o gateway do Foundry manipula o roteamento – o contêiner não precisa expor uma porta pública.

Variáveis de ambiente injetadas na plataforma

A plataforma do agente hospedado injeta automaticamente variáveis de ambiente em seu contêiner em runtime. Seu código pode lê-los sem declará-los em agent.yaml ou environment_variables. O FOUNDRY_* prefixo é reservado para uso de plataforma.

Não redeclare variáveis injetadas na plataforma em agent.yaml : elas são definidas automaticamente.

Variáveis que você mesmo declara, como MODEL_DEPLOYMENT_NAME ou endpoints MCP do toolbox, vão na seção environment_variables de agent.yaml ou na chamada do SDK create_version.

Empacotar e testar seu agente localmente

Antes de implantar no Foundry, valide se o agente funciona localmente usando a biblioteca de protocolos. O contêiner atende aos mesmos pontos de extremidade localmente como em produção.

Testar o protocolo de respostas

POST http://localhost:8088/responses
Content-Type: application/json

{
    "input": "Where is Seattle?",
    "stream": false
}

Testar o protocolo Invocações

POST http://localhost:8088/invocations
Content-Type: application/json

{
    "message": "Hello!"
}

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

A CLI do Desenvolvedor do Azure (azd) e a extensão do VS Code automatizam o ciclo de vida de implantação completo. Para obter um passo a passo passo, consulte o Início Rápido: Criar e implantar um agente hospedado.

Implantar usando o SDK do Python

Use o SDK quando quiser gerenciar implantações de agente diretamente do código python.

Pré-requisitos adicionais

• Python 3.10 ou posterior

• Uma imagem de contêiner em Azure Container Registry

• Gravador do Registro de Contêiner ou AcrPush no registro de contêiner (para fazer push de imagens)

• SDK de Projetos de IA do Azure versão 2.1.0 ou posterior

  pip install "azure-ai-projects>=2.1.0"
  

Criar e enviar por push a imagem do contêiner

1. Crie sua imagem do Docker:

   docker build --platform linux/amd64 -t myagent:v1 .
   

   Consulte exemplos de Dockerfiles para Python e C#.

2. Enviar para o Registro de Contêiner do Azure:

   az acr login --name myregistry
   docker tag myagent:v1 myregistry.azurecr.io/myagent:v1
   docker push myregistry.azurecr.io/myagent:v1
   

Configurar permissões do Registro de Contêiner

Conceda acesso à identidade gerida do projeto para puxar imagens.

1. No portal Azure, acesse o recurso de projeto do Foundry.

2. Selecione Identidade e copie a ID do Objeto (principal) em Sistema atribuído.

3. Atribua a função Leitor do Repositório de Registro de Contêiner a essa identidade no registro de contêiner. Consulte Azure Container Registry funções e permissões.

Criar uma versão do agente hospedado

A criação de uma versão dispara a plataforma para provisionar o agente automaticamente. Não há uma etapa inicial separada: a plataforma cria um instantâneo de contêiner e prepara o agente para atender às solicitações.

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import HostedAgentDefinition, ProtocolVersionRecord, AgentProtocol
from azure.identity import DefaultAzureCredential

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create project client
credential = DefaultAzureCredential()
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=credential,
    allow_preview=True,
)

# Create a hosted agent version
agent = project.agents.create_version(
    agent_name="my-agent",
    definition=HostedAgentDefinition(
        container_protocol_versions=[
            ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="1.0.0")
        ],
        cpu="1",
        memory="2Gi",
        image="your-registry.azurecr.io/your-image:tag",
        environment_variables={
            "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
        }
    )
)

print(f"Agent created: {agent.name}, version: {agent.version}")

Para expor os dois protocolos, passe ambos em container_protocol_versions.

container_protocol_versions=[
    ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="1.0.0"),
    ProtocolVersionRecord(protocol=AgentProtocol.INVOCATIONS, version="1.0.0")
],

Parâmetros de chave:

Sondar o status da versão

Depois de criar uma versão, pressione até que o status seja active antes de invocar o agente. O provisionamento normalmente leva menos de um minuto, dependendo do tamanho da imagem.

import time

# Poll until the agent version is active
while True:
    version_info = project.agents.get_version(
        agent_name="my-agent",
        agent_version=agent.version
    )
    status = version_info["status"]
    print(f"Status: {status}")

    if status == "active":
        print("Agent is ready!")
        break
    elif status == "failed":
        print(f"Provisioning failed: {version_info['error']}")
        break

    time.sleep(5)

Valores de status de versão:

Invocar o agente

Depois que a versão atingir o status active, use get_openai_client para criar um cliente OpenAI vinculado ao endpoint do agente.

Para o protocolo Respostas :

# Create an OpenAI client bound to the agent endpoint
openai_client = project.get_openai_client(agent_name="my-agent")

response = openai_client.responses.create(
    input="Hello! What can you do?",
)

print(response.output_text)

Para o protocolo Invocações, acesse diretamente o endpoint de invocações.

import requests

token = credential.get_token("https://ai.azure.com/.default").token
url = f"{PROJECT_ENDPOINT}/agents/my-agent/endpoint/protocols/invocations"

response = requests.post(url, headers={
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
    "Foundry-Features": "HostedAgents=V1Preview"
}, params={"api-version": "v1"}, json={
    "message": "Process this task"
})

print(response.json())

Para obter exemplos mais completos, consulte os exemplos de agente hospedado.

Implantar usando a API REST

Use a API REST para implantações diretas baseadas em HTTP ou ao integrar com ferramentas personalizadas.

Antes de começar, crie e envie por push sua imagem de contêiner e configure permissões de registro de contêiner.

Definir variáveis

BASE_URL="https://{account}.services.ai.azure.com/api/projects/{project}"
API_VERSION="v1"
TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)

Criar um agente

curl -X POST "$BASE_URL/agents?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "definition": {
      "kind": "hosted",
      "image": "myacr.azurecr.io/my-agent:v1",
      "cpu": "1",
      "memory": "2Gi",
      "container_protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

A criação de um agente também cria a versão 1 e dispara o provisionamento.

Sondar o status da versão

Consultar o ponto de extremidade de versão até que status seja active:

while true; do
  STATUS=$(curl -s -X GET "$BASE_URL/agents/my-agent/versions/1?api-version=$API_VERSION" \
    -H "Authorization: Bearer $TOKEN" | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "active" ] && echo "Ready!" && break
  [ "$STATUS" = "failed" ] && echo "Provisioning failed." && exit 1
  sleep 5
done

Invocar o agente

Utilize o endpoint exclusivo do agente para enviar solicitações. Defina "stream": true para receber eventos enviados pelo servidor.

Protocolo de respostas:

curl -X POST "$BASE_URL/agents/my-agent/endpoint/protocols/openai/responses?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Hello! What can you do?",
    "store": true
  }'

Protocolo de invocações:

curl -X POST "$BASE_URL/agents/my-agent/endpoint/protocols/invocations?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: HostedAgents=V1Preview" \
  -d '{
    "message": "Process this task"
  }'

Crie uma nova versão

Implante o código ou a configuração atualizados criando uma nova versão:

curl -X POST "$BASE_URL/agents/my-agent/versions?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": {
      "kind": "hosted",
      "image": "myacr.azurecr.io/my-agent:v2",
      "cpu": "1",
      "memory": "2Gi",
      "container_protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

Limpar os recursos

Para evitar custos, limpe os recursos ao terminar. A computação do agente é desprovisionada após 15 minutos de inatividade, portanto, não há custo quando um agente não está atendendo solicitações.

Limpeza da CLI de Desenvolvedores do Azure

azd down

Limpeza do SDK

Excluir uma única versão:

project.agents.delete_version(agent_name="my-agent", agent_version=agent.version)

Ou exclua todo o agente e todas as suas versões:

project.agents.delete(agent_name="my-agent")

Limpeza da API REST

Excluir uma única versão:

curl -X DELETE "$BASE_URL/agents/my-agent/versions/1?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

Ou exclua todo o agente:

curl -X DELETE "$BASE_URL/agents/my-agent?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

Resolução de problemas

Erros de provisionamento aparecem nos campos error.code e error.message do objeto de versão. Verifique o status da versão após a criação para identificar problemas.

Para erros 5xx, entre em contato com Microsoft suporte.

Para obter requisitos de RBAC detalhados e solução de problemas de permissão, consulte a referência de permissões do agente hospedado.

Próximas etapas

Conteúdo relacionado

• O que são agentes hospedados?
• Conceitos de identidade do agente
• Publicar e compartilhar agentes
• Documentação do Azure Container Registry