Otimizar as instruções, competências, ferramentas e modelos do agente (pré-visualização)

O otimizador de agentes melhora quatro aspetos do seu agente hospedado: instruções, competências, ferramentas e seleção de modelos. Deteta automaticamente quais destes objetivos devem ser otimizados com base na configuração de base do seu agente.

Este artigo mostra como executar uma otimização, configurar e monitorizar a execução, e implementar os resultados. Para saber o que cada alvo faz e quando é ativado, veja Alvos de Otimização. Para configurar as entradas de base, consulte Torne o seu agente compatível com o otimizador. Para uma referência rápida sobre o que o otimizador altera, veja O que cada alvo altera.

Pré-requisitos

• Um projeto Foundry com um agente alojado implementado
• A azure.ai.agents extensão CLI instalada (ver Quickstart: Otimizar um agente alojado)
• Um modelo implementado para avaliação (por exemplo, gpt-4.1-mini) e um modelo de otimização a partir da lista suportada (por exemplo, gpt-5.1)
• O seu agente é compatível com o Otimizador (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 a sua linha de base, gera candidatos, avalia-os e classifica os resultados. Para o ciclo completo de avaliação e melhoria, veja Como funciona o otimizador de agentes. Os alvos executados dependem da sua configuração de base — a afinação de instruções, o aperfeiçoamento de competências e a otimização de ferramentas são ativados automaticamente quando os ficheiros de base correspondentes estão presentes. Ver Metas de Otimização.

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

azd ai agent optimize --config eval.yaml

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

Destinar um agente específico

A forma como a CLI resolve o agente depende de executares o comando a partir de um azd projeto:

O nome do agente implementado tem de corresponder a um agente hospedado no projeto Foundry de destino.

Otimizar um agente existente sem ficheiros de projeto AZD

Podes otimizar um agente hospedado existente sem correr azd ai agent init e sem criar azure.yaml um .azure diretório de ambiente. Neste fluxo autónomo, forneça explicitamente o endpoint do projeto Foundry e o nome do agente implementado.

1. Certifique-se de que o agente implementado está pronto para o otimizador. Num diretório de trabalho local, crie o ficheiro de instruções, o conjunto de dados, os avaliadores e eval.yaml, descritos em Configurar a execução da otimização.

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

   Para este fluxo independente, omita agent.config. A CLI pede a instrução base quando executas 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 a partir da página de Visão Geral do projeto Foundry. Use o URL do endpoint do projeto, não o ID de recurso do Azure.

4. Guarde o endpoint na sua configuração ao nível azd de utilizador para que comandos subsequentes possam resolver o mesmo projeto a partir de qualquer diretório:

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

   Esta etapa escreve o endpoint padrão em ~/.azd/config.json. Para a ordem completa de resolução e os comandos para inspecionar ou limpar o contexto guardado, veja Definir o contexto do projeto Foundry para os comandos azd.

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

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

   Quando lhe for pedida a instrução para o agente, introduza-a diretamente ou selecione um ficheiro, como .agent_configs/baseline/instructions.md.

   Note

   Na pré-visualização atual, uma execução autónoma não expande agent.config de eval.yaml. Executa o comando de forma interativa para poderes fornecer a instrução base. Não uses --no-prompt para este fluxo. Também é necessário um projeto azd para carregar configurações de base de capacidades e ferramentas baseadas em ficheiros.

   Para um comando pontual que não altere a sua configuração de utilizador, passe --project-endpoint:

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

   Também pode definir o endpoint para o shell atual:

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

6. Guarde o ID da operação na saída do comando. Como este fluxo não tem um ambiente azd, a CLI não guarda localmente o identificador da última operação. Passe o ID da operação nos comandos seguintes:

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

   Estes comandos utilizam o endpoint guardado por azd ai project set. Se usaste o formulário único --project-endpoint , passa novamente a bandeira a cada comando de seguimento.

Configurar a execução da otimização

Configure as execuções de otimização através de um ficheiro eval.yaml que reúne o seu conjunto de dados, os avaliadores e as opções de execução. O comando azd ai agent eval generate escreve este ficheiro por si, ou pode criá-lo manualmente. O otimizador deteta eval.yaml automaticamente na raiz do seu projeto, ou 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; ver Criar um conjunto de dados de avaliação e avaliadores. As secções seguintes descrevem as opções de execução.

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

O otimizador utiliza dois modelos: um modelo de avaliação que avalia as respostas dos agentes com critérios e um modelo de otimização que gera configurações candidatas. Defina-os em eval.yaml ou use opções da 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 implementado no seu projeto funciona como modelo de avaliação. O modelo de otimização deve ser da lista suportada. Para funções e modelos suportados, veja Modelos.

Defina 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 paragem.

Valores mais altos exploram mais variações, mas demoram mais tempo. O otimizador aprende com candidatos anteriores, por isso os candidatos posteriores tendem a obter pontuações mais altas.

Avaliar múltiplos modelos

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

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

Cada modelo listado abaixo model_search_space deve ser implementado no seu projeto Foundry.

A seleção de modelos decorre em paralelo com os objetivos que são ativados automaticamente com base na sua configuração de referência. Uma única execução pode gerar candidatos que combinam instruções melhoradas, capacidades e descrições de ferramentas com diferentes opções de modelo; não é necessário configurar essa combinação manualmente.

Monitorizar um trabalho em execução

Uma execução de otimização é assíncrona. Use estes comandos quando um trabalho estiver a durar muito tempo ou quiser verificar o 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>

Recolha o ID da operação, o URL do portal, as pontuações e os IDs dos candidatos no resultado da execução. Também pode monitorizar o trabalho no portal Foundry usando o URL mostrado quando a execução começa.

Se iniciaste o trabalho sem ficheiros de projeto AZD, passa sempre o ID da operação para status e cancel. Os comandos utilizam o endpoint ao nível do utilizador guardado por azd ai project set; caso contrário, inclui --project-endpoint.

Interpretar os resultados

Depois de concluída a otimização, reveja a tabela de resultados. Um asterisco (*) indica o melhor candidato. Para as colunas da tabela de resultados, detalhes de pontuação, limiares de melhoria de pontuação e a vista do portal, consulte Compreender resultados de otimização.

Implementar a versão vencedora

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.

Em alternativa, podes implementar diretamente através da API (útil para testes rápidos de A/B):

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

Se todos os candidatos tiverem uma pontuação inferior à linha base, não coloquem nenhum candidato. A configuração base mantém-se ativa.

O que cada alvo altera

O otimizador ativa automaticamente os alvos que se aplicam à sua linha base. Esta secção serve de referência para as alterações introduzidas por uma execução. Use a tabela seguinte para antecipar o que a otimização faz para o seu agente:

O teu código mantém-se igual em todos os alvos porque load_config() devolve automaticamente os valores otimizados. Apenas a configuração que o modelo vê muda.

Instruções

O otimizador reescreve o prompt do sistema. Melhorias comuns incluem:

• Adicionar restrições explícitas que o prompt original sugeria mas não indicava
• Instruções de reestruturação para maior clareza
• Adicionar especificações de formatos de saída
• Reforço dos limites de segurança e âmbito

Por exemplo, um prompt base mínimo como You are a helpful assistant. pode tornar-se no seguinte:

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

Competências

O otimizador refina a descrição, o corpo e os critérios de ativação de cada habilidade, mantendo intacto o propósito da habilidade. O agente carrega competências melhoradas através de load_config(), que as acrescenta ao conjunto de instruções. As competências utilizam o formato aberto de Competências de Agente . Para saber como o seu agente carrega competências, veja Prepare o seu agente para o otimizador.

Tools

O otimizador refina as tuas tools.json definições. Melhorias comuns incluem:

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

O código de implementação da ferramenta mantém-se o mesmo. Apenas as definições que o modelo vê mudam.

Models

O otimizador classifica cada modelo candidato por pontuação composta e custo do token, para que possa escolher a melhor troca qualidade-custo. Para configurar os candidatos, consulte Avaliar múltiplos modelos.

Troubleshooting

Conteúdo relacionado

• Visão geral do otimizador de agentes
• Prepare o seu otimizador de agentes
• Criar um conjunto de dados de avaliação e avaliadores
• Quickstart: Otimizar um agente hospedado