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

O otimizador de agentes suporta quatro objetivos de otimização: ajuste de instruções (reescreve o prompt do sistema do seu agente), melhoria de competências (refina capacidades reutilizáveis), otimização de ferramentas (melhora descrições e parâmetros de ferramentas) e seleção de modelos (avalia em múltiplas implementações de modelos). O otimizador determina automaticamente quais os alvos a melhorar com base na configuração base do seu agente.

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

Qual agente é otimizado

O otimizador precisa de saber qual o agente alojado implementado a utilizar como destino. Resolve o nome do agente usando a seguinte ordem de prioridade:

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

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

Otimizar instruções

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

Como funciona

1. Avaliação inicial. O seu agente executa as instruções atuais em todas as tarefas do conjunto de dados. O avaliador avalia cada resposta com base nos critérios da tarefa.
2. Geração de instruções. O otimizador analisa as pontuações de base e gera prompts de sistema alternativos concebidos para melhorar as áreas mais fracas, mantendo as áreas fortes.
3. Avaliação do candidato. O otimizador injeta cada conjunto candidato de instruções no seu agente através da variável de ambiente OPTIMIZATION_CANDIDATE_ID e avalia-o com base no mesmo conjunto de dados.
4. Classificação. O otimizador classifica os candidatos por pontuação composta e marca o melhor candidato com ★ .

Otimização de instruções de execução

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 muda

O otimizador reescreve o prompt do sistema. O teu código mantém-se igual porque load_config() devolve automaticamente as novas instruções. 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

Exemplo: Antes e depois

Antes (as tuas 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 tempo. O otimizador aprende com as iterações anteriores, pelo que os candidatos posteriores tendem a obter pontuações mais altas.

Modelo de avaliação

O modelo de avaliação avalia as respostas dos agentes com base nos critérios. Qualquer modelo de conclusão de chat implementado no seu projeto 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 melhoradas, competências e descrições de ferramentas. Analisa resultados de base e produz variantes melhoradas. Tem de ser implementado no seu projeto Foundry.

Modelos suportados: gpt-5, gpt-5.1, gpt-5.3.

Especifique o modelo de otimização no seu ficheiro de configuração ou via CLI:

options:
  optimization_model: gpt-5.1

Ou através do flag CLI:

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

Para mais detalhes sobre como estes modelos são utilizados, consulte Modelos.

Otimizar competências

O otimizador melhora as competências existentes que o seu agente utiliza. Refina descrições de competências, implementações e critérios de ativação. A otimização de capacidades ativa-se automaticamente quando a sua configuração de base inclui um diretório skills/.

Como funciona

1. Avaliação inicial. O mesmo acontece com a afinação de instruções. O otimizador avalia o seu agente em relação ao conjunto de dados.

2. Melhoria de competências. O otimizador analisa áreas fracas e refina as definições de competências. Uma competência é uma capacidade designada com:

   • Nome: Por exemplo, "step_by_step_reasoning"
   • Descrição: O que a habilidade faz e quando a usar
   • Corpo: Detalhes ou procedimento de implementação

3. Injeção. O agente carrega competências melhoradas através 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 competências melhoradas em relação ao conjunto de dados.

Otimização de habilidades de corrida

Garante que a tua configuração base tem um skills/ diretório com pelo menos uma habilidade, depois executa:

azd ai agent optimize

Com um ficheiro 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

Transferências de ficheiros de skill

Para candidatos que incluem ficheiros de competências, o config loader pode descarregá-los através da API do resolvedor. As competências utilizam o formato aberto de Competências de Agente e são armazenadas num 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 Agent Skills em agentskills.io.

Ferramentas de otimização

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

Como funciona

1. Avaliação inicial. O otimizador avalia o seu agente com base no conjunto de dados, incluindo quaisquer chamadas a ferramentas que este faça.
2. Análise de ferramentas. O otimizador identifica chamadas de ferramentas que falham ou produzem resultados subótimos e analisa a causa raiz — descrições pouco claras, parâmetros em falta ou nomeação ambígua.
3. Refinamento da descrição. O otimizador gera definições melhoradas de ferramentas com descrições mais claras, melhor documentação dos parâmetros e nomes de funções mais precisos.
4. Avaliação. O otimizador avalia o agente com definições melhoradas de ferramentas em relação ao conjunto de dados.

Otimização de ferramentas de execução

Garante que a tua configuração base tem um tools.json ficheiro e depois executa:

azd ai agent optimize

O que muda

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.

Otimizar a seleção do modelo

O otimizador avalia o seu agente em múltiplas implementações de modelos para encontrar a melhor relação qualidade-custo. Cada modelo corre contra o mesmo conjunto de dados, por isso pode comparar os resultados diretamente. A otimização de modelos ativa-se quando se especificam candidatos a modelos em optimization_config.

Configurar modelos candidatos

Especifique os modelos a avaliar no 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 abaixo optimization_config.model deve ser implementado no seu projeto Foundry.

Executar a otimização do modelo

azd ai agent optimize --config eval.yaml

O otimizador avalia o seu agente com cada implementação de modelo especificado e classifica os resultados por pontuação e custo do token.

Combinar com outros alvos

Quando a sua linha de base inclui instruções, competências e candidatos a modelo, o otimizador executa todos os alvos juntos numa ú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

Isto produz candidatos que combinam instruções melhoradas com diferentes opções de modelos, dando-lhe uma visão completa do que funciona melhor.

Interpretar os resultados

Depois de concluída a otimização, reveja a tabela de resultados. Para orientações detalhadas de pontuação, consulte Compreender resultados de otimização.

Limiares-chave:

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.

Troubleshooting

Conteúdo relacionado

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