Início rápido: Otimizar um agente alojado (pré-visualização)

• azd CLI (Azure Developer CLI).

• CLI do Azure para autenticação.

• A extensão microsoft.foundry para o azd (versão 0.1.40-preview ou posterior da dependência azure.ai.agents):

  azd ext install microsoft.foundry
  

  Se já estiver instalado, atualize:

  azd ext upgrade microsoft.foundry
  

• CLI do Azure para autenticação.

• Python 3.10 ou posterior.

• Os pacotes Python usados neste caminho:

  pip install "azure-ai-projects>=2.4.0" azure-ai-agentserver-optimization azure-identity python-dotenv
  

• Um projeto Foundry existente que já contém o agente alojado, o conjunto de dados registado e o avaliador que pretende usar para otimização.

• Visual Studio Code.

• Microsoft Foundry Toolkit do Visual Studio Code versão 1.6.4 ou posterior, com sessão iniciada no Azure. O Foundry Toolkit instala e atualiza o Microsoft Foundry Skill utilizado por este fluxo de trabalho.

• GitHub Copilot no Visual Studio Code com acesso ao modo agente. O Foundry Toolkit envia o pedido do Agent Optimizer para o GitHub Copilot depois de selecionares o espaço de trabalho do agente.

• CLI do Azure e Azure Developer CLI (AZD) instalados e autenticados:

  az login
  azd auth login
  

• Um anfitrião de agente de programação com a Microsoft Foundry Skill instalada.

• CLI do Azure e Azure Developer CLI (AZD) instalados e autenticados:

  az login
  azd auth login
  

• A extensão microsoft.foundry do AZD. Instale-o antes de iniciar o fluxo de trabalho:

  azd ext install microsoft.foundry
  

  Se já estiver instalado, atualiza-o:

  azd ext upgrade microsoft.foundry
  

Passo 1: Criar o projeto

Inicialize um novo projeto a partir do modelo de otimização:

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/azure.yaml .

Este modelo predefinido importa o exemplo de suporte ao cliente para otimização, um agente alojado em Python preparado para otimização que utiliza a abordagem bring-your-own e o protocolo Responses. Representa um agente de suporte de eletrónica de consumo que trata de pedidos de encomenda, devoluções, reclamações de garantia, resolução de problemas, reclamações, recomendações e escalonamento. A instrução de base deliberadamente mínima torna fácil comparar as melhorias da otimização da instrução e da descoberta de competências.

O exemplo utiliza load_config() para carregar a configuração de referência ou a configuração candidata e inclui .agent_configs/baseline/, eval.yaml, conjuntos de dados de avaliação completos e rápidos, a configuração do contentor e o manifesto de implementação do Foundry. O fluxo interativo importa estes ficheiros e solicita a sua subscrição do Azure, a região e as configurações de implementação do modelo.

Passo 2: Provisionar e implementar

Autenticar e provisionar os recursos do Azure:

az login
azd auth login
azd provision

O provisionamento demora aproximadamente dois minutos e cria uma conta Foundry, projeto, Azure Container Registry e implementações de modelos.

Instalar o agente:

azd deploy

Teste a implementação:

azd ai agent invoke "What is 2+2?"

Passo 3: Gerar o conjunto de avaliação e otimizar

Gere um conjunto de dados de avaliação e avaliadores para o seu agente:

azd ai agent eval generate

Esta etapa cria eval.yaml, um conjunto de dados de teste e avaliadores de pontuação com base nas instruções do seu agente. O otimizador utiliza estes ficheiros para medir a melhoria.

Execute o otimizador:

azd ai agent optimize --max-candidates 2

A CLI pede para selecionar um modelo de otimização. Para saltar o prompt, passa-o diretamente:

azd ai agent optimize --max-candidates 2 --optimize-model gpt-5

A CLI deteta o seu agente a partir de azure.yaml e utiliza automaticamente o eval.yaml gerado. Com dois candidatos, a otimização normalmente termina em cerca de 8 minutos. É mostrado o progresso em tempo real:

Optimizing agent "customer-support-py"...
  Config: eval.yaml
  Baseline saved to .agent_configs/baseline/metadata.yaml
  Job ID: opt_162bd0f09....
  Status: pending
  Portal: <OPTIMIZATION-JOB-URL>

Use o URL do portal para monitorizar o seu trabalho no portal da Foundry.

O modelo de avaliação pontua cada resposta (qualquer modelo de conclusão de chat funciona). O modelo de otimização (--optimize-model) gera candidatos melhorados e deve ser da lista suportada (família gpt-5 ou DeepSeek). Também podes colocar optimization_model por baixo options: para eval.yaml evitar ultrapassar a bandeira cada vez.

Passo 4: Lançar o vencedor

A estrela (*) nos resultados indica o melhor candidato. Aplicar a configuração otimizada localmente e depois implementar:

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

O comando apply transfere a configuração otimizada para .agent_configs/<candidate_id>/ e atualiza o azure.yaml para usar as novas instruções. O comando deploy coloca o agente otimizado em produção utilizando o CodeDeploy.

Chame o seu agente para verificar a melhoria:

azd ai agent invoke "What is your return policy?"

Também pode fazer uma avaliação para confirmar a melhoria da pontuação:

azd ai agent eval run

Caminho do SDK Python

Use os seguintes passos se quiser executar o otimizador a partir de Python em vez do fluxo de trabalho CLI do Azure Developer descrito anteriormente.

Este caminho assume que já tem os seguintes recursos num projeto Foundry existente:

• Um agente hospedado para otimizar.
• Um conjunto de dados de treino registado.
• Um avaliador registado.

Ao contrário do fluxo CLI do Azure Developer descrito anteriormente, o caminho do SDK Python não estrutura um projeto nem gera eval.yaml, um conjunto de dados ou avaliadores para si. Se quiseres que a amostra crie esses assets automaticamente, usa azd ai agent eval generate primeiro.

1. Criar um .env ficheiro

Crie uma pasta funcional e depois adicione um .env ficheiro com estes valores:

FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
FOUNDRY_AGENT_NAME=<your-hosted-agent-name>
DATASET_NAME=<your-registered-dataset-name>
EVALUATOR_NAME=<your-registered-evaluator-name>
DATASET_VERSION=1
POLL_INTERVAL_SECONDS=10
EVAL_MODEL=<your-eval-model-deployment-name>
OPTIMIZATION_MODEL=<your-optimization-model-deployment-name>

Executa o script a partir dessa mesma pasta de trabalho para load_dotenv() poderes carregar o .env ficheiro automaticamente. Se preferires executá-lo a partir de outro diretório, define primeiro os mesmos valores no teu ambiente shell.

Use o endpoint exato do projeto na página de Visão Geral do seu projeto Foundry. O script Python envia imediatamente o seu primeiro pedido. Se FOUNDRY_PROJECT_ENDPOINT for apenas um marcador de posição ou apontar para o projeto errado, a execução falha com ResourceNotFound: The project does not exist.

Defina EVAL_MODEL e OPTIMIZATION_MODEL como nomes de implementação que já existem no seu projeto Foundry, e não apenas como nomes de famílias de modelos. Por exemplo, se a implementação do seu projeto tiver um nome gpt-4.1-mini ou DeepSeek-V3.2, use exatamente esse nome de implementação em .env.

2. Executar o trabalho de otimização

Crie um ficheiro nomeado optimize_hosted_agent.py na mesma pasta que .env:

import os
import time

from azure.ai.agentserver.optimization import load_config
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
  OptimizationAgentIdentifier,
  OptimizationEvaluatorRef,
  OptimizationJob,
  OptimizationJobInputs,
  OptimizationOptions,
  OptimizationReferenceDatasetInput,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
agent_name = os.environ["FOUNDRY_AGENT_NAME"]
dataset_name = os.environ["DATASET_NAME"]
evaluator_name = os.environ["EVALUATOR_NAME"]
dataset_version = os.environ.get("DATASET_VERSION", "1")
eval_model = os.environ.get("EVAL_MODEL", "gpt-4o")
optimization_model = os.environ.get("OPTIMIZATION_MODEL", "gpt-5")
poll_interval_seconds = int(os.environ.get("POLL_INTERVAL_SECONDS", "10"))

optimization_config = load_config() # Reads agent optimization config from .agent_configs/baseline/metadata.yaml

with (
  DefaultAzureCredential() as credential,
  AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
  job = OptimizationJob(
    inputs=OptimizationJobInputs(
      agent=OptimizationAgentIdentifier(agent_name=agent_name),
      train_dataset=OptimizationReferenceDatasetInput(
        name=dataset_name,
        version=dataset_version,
      ),
      evaluators=[OptimizationEvaluatorRef(name=evaluator_name)],
      options=OptimizationOptions(
        max_candidates=2,
        eval_model=eval_model,
        optimization_model=optimization_model,
        optimization_config={
          "system_prompt": optimization_config.instructions,
          **({"tools": optimization_config.tool_definitions} if optimization_config.tool_definitions else {}),
          **({"skills": optimization_config.skills} if optimization_config.has_skills else {}),
        }
      ),
    )
  )
  poller = project_client.beta.agents.begin_create_optimization_job(job=job)

  print(f"Optimization job started, waiting for completion...")
  while not poller.done():
    print(f"\tstatus=`{poller.status()}`")
    time.sleep(poll_interval_seconds)

  result = poller.result()

  if result:
    print(f"Baseline candidate: {result.baseline}")
    print(f"Best candidate: {result.best}")

    for candidate in result.candidates or []:
      print(
        f"{candidate.name}: candidate_id={candidate.candidate_id}, "
        f"avg_score={candidate.avg_score:.4f}, "
        f"avg_tokens={candidate.avg_tokens:.0f}"
      )

Executar o script:

python optimize_hosted_agent.py

Quando a tarefa é concluída com êxito, o script imprime o candidato vencedor e o respetivo candidate_id.

Ao contrário de azd ai agent optimize, o fluxo do SDK em Python não cria um ficheiro local.agent_configs/baseline/metadata.yaml. Os metadados do trabalho de otimização permanecem no objeto devolvido job e na resposta do serviço Foundry, incluindo o candidato base, o melhor candidato e a lista de candidatos pontuados.

3. Candidatar o candidato vencedor

Se também estiver a trabalhar a partir do projeto local azd usado no fluxo da CLI acima, aplique o candidato vencedor utilizando o candidate_id devolvido pelo script Python:

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

Se só precisares de inspecionar o resultado, usa as pontuações dos candidatos e os identificadores de avaliação impressos pelo script para rever a configuração vencedora no Foundry antes de a promover.

Executar a otimização no VS Code

O Foundry Toolkit inclui uma experiência nativa de Otimização de Agentes para agentes alojados implementados. A partir do playground do agente, pode iniciar uma execução de otimização, comparar candidatos com a linha de base, inspecionar alterações de configuração e implementar o melhor candidato.

Passo 1: Selecione um agente hospedado implementado

1. Selecione Foundry Toolkit na barra de atividades.
2. Na secção Meus Recursos, selecione Agentes.
3. Se tiveres um agente alojado implementado, seleciona-o para abrir o ambiente de teste do agente alojado.
4. Se não tiver um agente alojado implementado, complete o caminho do VS Code no Quickstart: Implemente o seu primeiro agente alojado. Depois de terminar a implementação, volte aos Agentes e selecione o novo agente alojado.

Passo 2: Iniciar uma corrida de otimização

1. Selecione o separador Otimizar , que está marcado como Pré-visualização.

1. Selecione Nova Otimização.

2. No Select Workspace, escolha o workspace que contém o código do agente alojado selecionado:

   • Selecione Espaço de trabalho atual se o espaço de trabalho atual contiver o código do agente e o seu azure.yaml ficheiro.
   • Seleciona Navegar... para abrir o espaço de trabalho que contém o código do agente.

   O Foundry Toolkit utiliza os ficheiros do espaço de trabalho para preparar a otimização e aplicar um candidato ao serviço correspondente azure.ai.agent.

1. O Foundry Toolkit abre o GitHub Copilot Chat e envia um pedido Agent Optimizer preenchido com o tipo, nome e endpoint do projeto Foundry do agente selecionado.

2. Responda às quatro perguntas de otimização no Copilot Chat:

   Entrada	O que fornecer
   Métricas de avaliação	Introduza as métricas ou avaliadores a utilizar. Se não os tiveres, escolhe se queres correr azd ai agent eval generate ou usar os valores predefinidos do otimizador.
   Dataset	Selecione o conjunto de dados de otimização. Se não tiveres um, escolhe se queres correr azd ai agent eval generate ou usar os valores predefinidos do otimizador.
   Número máximo de candidatos	Introduza o número máximo de candidatos a gerar, como 2.
   Modelo de otimização	Selecione uma implementação existente entre os modelos de otimização suportados.

O GitHub Copilot espera por estes inputs antes de começar a otimização. O pedido gerado orienta o Copilot a usar exclusivamente o fluxo de trabalho Agent Optimizer do Microsoft Foundry Skill e os comandos do Azure Developer CLI. Não utiliza as ferramentas MCP da Foundry. O Copilot:

• Inspeciona o código do agente no espaço de trabalho selecionado.
• Inicializa um ambiente AZD a partir de valores existentes azure.yaml e .env se o projeto ainda não tiver um.
• Envia o agente para otimização e implementa o agente hospedado atualizado.
• Cria eval.yaml na pasta de serviço do agente.
• Inicia a otimização depois de reveres e aprovares as alterações e comandos propostos ao ficheiro.

Depois de o Copilot submeter a tarefa, volte ao separador Otimizar. A execução aparece em Execuções de otimização. A tabela mostra o ID da execução, o estado, o número de candidatos, a pontuação de referência, a melhor pontuação e a hora de criação.

Passo 3: Compare e implemente o melhor candidato

1. Quando a execução tem sucesso, seleciona-a em Execuções de Otimização.
2. Compare as pontuações de base e as melhores . Consulte os detalhes da pontuação de cada candidato e selecione Ver alterações para inspecionar as alterações de configuração.
3. Se o melhor candidato melhorar em relação à linha base, selecione Implementar o melhor candidato para atualizar o agente atual. Para o implementar como um novo agente ou alterar as definições de implementação, selecione Deploy Personalizado em vez disso.

Executa a otimização com o Microsoft Foundry Skill

Use este caminho em qualquer host de agente de codificação que suporte a Microsoft Foundry Skill, como o GitHub Copilot no Visual Studio Code, Copilot CLI ou Claude Code. A competência resolve o contexto do agente a partir de azure.yaml, carrega o seu fluxo de trabalho Agent Optimizer e mantém a aplicação e a implementação do candidato atrás dos portões de revisão.

Passo 1: Abrir o espaço de trabalho do agente

Abre uma pasta vazia no host do teu agente de programação. Confirma que a microsoft-foundry habilidade está disponível. Se a capacidade não estiver disponível, siga Utilizar a capacidade Microsoft Foundry em agentes de programação.

Passo 2: Peça à skill que execute o Agent Optimizer

Envie este prompt ao seu agente de programação:

Use the Microsoft Foundry Skill to run the Agent Optimizer workflow for a
Python hosted agent. If this workspace doesn't contain an agent, initialize the
customer support optimization sample from this template:
https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/responses/optimization-customer-support/azure.yaml
Resolve the AZD environment and hosted-agent service, verify that the agent is
optimizer-ready, and deploy and invoke the baseline. Generate and show me the
evaluation dataset, evaluators, and eval.yaml before running optimization.
Verify that the project has a supported optimization model deployment, then run
Agent Optimizer with two candidates. Stop after reporting the operation ID,
portal URL, candidate IDs, and scores. Don't apply or deploy a candidate yet.

O agente de programação pode pedir-lhe que selecione uma subscrição, região, projeto Foundry, serviço de agente, modelo de avaliação ou modelo de otimização quando não conseguir determinar esses valores com base no espaço de trabalho. Revise os ficheiros gerados e os recursos que suportam custos antes de aprovar quaisquer alterações ou comandos.

Passo 3: Candidatar-se e apresentar um candidato aprovado

Depois de rever os resultados da otimização, submeta este prompt de seguimento:

Recommend the best optimization candidate and explain the score improvement.
Summarize the candidate changes before applying anything. After I approve the
candidate, apply it locally, show the source diff, and stop again before
deployment. After I approve deployment, run azd deploy, invoke the agent with
"What is your return policy?", and rerun the evaluation to confirm the
improvement.

A funcionalidade usa azd ai agent optimize apply --candidate <candidate-id> para poderes rever a configuração otimizada localmente. Só é implementado após a sua aprovação, depois invoca e avalia o agente hospedado atualizado.