Início rápido: Otimizar um agente alojado (pré-visualização)

Neste quickstart, instala-se a extensão CLI de otimização, implementa-se um agente alojado, executa-se o otimizador de agentes e lança-se o candidato vencedor.

Pré-requisitos

A tua subscrição do Azure deve estar na lista de autorização do otimizador de agentes. Contacte o seu representante da Microsoft para solicitar acesso.

Instale a extensão CLI

Instala a azure.ai.agents extensão para a CLI do azd:

azd ext install azure.ai.agents

Verifique a instalação:

azd ai agent optimize --help

Criar o projeto

Inicialize um novo projeto a partir da amostra do otimizador de agentes. Crie uma pasta e depois use azd ai agent init com o manifesto de exemplo:

mkdir my-agent && cd my-agent
azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/responses/optimization-customer-support/agent.manifest.yaml .

O fluxo interativo solicita a sua subscrição do Azure, a região e as configurações de implementação do modelo. Descarrega o exemplo e gera agent.yaml, .agent_configs/baseline/, o conjunto de dados de avaliação e os ficheiros de infraestrutura como código para o aprovisionamento.

azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/responses/optimization-customer-support/agent.manifest.yaml -p "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>"

Authenticate

az login
azd auth login

Se tiver várias subscrições, selecione a que deseja:

az account set --subscription "<subscription-name-or-id>"

Configurar e aprovisionar

Escolha uma das seguintes opções consoante se precisa de criar novos recursos Azure ou se já tem um projeto Foundry existente.

Opção A: Criar novos recursos

Provisione os recursos do Azure. Este passo demora aproximadamente dois minutos:

azd provision

Este passo cria:

• Uma conta e um projeto Foundry
• Um Registro de Contêiner do Azure
• Implementações de modelos (gpt-4.1-mini para avaliação, gpt-5.4 para otimização)

Opção B: Utilizar um projeto existente da Foundry

Se já tem um projeto Foundry com modelos implementados, use agent init para configurar o seu ambiente:

azd ai agent init --project-id "/subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>"

Defina o nome de implementação do modelo:

azd env set AZURE_AI_MODEL_DEPLOYMENT_NAME "gpt-4.1-mini"

Implantar o agente

azd deploy

Este comando constrói a imagem do contentor, envia-a para o Azure Container Registry e regista o agente alojado. O processo demora aproximadamente 1,5 minutos. O resultado inclui um link do portal playground que pode usar para conversar com o agente.

Teste a implementação:

azd ai agent invoke "What is 2+2?"

Gerar conjuntos de dados personalizados e avaliações

Para otimização significativa com os seus próprios cenários, gere um conjunto de dados com eval init:

azd ai agent eval init --gen-instruction "You are a helpful customer support agent."

O comando cria um eval.yaml com um conjunto de dados e avaliadores ajustados ao domínio do seu agente.

Para mais detalhes, consulte Criar um conjunto de dados de avaliação.

Executar otimização

Depois, execute otimização com a configuração gerada:

azd ai agent optimize

A interface de linha de comandos lê o campo name do seu ficheiro agent.yaml para determinar qual o agente implementado a otimizar. Também irá detetar e usar automaticamente o ficheiro gerado eval.yaml para executar a otimização. Se tiver vários agentes ou configurações, ou se quiser especificar outro, use as opções --agent e --config:

azd ai agent optimize --agent <your-agent-name> --config <your-config-file>.yaml

Para mais detalhes sobre o direcionamento de agentes, consulte Que agente é otimizado.

O otimizador de agentes completa os seguintes passos:

1. Avalia o seu agente de referência contra um conjunto de dados incorporado que contém 3 tarefas e 12 critérios.
2. Gera candidatos melhorados (instruções, competências, ferramentas ou configurações de modelos, dependendo do seu alvo).
3. Avalia cada candidato.
4. Classifica os candidatos por pontuação.

Este processo demora alguns minutos. Vê progresso em tempo real:

Optimizing agent "customer-support-py"...
  Config: C:\Dev\my-agent\eval.yaml
  Baseline saved to .agent_configs\baseline\metadata.yaml
  Job ID: opt_162bd0f09070432c9ca4a699a908abb0
  Status: pending
  Portal: <OPTIMIZATION-JOB-URL>

Use o URL fornecido no CLI para visualizar e monitorizar o seu trabalho no portal da Foundry.

O modelo de avaliação pontua cada resposta (qualquer modelo de conclusão de chat funciona). O modelo de otimização gera candidatos melhorados e deve ser da lista suportada (família gpt-5 ou DeepSeek).

Implementar a versão vencedora

Indica ★ o melhor candidato. O fluxo de trabalho recomendado é aplicar a configuração otimizada localmente e depois implementar:

# Apply the winning candidate locally
azd ai agent optimize apply --candidate <candidate-id>

# Deploy with the optimized config
azd deploy

Isto transfere a configuração otimizada para .agent_configs/<candidate_id>/ no seu projeto. Na próxima implementação, o seu agente utiliza as instruções melhoradas e as descrições das ferramentas.

Alternativamente, para testes rápidos podes implementar diretamente:

azd ai agent optimize deploy --candidate <candidate-id>

A função load_config() do pacote azure-ai-agentserver-optimization carrega automaticamente a nova configuração durante o arranque.

Chame novamente o seu agente para verificar a melhoria:

azd ai agent invoke "What is your return policy?"

Também pode fazer uma avaliação separadamente para confirmar a melhoria da pontuação:

azd ai agent eval run

Monitorizar e gerir

Utilize o ID da tarefa, que tem o formato opt_<hex> e é impresso na saída da otimização, para monitorizar e gerir execuções:

# Watch a running job
azd ai agent optimize status <job-id> --watch

# List all optimization runs
azd ai agent optimize list

# Cancel a running job
azd ai agent optimize cancel <job-id>

Limpeza de recursos

Quando terminares de experimentar, elimina os recursos provisionados:

azd down --force --purge

Troubleshooting

Conteúdo relacionado

• Visão geral do otimizador de agentes
• Criar um conjunto de dados de avaliação
• Executa avaliações de agentes com o CLI azd
• Otimizar as instruções, competências, ferramentas e modelos do agente
• Prepare o seu otimizador de agentes