Deixe seu agente pronto para o otimizador (prévia)

Adicionar suporte para o otimizador de agente ao seu agente requer algumas linhas de código. Nenhuma alteração de estrutura ou lógica condicional é necessária. Instale o pacote de otimização, configure um diretório de configuração e chame load_config() na inicialização.

Pré-requisitos

• Um projeto da Foundry com um agente hospedado implantado
• Familiaridade com agentes hospedados
• Python 3.10 ou posterior

Instalar o pacote de otimização

Instalar o pacote azure-ai-agentserver-optimization:

pip install azure-ai-agentserver-optimization

Configurar o diretório de configuração

Crie o .agent_configs/baseline/ diretório na raiz do projeto. Este diretório define a configuração base do seu agente — o ponto de partida que o otimizador lê e usa como base para aprimoramentos.

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 arquivo de metadados informa ao carregador de otimização onde localizar arquivos de configuração e qual modelo usar:

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

instructions.md

O prompt do sistema do seu agente. Escreva-o como texto simples ou 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 esse prompt durante as execuções de otimização. Depois de aplicar um candidato otimizado, esse arquivo contém a versão aprimorada.

tools.json

Declare as ferramentas que seu agente pode chamar usando o formato de chamada de função 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 mais precisão. Após a otimização, você aplicará descrições aprimoradas de volta a esse arquivo.

skills/ (Formato de habilidades do agente)

As habilidades usam o formato de Habilidades do Agente aberto. Cada habilidade é uma pasta que contém um SKILL.md arquivo:

skills/
└── policy-reviewer/
    └── SKILL.md

Um arquivo SKILL.md tem frontmatter YAML de metadados e corpo em Markdown com 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) habilita a divulgação progressiva – o agente carrega apenas metadados na inicialização e ativa as instruções completas de habilidade quando uma tarefa correspondente é detectada.

O otimizador pode descobrir e criar novas habilidades durante a otimização. Essas habilidades são gravadas no diretório skills/ ao aplicar um candidato otimizado.

Saiba mais sobre o formato habilidades do agente em agentskills.io.

Carregar a configuração de otimização

Adicione o carregador de configuração na parte superior do ponto de entrada do agente:

from azure.ai.agentserver.optimization import load_config

config = load_config()

A load_config() função lê .agent_configs/ e retorna um OptimizationConfig objeto. Quando nenhum candidato à otimização estiver ativo, ele retornará sua configuração de linha de base.

Parâmetros:

OptimizationConfig Campos:

Use os valores da 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 compose_instructions() método retorna o prompt do sistema com todas as habilidades descobertas acrescentadas como um catálogo de habilidades.

Aplicar descrições de ferramentas otimizadas

Se o agente usar 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 aprimoradas da configuração de otimização. Isso melhora a precisão do modelo ao decidir qual ferramenta chamar.

Carregar habilidades de um diretório

Se a configuração de otimização não incluir habilidades, você poderá carregá-las 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)))

Registrar a origem da configuração (recomendado)

Adicione uma linha de log 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 implantar:

# 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 baixa as versões otimizadas de instructions.md, tools.json e skills/ do candidato e as grava em .agent_configs/<candidate_id>/ no seu projeto. Na próxima inicialização, load_config() detecta o candidato e usa a configuração otimizada.

Exemplo completo

O exemplo a seguir mostra um agente de aprovação de viagem que usa a configuração de otimização para instruções, ferramentas e habilidades:

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. Operação normal: nenhuma variável de ambiente de otimização é definida. O carregador de configuração lê .agent_configs/baseline/ e retorna sua configuração de linha de base. O agente funciona com suas instruções originais.

2. Durante a otimização: O otimizador define OPTIMIZATION_CONFIG com a configuração do candidato como JSON inline. Seu agente usa as instruções do candidato e as descrições da ferramenta durante a avaliação.

   Warning

   Durante a avaliação, o otimizador invoca seu agente em cada tarefa em seu conjunto de dados. Se o agente chamar ferramentas externas (APIs, bancos de dados, serviços de terceiros), essas chamadas serão executadas de verdade. Considere simular implementações de ferramentas ou apontar para endpoints de teste para evitar efeitos colaterais não intencionais.

3. Após aplicar a configuração vencedora: você executa azd ai agent optimize apply --candidate <id> para gravar os arquivos de configuração otimizados em .agent_configs/<candidate_id>/ no seu projeto. Em seguida, azd deploy implanta o agente com a configuração aprimorada.

Seu código nunca muda entre esses estados. A definição da configuração é totalmente automática.

Ordem de resolução da configuração

A função load_config() determina a configuração usando uma cadeia de prioridades (a primeira correspondência encontrada prevalece):

Verificar

Confirme se o pacote é importável e a configuração é carregada 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

• Início Rápido: Otimizar um agente hospedado
• Criar um conjunto de dados de avaliação personalizado
• Otimizar instruções, habilidades, ferramentas e modelos do agente
• Visão geral do otimizador de agentes
• Formato Agent Skills — padrão aberto para habilidades de agente portáteis