Desenvolver um agente em servidor

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.

Utilize o guia Quickstart: Criar e desdobrar um agente alojado se for a primeira vez que está a implementar ou se quiser o caminho mais rápido. O início rápido utiliza a CLI do Desenvolvedor Azure (azd) ou a extensão VS Code, que tratam automaticamente da compilação, lançamento, controlo de versão e configuração RBAC.

Ciclo de vida de implementação

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

1. Build e push — Embala o código do teu agente numa imagem de contentor e publica-a no 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 o estado — Aguardar que o estado da versão atinja 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.
• CLI do Azure versão 2.80 ou posterior.

Permissões necessárias

É necessário Azure AI Project Manager no âmbito 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 Azure IA à identidade do agente criado pela plataforma. A identidade do agente precisa de 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 pelo projeto (imagens extraídas)
• Azure AI User para a identidade do agente criado pela plataforma (modelo de execução e acesso à ferramenta)

Para 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 do agente hospedado.

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 o 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 trata do direcionamento — o seu contenedor não precisa 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 declaras, como endpoints de toolbox MCP, vão para a secção environment_variables de agent.yaml ou a chamada create_version do SDK.

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 tanto localmente como 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 Invocações

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

{
    "message": "Hello!"
}

Implementar usando o Azure Developer CLI ou VS Code

A 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"
  

Construa e publique a imagem do 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. Envio 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 à identidade gerida do seu projeto acesso 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 de 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 seja 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 ligado 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 as amostras de agentes alojados.

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

Utilize o endpoint dedicado do agente para enviar 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"
      }
    }
  }'

Liberar recursos

Para evitar cobranças, limpe os recursos quando terminar. A capacidade computacional do agente é liberada após 15 minutos de inatividade, por isso não há custo quando um agente não está a processar solicitações.

Limpeza do Azure Developer CLI

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"

Resoluçã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
• Aplicações para agentes
• Documentação do Azure Container Registry