Início Rápido: Otimizar um agente hospedado (versão prévia)

• azd CLI (CLI do desenvolvedor do Azure).

• CLI do Azure para autenticação.

• A extensão microsoft.foundry para azd (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 de Python usados neste caminho:

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

• Um projeto do Foundry existente que já contém o agente hospedado, o conjunto de dados registrado e o avaliador que você deseja usar para otimização.

• Código do Visual Studio.

• Microsoft Foundry Toolkit para Visual Studio Code versão 1.6.4 ou posterior, conectado ao Azure. O Foundry Toolkit instala e atualiza a Habilidade Microsoft Foundry usada por este fluxo de trabalho.

• GitHub Copilot em Visual Studio Code com acesso ao modo de agente. O Foundry Toolkit envia a solicitação do Otimizador de Agente para GitHub Copilot depois que você seleciona o workspace do agente.

• CLI do Azure e CLI do Azure para Desenvolvedores (AZD) instalados e autenticados:

  az login
  azd auth login
  

• Um host para agente de codificação com a Microsoft Foundry Skill instalada.

• CLI do Azure e CLI do Azure para Desenvolvedores (AZD) instalados e autenticados:

  az login
  azd auth login
  

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

  azd ext install microsoft.foundry
  

  Se ele já estiver instalado, atualize-o:

  azd ext upgrade microsoft.foundry
  

Etapa 1: Criar o projeto

Inicialize um novo projeto do modelo de exemplo 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 .

Esse modelo importa o exemplo de Suporte ao Cliente de Otimização, um agente hospedado Python pronto para otimização que usa a abordagem bring-your-own e o protocolo Responses. Representa um agente de suporte eletrônico do consumidor que lida com consultas de pedidos, retornos, declarações de garantia, solução de problemas, reclamações, recomendações e escalonamento. A instrução de linha de base deliberadamente mínima torna as melhorias da otimização de instrução e da descoberta de habilidades fáceis de comparar.

O exemplo chama load_config() para carregar a configuração base ou a configuração candidata e inclui .agent_configs/baseline/, eval.yaml, conjuntos de dados de avaliação completos e rápidos, configuração de contêiner e o manifesto de implantação do Foundry. O fluxo interativo importa esses arquivos e solicita que você informe sua assinatura do Azure, a região e as configurações de implantação do modelo.

Etapa 2: Provisionar e implantar

Autenticar e provisionar os recursos de Azure:

az login
azd auth login
azd provision

O provisionamento leva aproximadamente dois minutos e cria uma conta do Foundry, um projeto, Registro de Contêiner do Azure e implantações de modelo.

Implante o agente:

azd deploy

Teste a implantação:

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

Etapa 3: gerar o pacote de avaliação e otimizar

Gere um conjunto de dados de avaliação e avaliadores para 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 agente. O otimizador usa esses arquivos para medir o aprimoramento.

Execute o otimizador:

azd ai agent optimize --max-candidates 2

A CLI solicita que você selecione um modelo de otimização. Para ignorar o prompt, passe-o diretamente:

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

A CLI detecta seu agente a partir de azure.yaml e usa o eval.yaml gerado automaticamente. Com dois candidatos, a otimização normalmente é concluída em cerca de 8 minutos. O progresso em tempo real é mostrado:

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 a URL do portal para monitorar seu trabalho no portal do 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 aprimorados e deve ser da lista com suporte (família gpt-5 ou DeepSeek). Você também pode definir optimization_model em options: em eval.yaml para evitar passar o sinalizador a cada vez.

Etapa 4: Implementar a versão vencedora

A estrela (*) na saída indica o melhor candidato. Aplique a configuração otimizada localmente e implante:

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

O apply comando baixa a configuração .agent_configs/<candidate_id>/ otimizada e atualiza sua azure.yaml para usar as novas instruções. O comando deploy coloca o agente otimizado em produção por meio da implantação de código.

Invoque seu agente para verificar a melhoria:

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

Você também pode executar a avaliação para confirmar a melhoria da pontuação:

azd ai agent eval run

Caminho do SDK do Python

Use as etapas a seguir se quiser executar o otimizador de Python em vez do fluxo de trabalho da CLI do Desenvolvedor Azure descrito anteriormente.

Esse caminho pressupõe que você já tenha os seguintes recursos em um projeto de Foundry existente:

• Um agente hospedado para otimização.
• Um conjunto de dados de treinamento registrado.
• Um avaliador registrado.

Ao contrário do fluxo do Azure Developer CLI descrito anteriormente, a abordagem com o SDK do Python não cria a estrutura de um projeto nem gera eval.yaml, um conjunto de dados ou avaliadores para você. Se você quiser que o exemplo crie esses ativos automaticamente, use azd ai agent eval generate primeiro.

1. Criar um .env arquivo

Crie uma pasta de trabalho e adicione um .env arquivo 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>

Execute o script nessa mesma pasta de trabalho para load_dotenv() poder carregar o .env arquivo automaticamente. Se você preferir executá-lo de outro diretório, defina os mesmos valores em seu ambiente de shell primeiro.

Use o ponto de extremidade exato do projeto na página visão geral do projeto do Foundry. O script Python envia sua primeira solicitação imediatamente. Se FOUNDRY_PROJECT_ENDPOINT for apenas um espaço reservado ou apontar para o projeto errado, a execução falhará com ResourceNotFound: The project does not exist.

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

2. Executar o trabalho de otimização

Crie um arquivo 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 sucesso, o script imprime o candidato vencedor e o candidate_id.

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

3. Aplicar a opção vencedora

Se você também estiver trabalhando no projeto local azd usado no fluxo da CLI acima, aplique o candidato vencedor usando o candidate_id retornado pelo script Python:

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

Se você só precisar inspecionar o resultado, use as pontuações dos candidatos e os identificadores de avaliação impressos pelo script para revisar a configuração vencedora no Foundry antes de promovê-la.

Executar a otimização no VS Code

O Foundry Toolkit inclui uma experiência de Otimização de Agente nativa para agentes hospedados implantados. No playground do agente, você pode iniciar uma execução de otimização, comparar candidatos com a linha de base, inspecionar as alterações de configuração e implantar o melhor candidato.

Etapa 1: Selecionar um agente hospedado implantado

1. Selecione o Foundry Toolkit na Barra de Atividades.
2. Em Meus Recursos, selecione Agentes.
3. Se você tiver um agente hospedado implantado, selecione-o para abrir o playground do agente hospedado.
4. Se você não tiver um agente hospedado implantado, conclua o caminho do VS Code no Início Rápido: Implantar seu primeiro agente hospedado. Após a conclusão da implantação, retorne aos Agentes e selecione o novo agente hospedado.

Etapa 2: iniciar uma execução de otimização

1. Selecione a guia Otimizar , que está marcada como Visualização.

1. Selecione Nova Otimização.

2. Em Selecionar Workspace, escolha o workspace que contém o código do agente hospedado selecionado:

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

   O Foundry Toolkit usa os arquivos de workspace 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 uma solicitação ao Agent Optimizer preenchida com o tipo, o nome e o 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	Insira as métricas ou os avaliadores a serem usados. Se você não os tiver, escolha se deseja executar azd ai agent eval generate ou usar os padrões internos do otimizador.
   Dataset	Selecione o conjunto de dados de otimização. Se você não tiver um, escolha se deseja executar azd ai agent eval generate ou usar os padrões internos do otimizador.
   Máximo de candidatos	Insira o número máximo de candidatos a serem gerados, como 2.
   Modelo de otimização	Selecione uma implantação existente nos modelos de otimização com suporte.

GitHub Copilot aguarda essas entradas antes de iniciar a otimização. A solicitação gerada orienta o Copilot a usar exclusivamente o fluxo de trabalho Agent Optimizer da habilidade Microsoft Foundry e os comandos da CLI do Azure Developer. Ele não usa ferramentas do MCP do Foundry. Copilot:

• Inspeciona o código do agente no espaço de trabalho selecionado.
• Inicializa um ambiente do AZD a partir dos valores existentes de azure.yaml e .env, caso o projeto ainda não tenha um.
• Conecta o agente para otimização e implanta o agente hospedado atualizado.
• Cria eval.yaml na pasta de serviço do agente.
• Inicia a otimização depois de examinar e aprovar as alterações de arquivo e os comandos propostos.

Depois que o Copilot submeter o trabalho, volte para a guia Otimizar. A execução aparece em Execuções de otimização. A tabela mostra o ID da execução, o status, a contagem de candidatos, a pontuação de referência, a melhor pontuação e a hora de criação.

Etapa 3: Comparar e implantar o melhor candidato

1. Quando a execução for bem-sucedida, selecione-a em Execuções de Otimização.
2. Compare as pontuações Baseline e Melhor. Examine os detalhes da Pontuação de cada candidato e selecione Exibir alterações para inspecionar as alterações de configuração.
3. Se o melhor candidato melhorar na linha de base, selecione Implantar o melhor candidato para atualizar o agente atual. Para implantá-lo como um novo agente ou alterar as configurações de implantação, selecione Implantar personalizado .

Executar a otimização com o Microsoft Foundry Skill

Use este caminho em qualquer host para agentes de codificação que ofereça suporte à Microsoft Foundry Skill, como o GitHub Copilot no Visual Studio Code, o Copilot CLI ou o Claude Code. A skill resolve o contexto do agente a partir de azure.yaml, carrega seu fluxo de trabalho do Agent Optimizer e mantém a aplicação candidata e a implantação sujeitas a gates de revisão.

Etapa 1: Abrir o workspace do agente

Abra uma pasta vazia no host do agente de codificação. Confirme se a microsoft-foundry habilidade está disponível. Se a habilidade não estiver disponível, consulte Usar a habilidade Microsoft Foundry em agentes de codificação.

Etapa 2: Peça à habilidade que execute o Agent Optimizer

Envie este prompt ao seu agente de codificaçã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 codificação pode solicitar que você selecione uma assinatura, região, projeto do Foundry, serviço de agente, modelo de avaliação ou modelo de otimização quando não puder resolver esses valores do workspace. Examine os arquivos gerados e os recursos que geram custos antes de aprovar quaisquer alterações ou comandos.

Etapa 3: Promover e implantar um candidato aprovado

Depois de examinar os resultados da otimização, envie este prompt de acompanhamento:

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 habilidade usa azd ai agent optimize apply --candidate <candidate-id> para que você possa revisar a configuração otimizada localmente. Ele é implantado somente após a aprovação e, em seguida, invoca e avalia o agente hospedado atualizado.