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

O otimizador de agente oferece suporte a quatro objetivos de otimização: ajuste de instruções (reescreve o prompt de sistema do agente), melhoria de habilidades (refina capacidades reutilizáveis), otimização de ferramentas (melhora as descrições e os parâmetros das ferramentas) e seleção de modelo (avalia várias implantações de modelos). O otimizador determina automaticamente quais metas deve melhorar com base na configuração básica do seu agente.

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())

Qual agente será otimizado

O otimizador precisa saber qual agente hospedado implantado deve ser usado como alvo. Ele resolve o nome do agente usando a seguinte ordem de prioridade:

Na maioria dos casos, você não precisa especificar o nome do agente explicitamente. A CLI lê isso do arquivo agent.yaml do seu projeto. Use a flag --agent quando você tiver vários agentes no seu projeto ou quiser substituir o valor padrão:

azd ai agent optimize --agent my-support-agent

Otimizar instruções

O otimizador reescreve e refina o prompt do sistema do agente para melhorar o desempenho em seu conjunto de dados de avaliação. O ajuste por instruções é ativado automaticamente quando a configuração base inclui um arquivo instructions.md.

Como funciona

1. Avaliação de linha de base. Seu agente é executado com suas instruções atuais em relação a cada tarefa no conjunto de dados. O avaliador pontua cada resposta em relação aos critérios da tarefa.
2. Geração de instruções. O otimizador analisa as pontuações de referência e gera prompts de sistema alternativos desenvolvidos para melhorar os pontos fracos, mantendo os pontos fortes.
3. Avaliação do candidato. O otimizador injeta cada conjunto de instruções candidato no seu agente por meio da variável de ambiente OPTIMIZATION_CANDIDATE_ID e avalia cada um deles usando o mesmo conjunto de dados.
4. Ranking. O otimizador classifica os candidatos por pontuação composta e marca o melhor candidato com ★ .

Executar otimização de instruções

azd ai agent optimize

Com uma configuração personalizada:

# eval.yaml
agent:
  name: my-agent

dataset_file: ./eval.jsonl

evaluators:
  - builtin.task_adherence

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

azd ai agent optimize --config eval.yaml

O que é alterado

O otimizador reescreve o prompt do sistema. Seu código permanece o mesmo porque load_config() retorna as novas instruções automaticamente. 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

Exemplo: Antes e depois

Antes (suas instruções padrão):

You are a helpful assistant.

Depois (otimizado):

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

Iterações máximas

A max_iterations opção controla quantos conjuntos de instruções candidatos são gerados. Cada iteração produz um candidato.

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

Modelo de avaliação

O modelo de avaliação pontua respostas do agente em relação aos critérios. Qualquer modelo de conclusão de chat implantado em seu projeto do Foundry funciona.

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

Modelo de otimização (reflexão)

O modelo de otimização (também chamado de "modelo de reflexão") gera configurações candidatas – instruções aprimoradas, habilidades e descrições de ferramentas. Ele analisa os resultados da linha de base e produz variantes aprimoradas. Ele deve ser implantado no seu projeto Foundry.

Modelos com suporte: gpt-5, , gpt-5.1. gpt-5.3

Especifique o modelo de otimização no arquivo de configuração ou por meio da CLI:

options:
  optimization_model: gpt-5.1

Ou por meio do sinalizador da CLI:

azd ai agent optimize --optimize-model gpt-5.1

Para obter mais detalhes sobre como esses modelos são usados, consulte Modelos.

Otimizar habilidades

O otimizador melhora as habilidades existentes que seu agente usa. Ele refina descrições de habilidades, implementações e critérios de ativação. A otimização de habilidade é ativada automaticamente quando sua configuração de linha de base inclui um skills/ diretório.

Como funciona

1. Avaliação de linha de base. O mesmo que ajuste de instruções. O otimizador avalia seu agente em relação ao conjunto de dados.

2. Aprimoramento de habilidades. O otimizador analisa áreas fracas e refina definições de habilidade. Uma habilidade é uma funcionalidade nomeada com:

   • Nome: por exemplo, "step_by_step_reasoning"
   • Descrição: o que a habilidade faz e quando usá-la
   • Corpo: Detalhes ou procedimento da implementação

3. Injeção. O agente carrega habilidades aprimoradas por meio de load_config(), o que as torna disponíveis para o conjunto de instruções do seu agente.

   # load_config() returns skills from .agent_configs/baseline/skills/
   config = load_config()
   full_prompt = config.compose_instructions()
   # Returns: "You are a helpful assistant.\n\n## Available Skills\n- **step_by_step_reasoning**: ..."
   

4. Avaliação. O otimizador avalia o agente com habilidades aprimoradas em relação ao conjunto de dados.

Executar a otimização de competências

Verifique se a configuração de linha de base tem um skills/ diretório com pelo menos uma habilidade e execute:

azd ai agent optimize

Com um arquivo de configuração:

# eval.yaml
agent:
  name: my-agent

dataset_file: ./eval.jsonl

evaluators:
  - builtin.task_adherence

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

azd ai agent optimize --config eval.yaml

Downloads de arquivos de skill

Para candidatos que incluem arquivos de habilidades, o carregador de configuração pode baixar esses arquivos por meio da API do resolvedor. As habilidades usam o formato open Agent Skills e são armazenadas em um diretório local.

from azure.ai.agentserver.optimization import load_config, load_skills_from_dir
from pathlib import Path

config = load_config()

if config.skills:
    print(f"Skills loaded from optimization config:")
    for skill in config.skills:
        print(f"  - {skill.name}: {skill.description}")
elif config.skills_dir:
    # Load skills from local directory
    skills = load_skills_from_dir(Path(config.skills_dir))
    config.skills.extend(skills)
    for skill in skills:
        print(f"  - {skill.name}: {skill.description}")

Saiba mais sobre o formato habilidades do agente em agentskills.io.

Otimizar ferramentas

O otimizador melhora as descrições e os parâmetros das ferramentas no arquivo tools.json para ajudar o modelo a chamar as ferramentas com mais precisão. A otimização da ferramenta é ativada automaticamente quando a configuração de linha de base inclui um tools.json arquivo.

Como funciona

1. Avaliação de linha de base. O otimizador avalia seu agente em relação ao conjunto de dados, incluindo todas as chamadas de ferramenta que ele faz.
2. Análise de ferramentas. O otimizador identifica chamadas de ferramenta que falham ou produzem resultados abaixo do ideal e analisa a causa raiz — descrições não claras, parâmetros ausentes ou nomenclatura ambígua.
3. Refinamento da descrição. O otimizador gera definições de ferramenta aprimoradas com descrições mais claras, documentação de parâmetro melhor e nomes de função mais precisos.
4. Avaliação. O otimizador avalia o agente com definições de ferramenta aprimoradas em relação ao conjunto de dados.

Executar otimização da ferramenta

Verifique se a configuração de linha de base tem um tools.json arquivo e, em seguida, execute:

azd ai agent optimize

O que é alterado

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.

Otimizar seleção de modelo

O otimizador avalia seu agente em várias implantações de modelos para encontrar o melhor equilíbrio entre qualidade e custo. Cada modelo é executado no mesmo conjunto de dados, para que você possa comparar os resultados diretamente. A otimização de modelo é ativada quando você especifica candidatos a modelo em optimization_config.

Configurar candidatos a modelo

Especifique os modelos para avaliar em seu eval.yaml:

# eval.yaml
agent:
  name: my-agent

dataset_file: ./eval.jsonl

evaluators:
  - builtin.task_adherence

options:
  eval_model: gpt-4.1-mini
  optimization_model: gpt-5.1
  max_iterations: 5
  optimization_config:
    model:
      - gpt-4.1
      - gpt-4.1-mini
      - gpt-4o

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

Executar otimização de modelo

azd ai agent optimize --config eval.yaml

O otimizador avalia seu agente com cada implantação especificada do modelo e classifica os resultados com base na pontuação e no custo de tokens.

Combinar com outros destinos

Quando sua configuração de base inclui instruções, habilidades e modelos candidatos, o otimizador executa todos os alvos juntos em uma única execução:

# eval.yaml — all targets active
agent:
  name: my-agent

dataset_file: ./eval.jsonl

evaluators:
  - builtin.task_adherence
  - builtin.intent_resolution

options:
  eval_model: gpt-4.1-mini
  optimization_model: gpt-5.1
  max_iterations: 5
  optimization_config:
    model:
      - gpt-4.1
      - gpt-5

Isso produz candidatos que combinam instruções aprimoradas com diferentes opções de modelo, dando a você a visão completa do que funciona melhor.

Interpretar os resultados

Após a conclusão da otimização, examine a tabela de resultados. Para obter diretrizes detalhadas de pontuação, consulte Noções básicas sobre os resultados da otimização.

Limites principais:

Publicar 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

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, 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.

Solução de problemas

Conteúdo relacionado

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