Desplegar um agente hospedado

Este artigo mostra-lhe como implementar um agente containerizado para o Foundry Agent Service usando o SDK Python ou a API REST. Use estas abordagens quando quiser gerir implementações de agentes diretamente a partir das suas próprias aplicações ou serviços.

Se estiver a efetuar a implementação pela primeira vez ou quiser o caminho mais rápido, utilize o Quickstart: Criar e implementar um agente alojado . O quickstart utiliza a Azure Developer CLI (azd) ou a extensão do VS Code, que gerem automaticamente a construção, o lançamento, o controlo de versão e a configuração do RBAC.

Ciclo de vida de implementação

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

1. Construa e faça push — Empacote o código do seu agente numa imagem de contentor e envie-o para o Azure Container Registry.
2. Crie uma versão de agente — Registe a imagem no Foundry Agent Service. A plataforma fornece infraestrutura e cria uma identidade dedicada ao agente Entra.
3. Consultar estado — Aguardar até que o estado da versão alcance active.
4. Invocar — Enviar requisições para o endpoint dedicado do agente.

Pré-requisitos

• Um projeto Microsoft Foundry.
• Código de agente usando um framework suportado.
• Docker Desktop instalado para desenvolvimento local de contentores.
• Azure CLI versão 2.80 ou posterior.

Permissões necessárias

Precisas de um Azure AI Project Manager na definição do projeto para criar e implementar agentes alojados. Este papel inclui tanto as permissões do plano de dados para criar agentes como a capacidade de atribuir o papel de Utilizador de IA Azure à identidade do agente criado pela plataforma. A identidade do agente necessita do Azure AI User no projeto para aceder a modelos e artefactos em tempo de execução.

Se usar azd ou a extensão VS Code, a ferramenta gere automaticamente a maioria das atribuições RBAC, incluindo:

• Leitor de Repositório do Registo de Contentores para a identidade gerida do projeto (captura de imagens)
• Azure AI User para a identidade de agente criada pela plataforma (acesso a modelos em tempo de execução e a ferramentas)

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

Requisitos de contentores

A sua imagem de contentor deve cumprir os seguintes requisitos para funcionar na plataforma agente alojada.

Bibliotecas de protocolos

Os agentes alojados comunicam com o gateway Foundry através de bibliotecas de protocolos. Escolha o protocolo que corresponda ao padrão de interação do seu agente:

Um único contentor pode expor ambos os protocolos simultaneamente , declarando ambos quando cria o agente — no agent.yaml ficheiro, na chamada SDK ou no pedido da API REST — e importando ambas as bibliotecas. Use as bibliotecas de protocolos dentro do seu framework existente, seja Microsoft Agent Framework, LangChain ou código personalizado.

Endpoints de saúde

As bibliotecas de protocolos expõem automaticamente um /readiness endpoint para verificações de integridade da plataforma. Não precisas de implementar isto tu próprio.

Porto

Contentores servem o tráfego localmente no porto 8088 . Em produção, o gateway Foundry cuida do roteamento — o seu contenedor não precisa de expor uma porta pública.

Variáveis ambientais injetadas pela plataforma

A plataforma de agentes alojados injeta automaticamente variáveis de ambiente no seu contentor em tempo de execução. O seu código pode ler estas sem as declarar em agent.yaml ou environment_variables. O FOUNDRY_* prefixo é reservado para uso em plataformas.

Não redeclares variáveis injetadas pela plataforma em agent.yaml — elas são definidas automaticamente.

Variáveis que são declaradas por você, como ou toolbox endpoints MCP, devem ser colocadas na secção environment_variables de agent.yaml ou na chamada SDK create_version.

Empacota e testa o teu agente localmente

Antes de implementar no Foundry, valide que o seu agente funciona localmente usando a biblioteca de protocolos. O contentor serve os mesmos endpoints localmente que em produção.

Teste o protocolo Responses

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

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

Teste o protocolo de invocações

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

{
    "message": "Hello!"
}

Deploye usando o Azure Developer CLI ou VS Code

O Azure Developer CLI (azd) e a extensão VS Code automatizam todo o ciclo de vida da implementação. Para um guia passo a passo, consulte o Quickstart: Criar e implementar um agente alojado.

Implementar usando o SDK Python

Usa o SDK quando quiseres gerir implementações de agentes diretamente a partir de código Python.

Pré-requisitos adicionais

• Python 3.10 ou posterior

• Uma imagem de contentor em Azure Container Registry

• Papel de Escritor de Repositório do Registo de Contentores ou AcrPush no registo de contentores (para enviar imagens)

• Azure AI Projects SDK versão 2.1.0 ou posterior

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

Constrói e empurra a imagem do teu contentor

1. Constrói a tua imagem no Docker:

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

   Veja Dockerfiles de exemplo para Python e C#.

2. Efetuar o Push para o Azure Container Registry:

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

Configurar permissões de registo de contentores

Conceda acesso à identidade gerida do seu projeto para obter imagens.

1. No portal Azure, aceda ao recurso do seu projeto Foundry.

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

3. Atribui o papel de Leitor de Repositório do Registo de Contentores a esta identidade no teu registo de contentores. Veja Azure Container Registry funções e permissões.

Criar uma versão do agente hospedada

Criar uma versão faz com que a plataforma faça provisionar automaticamente o agente. Não existe uma etapa inicial separada — a plataforma constrói um snapshot de contentor e torna o agente pronto para atender pedidos.

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 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-chave:

Inquérito para o estado da versão

Depois de criar uma versão, verifique até que o estado atinja o active antes de invocar o agente. O provisionamento normalmente demora 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 estado da versão:

Invocar o agente

Depois de a versão atingir o estado active, 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 Invocations , chame diretamente o endpoint das 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 exemplos mais completos, consulte os exemplos de agentes hospedados.

Implementar usando a API REST

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

Antes de começar, constrói e divulga a imagem do teu contentor e configura permissões de registo de contentores.

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

Criar um agente também cria versões 1 e desencadeia o provisionamento.

Inquérito para o estado da versão

Consulta o endpoint de versão até status ser 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

Use o endpoint dedicado do agente para enviar os pedidos. Definir "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

Implemente código ou configuração atualizada 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"
      }
    }
  }'

Limpeza de recursos

Para evitar cobranças, limpe os recursos quando terminar. Os recursos computacionais do agente são desprovisionados após 15 minutos de inatividade do agente, por isso não há custo quando o agente não está a processar pedidos.

Limpeza da CLI do Azure Developer

azd down

Limpeza do SDK

Apague uma única versão:

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

Ou apagar o agente inteiro e todas as suas versões:

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

Limpeza da API REST

Apague uma única versão:

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

Ou apagar o agente inteiro:

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

Solução de problemas

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

Para erros 5xx, contacte o suporte da Microsoft.

Para requisitos detalhados de RBAC e resolução de problemas de permissões, consulte Referência de permissões de agente hospedado.

Próximos passos

Conteúdo relacionado

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