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.

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
├── agent.yaml
├── 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/)

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 a configuração de otimização

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.

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.

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

Aplicar a configuração otimizada localmente

Depois de executar azd ai agent optimize e selecionar um candidato vencedor, aplique-o ao seu projeto local antes de implementar:

# 1. Run optimization
azd ai agent optimize

# 2. Review results
azd ai agent optimize status <job-id>

# 3. Apply the winning candidate locally
azd ai agent optimize apply --candidate <candidate_id>

# 4. Deploy with the optimized config
azd deploy

O comando apply transfere os ficheiros otimizados instructions.md, tools.json e skills/ da compilação candidata e grava-os em .agent_configs/<candidate_id>/ no seu projeto. No próximo arranque, load_config() deteta o candidato e usa a configuração otimizada.

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(
        "AZURE_AI_MODEL_DEPLOYMENT_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.

   Warning

   Durante a avaliação, o otimizador invoca o seu agente contra todas as tarefas do seu conjunto de dados. Se o seu agente chamar ferramentas externas (APIs, bases de dados, serviços de terceiros), essas chamadas são realmente executadas. Considere simular implementações de ferramentas ou apontar para endpoints de teste para evitar efeitos colaterais indesejados.

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.

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

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