Implantar um agente hospedado

Este artigo mostra como implantar um agente em contêineres no Serviço do Foundry Agent usando o SDK 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 Azure Developer (azd) ou a extensão do VS Code, que gerencia automaticamente a criação, o push, o controle de versão e a configuração do RBAC.

Ciclo de vida da implantação

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

1. Construir e enviar — Empacote o código do agente em uma imagem de contêiner e envie-a para o Registro de Contêiner do Azure.
2. Criar uma versão do agente – registre a imagem com o Serviço do 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 seja atingido active.
4. Invocar – Enviar solicitações para o endpoint dedicado 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 de Gerente de Projeto de Azure AI 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 Azure Usuário de IA à identidade do agente criada pela plataforma. A identidade do agente precisa de Azure AI User no projeto para acessar modelos e artefatos em tempo de execução.

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ções de imagem)
• Azure Usuário de IA para a identidade do agente criada pela plataforma (modelo de runtime e acesso à ferramenta)

Para obter mais informações, consulte 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 Microsoft Agent Framework, LangChain ou código personalizado.

Pontos de verificação de saúde

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

Porta

Os contêineres atendem o tráfego na porta 8088 localmente. Em produção, o gateway do Foundry cuida do roteamento, e o contêiner não precisa expor uma porta de rede 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ê declara, como MODEL_DEPLOYMENT_NAME ou pontos de extremidade MCP da caixa de ferramentas, são inseridas na seção environment_variables de agent.yaml ou na chamada do SDK create_version.

Empacote e execute teste no seu agente em ambiente local

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 de Invocações

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

{
    "message": "Hello!"
}

Implantar usando a CLI do desenvolvedor 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 completa. 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 de Python código.

Pré-requisitos adicionais

• Python 3.10 ou posterior

• Uma imagem de contêiner em Registro de Contêiner do Azure

• Escritor do Repositório de Registro de Contêiner ou AcrPush no registro de contêiner (para envio de imagens)

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

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

Compilar e efetuar push da 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. Envie por push para 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 gerenciada do projeto para efetuar pull de imagens:

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

2. Selecione Identidade e copie a ID do Objeto (principal) sob 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 Registro de Contêiner do Azure 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 ambos os protocolos, passe-os ambos no 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:

Consultar o status da versão

Depois de criar uma versão, verifique repetidamente 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 active status, use get_openai_client para criar um cliente OpenAI associado 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 de Invocações, chame 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.

Configurar 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.

Consultar o status da versão

Sondar 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 ponto de extremidade dedicado 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"
  }'

Criar 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 recursos

Para evitar custos, libere os recursos quando 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.

Ferramenta de Limpeza do CLI para 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"

Solucionando 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
• Aplicativos de agente
• Documentação do Registro de Contêiner do Azure