Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Importante
No momento, o Otimizador de Agente está em versão prévia limitada e só está disponível por meio de um processo de inscrição. Para acessar o serviço, preencha o formulário de entrada. Essa versão prévia é fornecida sem um contrato de nível de serviço e não recomendamos isso para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares para Versões Prévias do Microsoft Azure.
Neste início rápido, você instala a extensão da CLI de otimização, implanta um agente hospedado, executa o otimizador do agente e implanta o candidato vencedor.
Pré-requisitos
| Tool | Obrigatório | Purpose |
|---|---|---|
| azd CLI | Sim | CLI do Azure para Desenvolvedores. Configura, implanta e gerencia seu agente. |
| CLI do Azure | Sim | autenticação Azure (az login) |
Sua assinatura do Azure deve estar na lista de permissões para o otimizador do agente. Entre em contato com seu representante Microsoft para solicitar acesso.
Instalar a extensão da CLI
Instale 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
Inicie um novo projeto a partir do exemplo do otimizador de agentes. Crie uma pasta e 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 sua assinatura do Azure, a região e as configurações de implantação do modelo. Ele baixa a amostra e gera agent.yaml, .agent_configs/baseline/, o conjunto de dados de avaliação e os arquivos de infraestrutura como código para provisionamento.
Dica
Se você já tiver um projeto de agente existente, ignore esta etapa e veja Tornar o otimizador do agente pronto para adicionar suporte à otimização.
Se você já tiver um projeto do Foundry e implantações de modelo, adicione -p <project-resource-id> para direcionar aos recursos existentes:
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 você tiver várias assinaturas, selecione a que deseja:
az account set --subscription "<subscription-name-or-id>"
Configurar e provisionar
Escolha uma das opções a seguir com base em se você precisa criar novos recursos de Azure ou já tem um projeto foundry existente.
Opção A: Criar novos recursos
Provisione os recursos de Azure. Esta etapa leva aproximadamente dois minutos:
azd provision
Esta etapa cria:
- Uma conta e um projeto da Foundry
- Um Registro de Contêiner do Azure
- Implantações de modelos (gpt-4.1-mini para avaliação, gpt-5.4 para otimização)
Opção B: usar um projeto de Foundry existente
Se você já tiver um projeto do Foundry com modelos implantados, use agent init para configurar seu ambiente:
azd ai agent init --project-id "/subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>"
Dica
Localize a ID do recurso do projeto no portal do Azure → seu projeto do Foundry → Properties → Resource ID.
Defina o nome da implantação do modelo:
azd env set AZURE_AI_MODEL_DEPLOYMENT_NAME "gpt-4.1-mini"
Implantar o agente
azd deploy
Esse comando cria a imagem de contêiner, envia-a por push para Registro de Contêiner do Azure e registra o agente hospedado. O processo leva aproximadamente 1,5 minutos. A saída inclui um link para o playground do portal que você pode usar para conversar com o agente.
Teste a implantação:
azd ai agent invoke "What is 2+2?"
Gerar avaliações e conjuntos de dados personalizados
Para otimização significativa com 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 adaptados ao domínio do seu agente.
Para obter detalhes, consulte Criar um conjunto de dados de avaliação.
Executar otimização
Em seguida, execute a otimização com a configuração gerada:
azd ai agent optimize
A CLI lê o name campo do arquivo agent.yaml para determinar qual agente implantado otimizar. Ele também detectará e usará automaticamente o arquivo gerado eval.yaml para executar a otimização. Se você tiver vários agentes ou configurações, ou quiser selecionar outro, use os --agentsinalizadores--config:
azd ai agent optimize --agent <your-agent-name> --config <your-config-file>.yaml
Para obter mais detalhes sobre a seleção de agentes, consulte Qual agente será otimizado.
O otimizador do agente executa as seguintes etapas:
- Avalia seu agente de linha de base em relação a um conjunto de dados interno que contém 3 tarefas e 12 critérios.
- Gera candidatos aprimorados (instruções, habilidades, ferramentas ou configurações de modelo, dependendo do seu destino).
- Avalia cada candidato.
- Classifica os candidatos por pontuação.
Esse processo pode demorar alguns minutos. Você vê o 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 a URL fornecida na CLI para exibir e monitorar seu trabalho no portal do Foundry.
O modelo de avaliação pontua cada resposta (qualquer modelo de conclusão de chat funciona). O modelo de otimização gera candidatos aprimorados e deve ser da lista com suporte (família gpt-5 ou DeepSeek).
Warning
Se o modelo de avaliação não for implantado, todas as pontuações serão zero sem nenhuma mensagem de erro. Verifique se o modelo de avaliação existe antes de executar a otimização.
Publicar o vencedor
Indica ★ o melhor candidato. O fluxo de trabalho recomendado é aplicar a configuração otimizada localmente e, em seguida, implantar:
# Apply the winning candidate locally
azd ai agent optimize apply --candidate <candidate-id>
# Deploy with the optimized config
azd deploy
Isso faz o download da configuração otimizada para .agent_configs/<candidate_id>/ no seu projeto. Na próxima implantação, seu agente passará a usar as instruções aprimoradas e as descrições das ferramentas.
Como alternativa, para testes rápidos, você pode implantar 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 na inicialização.
Invoque o agente novamente para verificar a melhoria:
azd ai agent invoke "What is your return policy?"
Você também pode executar a avaliação separadamente para confirmar a melhoria da pontuação:
azd ai agent eval run
Monitorar e gerenciar
Use o ID da tarefa, que é formatado como opt_<hex> e é exibido na saída da otimização, para acompanhar e gerenciar 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>
Limpar os recursos
Ao concluir a experimentação, exclua os recursos provisionados:
azd down --force --purge
Dica
Por quê --purge? As contas do Foundry usam exclusão temporária por padrão. Sem --purge, o nome do recurso permanece reservado por 48 horas e o reprovisionamento com o mesmo nome falha.
Solução de problemas
| Problema | Cause | Corrigir |
|---|---|---|
| Todas as pontuações são zero | Agente ou modelo de avaliação não implantado | Implantar o agente ou modelo de avaliação em seu projeto do Foundry ou usar --eval-model para especificar um modelo implantado |
azd provision falha devido a erro de cota |
A assinatura não possui capacidade suficiente | Experimente uma assinatura diferente ou solicite um aumento de cota |