Otimizar instruções, habilidades, ferramentas e modelos do agente (versão prévia)

O otimizador do agente melhora quatro aspectos do agente hospedado: instruções, habilidades, ferramentas e seleção de modelo. Detecta automaticamente quais desses alvos devem ser otimizados com base na configuração base do seu agente.

Este artigo mostra como executar uma otimização, configurar e monitorar a execução e implantar os resultados. Para o que cada destino faz e quando ele é ativado, consulte destinos de otimização. Para configurar as entradas de referência, consulte Preparar seu agente para o otimizador. Para obter uma referência rápida sobre as alterações feitas pelo otimizador, consulte As alterações de cada destino.

Pré-requisitos

• Um projeto da Foundry com um agente hospedado implantado
• A azure.ai.agents extensão da CLI instalada (consulte Início Rápido: Otimizar um agente hospedado)
• Um modelo implantado para avaliação (por exemplo) gpt-4.1-minie um modelo de otimização da lista com suporte (por exemplo, gpt-5.1)
• Seu agente está preparado para otimização (chamadas load_config())

Executar uma otimização

Inicie uma execução de otimização com um único comando:

azd ai agent optimize

O otimizador avalia sua linha de base, gera candidatos, os avalia e classifica os resultados. Para o ciclo completo de avaliação e melhoria, consulte Como o otimizador do agente funciona. A execução dos alvos depende da sua configuração de linha de base — ajuste de instruções, aprimoramento de habilidades e otimização de ferramentas são ativados automaticamente quando os arquivos de linha de base correspondentes estão presentes. Consulte as metas de otimização.

Para controlar a execução com um arquivo de configuração, passe um eval.yaml que faça referência ao conjunto de dados, aos avaliadores e às opções:

azd ai agent optimize --config eval.yaml

Para obter o esquema completo eval.yaml , consulte Configurar a execução de otimização.

Direcionar um agente específico

Como a CLI determina o agente depende de se você executa o comando a partir de um projeto azd:

O nome do agente implantado deve coincidir com o de um agente hospedado no projeto Foundry de destino.

Otimizar um agente existente sem arquivos de projeto do AZD

Você pode otimizar um agente hospedado existente sem executar azd ai agent init e sem criar azure.yaml ou um .azure diretório de ambiente. Neste fluxo independente, forneça explicitamente o endpoint do projeto Foundry e o nome do agente implantado.

1. Verifique se o agente implantado está pronto para o otimizador. Em um diretório de trabalho local, crie o arquivo de instrução, o conjunto de dados, os avaliadores e eval.yaml descrito em Configurar a execução de otimização.

   Execute o comando deste diretório de trabalho. Sem um projeto azd, os caminhos relativos em eval.yaml são resolvidos direto do diretório de trabalho atual.

   Para esse fluxo autônomo, omita agent.config. A CLI solicita a instrução de linha de base quando você executa o comando:

   # eval.yaml
   agent:
     name: my-support-agent
     kind: hosted
     model: gpt-4.1-mini
   dataset:
     local_uri: ./eval.jsonl
   evaluators:
     - builtin.task_adherence
   options:
     eval_model: gpt-4.1-mini
     optimization_model: gpt-5.1
     max_candidates: 2
   

2. Autenticar:

   az login
   azd auth login
   

3. Copie o endpoint do projeto na página Overview do projeto Foundry. Use a URL do ponto de extremidade do projeto, não a ID do recurso Azure.

4. Salve o ponto de extremidade na configuração de usuário de nível azd para que os comandos subsequentes possam resolver o mesmo projeto direto de qualquer diretório:

   azd ai project set "<project-endpoint>"
   azd ai project show
   

   Esta etapa grava o ponto de extremidade padrão em ~/.azd/config.json. Para obter a ordem completa de resolução e os comandos para inspecionar ou limpar o contexto armazenado, consulte Definir o contexto do projeto Foundry para os comandos do azd.

5. Execute a otimização com o nome do agente implantado:

   azd ai agent optimize --agent "<deployed-agent-name>" --config eval.yaml
   

   Quando for solicitada a instrução do agente, forneça-a diretamente ou selecione um arquivo como .agent_configs/baseline/instructions.md.

   Note

   Na visualização atual, uma execução autônoma não expande agent.config a partir de eval.yaml. Execute o comando interativamente para que você possa fornecer a instrução de linha de base. Não use --no-prompt para esse fluxo. O carregamento habilidade baseada em arquivo e linhas de base de ferramenta também exige um projeto azd.

   Para um comando único que não deve alterar a configuração no nível do usuário, passe --project-endpoint:

   azd ai agent optimize \
     --project-endpoint "<project-endpoint>" \
     --agent "<deployed-agent-name>" \
     --config eval.yaml
   

   Você também pode definir o ponto de extremidade para o shell atual:

   export FOUNDRY_PROJECT_ENDPOINT="<project-endpoint>"
   azd ai agent optimize --agent "<deployed-agent-name>" --config eval.yaml
   

6. Salve a ID da operação na saída do comando. Como esse fluxo não tem ambiente azd, a CLI não persiste o último ID da operação localmente. Passe a ID da operação para os comandos de acompanhamento:

   azd ai agent optimize status <operation-id> --watch
   
   azd ai agent optimize list
   
   azd ai agent optimize cancel <operation-id>
   

   Esses comandos usam o ponto de extremidade salvo por azd ai project set. Se você usou a forma única --project-endpoint, passe um sinalizador novamente para cada comando subsequente.

Configurar a execução de otimização

Configure as execuções de otimização por meio de um eval.yaml arquivo que vincule seu conjunto de dados, avaliadores e opções de execução. O comando azd ai agent eval generate grava esse arquivo para você ou você pode criá-lo manualmente. O otimizador detecta eval.yaml automaticamente na raiz do projeto ou você pode passá-lo explicitamente com --config eval.yaml.

# eval.yaml
name: my-optimization              # Optional label for the run
agent:
  name: my-agent                   # Deployed hosted agent name
  kind: hosted
  version: "1"                     # Agent version (optional)
  model: gpt-4.1-mini              # Baseline model deployment
  config: .agent_configs/baseline/metadata.yaml
dataset:
  local_uri: ./eval.jsonl          # A local JSONL file...
  # name: my-foundry-dataset       # ...OR a registered Foundry dataset
  # version: "1"
# validation_dataset:              # Optional held-out dataset
#   name: my-validation-dataset
#   version: "1"
evaluators:
  - builtin.task_adherence         # A built-in evaluator...
  # - name: my-custom-evaluator    # ...or a custom evaluator
  #   version: "1"
  #   local_uri: ./my_evaluator.json
options:
  eval_model: gpt-4.1-mini         # Scores responses
  optimization_model: gpt-5.1      # Generates candidates
  max_candidates: 4
  optimization_config:
    model_search_space:            # Optional: compare model deployments
      - gpt-4.1

Criar o conjunto de dados e os avaliadores separadamente; consulte Criar um conjunto de dados de avaliação e avaliadores. As seções a seguir descrevem as opções de execução.

Escolha os modelos de avaliação e otimização

O otimizador usa dois modelos: um modelo de avaliação que pontua respostas do agente em relação a critérios e um modelo de otimização que gera configurações candidatas. Defina-os em eval.yaml ou use sinalizadores de CLI.

options:
  eval_model: gpt-4.1-mini
  optimization_model: gpt-5.1

azd ai agent optimize --eval-model gpt-4.1-mini --optimize-model gpt-5.1

Qualquer modelo de conclusão de chat implantado no seu projeto serve como modelo de avaliação. O modelo de otimização deve ser da lista com suporte. Para funções e modelos com suporte, consulte Modelos.

Definir o número de candidatos

A max_candidates opção define o número esperado de configurações candidatas para a execução. O otimizador normalmente retorna depois de atingir essa contagem, a menos que a execução pare mais cedo devido a um erro ou outra condição de parada.

Valores mais altos exploram mais variações, mas demoram mais. O otimizador aprende com os candidatos anteriores, de modo que os candidatos posteriores tendem a pontuar mais alto.

Avaliar vários modelos

Para comparar implantações de modelo em uma única execução, liste-as em optimization_config.model_search_space. O otimizador avalia seu agente com cada modelo em relação ao mesmo conjunto de dados e classifica os resultados por pontuação e custo de token.

# eval.yaml
options:
  optimization_config:
    model_search_space:
      - gpt-4.1
      - gpt-4.1-mini
      - gpt-4o

Cada modelo listado em model_search_space deve ser implantado em seu projeto do Foundry.

A seleção de modelo ocorre junto com os alvos que são ativados automaticamente a partir da sua linha de base. Uma única execução pode produzir candidatos que combinam instruções, habilidades e descrições de ferramentas aprimoradas com diferentes opções de modelo – você não configura a combinação por conta própria.

Monitorar um trabalho em execução

Uma execução de otimização é assíncrona. Use estes comandos quando um trabalho estiver em execução longa ou você quiser verificar seu progresso:

# Check status and stream progress
azd ai agent optimize status <operation-id> --watch

# List recent optimization jobs
azd ai agent optimize list

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

Capture a ID da operação, a URL do portal, as pontuações e as IDs do candidato na saída da execução. Você também pode monitorar o trabalho no portal do Foundry usando a URL mostrada quando a execução é iniciada.

Se você iniciou o trabalho sem arquivos de projeto do AZD, sempre passe a ID da operação para status e cancel. Os comandos usam o ponto de extremidade de usuário salvo por azd ai project set; caso contrário, inclua --project-endpoint.

Interpretar os resultados

Após a conclusão da otimização, examine a tabela de resultados. Um asterisco (*) marca o melhor candidato. Para obter as colunas da tabela de resultados, detalhes de pontuação, limites de melhoria de pontuação e a exibição do portal, consulte Entender os resultados da otimização.

Implante o vencedor

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

Então, será feito 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, você pode implantar diretamente por meio da API (útil para testes rápidos de A/B):

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

Se todos os candidatos pontuarem abaixo da linha de base, não implante nenhum candidato. A configuração de linha de base permanece ativa.

O que cada alvo altera

O otimizador ativa automaticamente as metas que se aplicam à sua configuração de base. Esta seção serve como referência para as alterações feitas por uma execução. Use a tabela a seguir para prever o que a otimização faz para seu agente:

Seu código permanece o mesmo em todos os destinos porque load_config() retorna os valores otimizados automaticamente. Apenas a configuração que o modelo vê é alterada.

Instruções

O otimizador reescreve o prompt do sistema. As melhorias comuns incluem:

• Adicionando restrições explícitas que o prompt original implicava, mas não informava
• Instruções de reestruturação para maior clareza
• Adicionando especificações de formato de saída
• Fortalecendo os limites de escopo e segurança

Por exemplo, um prompt base mínimo como You are a helpful assistant. pode ficar assim:

You are a helpful coding assistant. Follow these guidelines:
1. Always include working code examples
2. Explain your reasoning step by step
3. If a question is outside your expertise, say so clearly
4. Use markdown formatting for code blocks
5. Handle edge cases in code examples

Habilidades

O otimizador refina a descrição, o corpo e os critérios de ativação de cada habilidade, mantendo a finalidade da habilidade intacta. O agente carrega habilidades aprimoradas por meio de load_config(), que as adiciona ao conjunto de instruções. As habilidades usam o formato de Habilidades do Agente aberto. Para saber mais sobre como seu agente carrega habilidades, consulte Prepare seu agente para o otimizador.

Tools

O otimizador refina suas tools.json definições. As melhorias comuns incluem:

• Descrições de função mais claras que ajudam o modelo a saber quando chamar uma ferramenta
• Descrições de parâmetro mais específicas que reduzem argumentos imprecisos
• Restrições adicionadas (enumerações, campos necessários) que impedem entradas inválidas

O código de implementação da ferramenta permanece o mesmo. Somente as definições que o modelo vê mudam.

Models

O otimizador classifica cada modelo candidato por pontuação composta e custo de token, para que você possa escolher a melhor troca de qualidade a custo. Para configurar os candidatos, consulte Avaliar vários modelos.

Solução de problemas

Conteúdo relacionado

• Visão geral do otimizador de agentes
• Deixe seu agente pronto para otimização
• Criar um conjunto de dados de avaliação e avaliadores
• Início Rápido: Otimizar um agente hospedado