Prepare o seu agente para otimização (pré-visualização)

Adicionar suporte para o otimizador de agentes ao seu agente requer algumas linhas de código. Não são necessárias alterações no quadro ou lógica condicional. Instala-se o pacote de otimização, configura-se um diretório de configuração e liga-se load_config() no arranque.

Este passo é o primeiro no fluxo de trabalho de otimização. A configuração base que crias define as entradas que o otimizador melhora: instruções, ferramentas, competências e o modelo. O teu agente trabalha da mesma forma, quer a otimização esteja ativa ou não.

Para preparar o seu agente para otimização, conclua estes três passos:

1. Instala o pacote de otimização.
2. Configura um diretório de configuração de base com as tuas instruções e, opcionalmente, ferramentas e competências.
3. Carrega a configuração no arranque com load_config() e usa os valores que esta devolve.

O resto deste artigo apresenta um exemplo completo e explica como funciona a resolução de configuração. Depois de concluir uma execução de otimização, aplica o candidato vencedor e implementa-o — veja Implementar o vencedor.

Pré-requisitos

• Um projeto Foundry com um agente alojado implementado
• Familiaridade com agentes alojados
• Python 3.10 ou posterior

Instalar o pacote de otimização

Instale o pacote azure-ai-agentserver-optimization:

pip install azure-ai-agentserver-optimization

Configurar o diretório de configuração

Cria o .agent_configs/baseline/ diretório na raiz do teu projeto. Este diretório define a configuração base do seu agente — o ponto de partida que o otimizador lê e melhora.

my-agent/
|- main.py
|- azure.yaml
|- requirements.txt
\- .agent_configs/
   |- baseline/              <- your starting config
   |  |- metadata.yaml
   |  |- instructions.md
   |  |- tools.json
   |  \- skills/
   |     \- (initially empty)
   \- <candidate_id>/        <- created by 'azd ai agent optimize apply'
      \- (same layout as baseline/)

A linha base requer metadata.yaml e instructions.md. O ficheiro tools.json e o diretório skills/ são opcionais — inclua-os apenas se o seu agente utilizar ferramentas ou capacidades. O otimizador ativa cada alvo com base em quais destes ficheiros estão presentes.

metadata.yaml

O ficheiro de metadados indica ao carregador de otimização onde encontrar os ficheiros de configuração e que modelo utilizar:

model: gpt-4.1-mini
instruction_file: instructions.md
tools_file: tools.json
skill_dir: skills

instructions.md

O aviso do sistema do seu agente. Escreva-o em texto simples ou com markdown:

You are a travel approval agent for Contoso Ltd. You review travel
requests and enforce company travel policy. Check travel policy limits,
department budget, and suggest cheaper alternatives when appropriate.
Enforce policy rules strictly — do not auto-approve everything.

O otimizador melhora este prompt durante as execuções de otimização. Depois de aplicar um candidato otimizado, este ficheiro contém a versão melhorada.

tools.json

Declare as ferramentas que o seu agente pode chamar usando o formato de chamada de funções OpenAI:

[
  {
    "type": "function",
    "function": {
      "name": "lookup_travel_policy",
      "description": "Look up the company travel policy rules and limits.",
      "parameters": {
        "type": "object",
        "properties": {}
      }
    }
  },
  {
    "type": "function",
    "function": {
      "name": "get_flight_alternatives",
      "description": "Find cheaper flight alternatives for the given destination.",
      "parameters": {
        "type": "object",
        "properties": {
          "destination": {
            "type": "string",
            "description": "The travel destination city"
          }
        },
        "required": ["destination"]
      }
    }
  }
]

O otimizador pode melhorar as descrições das ferramentas para ajudar o modelo a chamar ferramentas com maior precisão. Após a otimização, aplicas descrições melhoradas de volta a este ficheiro.

skills/ (formato de competências do agente)

As competências utilizam o formato aberto de Competências de Agente . Cada habilidade é uma pasta que contém um SKILL.md ficheiro:

skills/
\-- policy-reviewer/
    \-- SKILL.md

Um SKILL.md ficheiro tem um cabeçalho YAML para metadados e um corpo em Markdown para instruções:

---
name: policy-reviewer
description: Reviews travel requests. Use when someone submits a travel request.
---

# Policy Reviewer Skill

When reviewing a travel request:
1. Check destination against restricted countries list
2. Verify trip cost is within department budget
3. Confirm travel dates don't conflict with blackout periods
4. Suggest alternatives if the request exceeds policy limits

O frontmatter YAML (name e description) permite uma divulgação progressiva — o agente carrega apenas os metadados no arranque e depois ativa as instruções completas de skill quando é detetada uma tarefa correspondente.

O otimizador pode descobrir e criar novas competências durante a otimização. Estas competências são escritas no skills/ diretório quando se aplica um candidato otimizado.

Saiba mais sobre o formato Agent Skills em agentskills.io.

Carregar e usar a config

Adicione o carregador de configuração no topo do ponto de entrada do seu agente:

from azure.ai.agentserver.optimization import load_config

config = load_config()

A função load_config() lê de .agent_configs/ e devolve um objeto OptimizationConfig. Quando nenhum candidato à otimização está ativo, devolve a sua configuração base. Se não for encontrada nenhuma fonte de configuração, devolve None.

Parâmetros:

OptimizationConfig Campos:

Use os valores de configuração

Use o modelo e as instruções compostas ao chamar o modelo:

model = config.model or "gpt-4.1-mini"
instructions = config.compose_instructions()

O método compose_instructions() devolve o prompt do sistema com todas as competências detetadas acrescentadas sob a forma de um catálogo de competências.

Aplicar descrições otimizadas de ferramentas

Se o seu agente usa ferramentas (funções), aplique descrições otimizadas a elas:

tools = [lookup_travel_policy, check_department_budget, get_flight_alternatives]
config.apply_tool_descriptions(tools)

O método apply_tool_descriptions() atualiza os metadados de cada função de ferramenta com as descrições melhoradas da configuração de otimização. Isto melhora a precisão do modelo ao decidir qual a ferramenta a chamar.

Se as tuas ferramentas não forem compatíveis com apply_tool_descriptions(), lê as definições otimizadas de config.tool_definitions e aplica-as aos teus próprios objetos de ferramenta. Cada definição inclui tanto a descrição da função otimizada como as descrições dos parâmetros, por isso mapeia ambas para as suas ferramentas por função e nome do parâmetro.

Carregar competências a partir de um diretório

Se a tua configuração de otimização não incluir competências, podes carregá-las a partir de um diretório local:

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

if not config.skills and config.skills_dir:
    config.skills.extend(load_skills_from_dir(Path(config.skills_dir)))

Registar a origem da configuração (recomendado)

Adicione uma linha de registo para confirmar de onde veio a configuração:

import logging

logger = logging.getLogger("my-agent")
logger.info(
    "Config source=%s | model=%s | prompt_len=%d | skills=%d",
    config.source, model, len(instructions), len(config.skills),
)

Exemplo completo

O exemplo seguinte mostra um agente de aprovação de viagens que utiliza a configuração de otimização para instruções, ferramentas e competências:

import json
import logging
import os
from pathlib import Path
from typing import Annotated

from agent_framework import Agent, tool
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.identity import DefaultAzureCredential
from pydantic import Field
from azure.ai.agentserver.optimization import load_config, load_skills_from_dir

logger = logging.getLogger(__name__)


@tool(approval_mode="never_require")
def lookup_travel_policy() -> str:
    """Look up the company travel policy rules and limits."""
    return json.dumps({
        "company": "Contoso Ltd.",
        "approval_thresholds": {
            "auto": 1500, "manager": 3000,
            "director": 7500, "vp": "above 7500"
        },
        "lodging_per_night": {"domestic": 250, "international": 400},
        "airfare": "economy only; business class if flight > 6 hours",
        "advance_booking_days": 14,
    })


@tool(approval_mode="never_require")
def check_department_budget() -> str:
    """Check the remaining travel budget for the employee's department."""
    return json.dumps({
        "department": "Engineering",
        "total_budget": 50000, "remaining": 14800,
    })


@tool(approval_mode="never_require")
def get_flight_alternatives(
    destination: Annotated[str, Field(description="The travel destination city")],
) -> str:
    """Find cheaper flight alternatives for the given destination."""
    return json.dumps({
        "alternatives": [
            {"option": "Flexible dates (+/-2 days)", "savings": "$200-800"},
            {"option": "Nearby alternate airport", "savings": "$100-400"},
        ],
    })


def main():
    # Load optimization config from .agent_configs/
    config = load_config()

    # Load skills from local directory if not provided by optimization
    if not config.skills and config.skills_dir:
        config.skills.extend(load_skills_from_dir(Path(config.skills_dir)))

    model = config.model or os.environ.get(
        "FOUNDRY_MODEL_NAME", "gpt-4.1-mini"
    )
    instructions = config.compose_instructions()

    # Apply optimized tool descriptions
    tools = [lookup_travel_policy, check_department_budget, get_flight_alternatives]
    config.apply_tool_descriptions(tools)

    logger.info(
        "Config source=%s | model=%s | prompt_len=%d | skills=%d",
        config.source, model, len(instructions), len(config.skills),
    )

    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=model,
        credential=DefaultAzureCredential(),
    )

    agent = Agent(
        client=client,
        instructions=instructions,
        tools=tools,
        default_options={"store": False},
    )

    server = ResponsesHostServer(agent)
    server.run()


if __name__ == "__main__":
    main()

Como funciona

1. Funcionamento normal: Não são definidas variáveis de ambiente de otimização. O carregador de configuração lê .agent_configs/baseline/ e devolve a sua configuração base. O agente trabalha com as tuas instruções originais.

2. Durante a otimização: O otimizador define OPTIMIZATION_CONFIG com a configuração do candidato como JSON inline. O seu agente utiliza as instruções e descrições das ferramentas do candidato durante a avaliação.

   Note

   Durante a avaliação, o otimizador executa o seu agente em cada tarefa do seu conjunto de dados, pelo que quaisquer chamadas a ferramentas externas são executadas de facto. Para orientações sobre como evitar efeitos secundários não intencionais, veja Como funciona o otimizador de agentes.

3. Depois de selecionar o vencedor: Execute azd ai agent optimize apply --candidate <id> para escrever os ficheiros de configuração otimizados em .agent_configs/<candidate_id>/ no seu projeto. Depois azd deploy implanta o agente com a configuração melhorada. Para os passos completos de aplicação e implementação, veja Implementar o vencedor.

O teu código nunca muda entre estes estados. A resolução da configuração é totalmente automática.

Ordem de resolução da configuração

A load_config() função resolve a configuração usando uma cadeia de prioridades (vence a primeira partida):

Verificar

Confirme que o pacote é importável e que a configuração carrega corretamente:

# Verify the package is importable
python -c "from azure.ai.agentserver.optimization import load_config; print('OK')"

# Run locally and check the log output
azd ai agent run
# Expected log: "Config source=baseline | model=gpt-4.1-mini | ..."

Conteúdo relacionado

• Visão geral do otimizador de agentes
• Criar um conjunto de dados de avaliação e avaliadores
• Otimizar as instruções, competências, ferramentas e modelos do agente
• Quickstart: Otimizar um agente hospedado
• Formato de Competências de Agente — padrão aberto para competências portáteis de agentes