Szybki start: optymalizowanie hostowanego agenta

• azd CLI (Azure Developer CLI) w wersji 1.37.0 lub nowszej.

• Azure CLI na potrzeby uwierzytelniania.

• microsoft.foundry Rozszerzenie dla azd. Zawiera polecenia azd ai agent, takie jak azd ai agent optimize, ale nie polecenia azd ai eval:

  azd ext install microsoft.foundry
  

  Jeśli już zainstalowano, uaktualnij:

  azd ext upgrade microsoft.foundry
  

• Rozszerzenie azure.ai.evaluations dla azd, które udostępnia polecenia azd ai eval. Wymaga to azd 1.33.0 lub nowszego:

  azd ext install azure.ai.evaluations
  

  Jeśli już zainstalowano, uaktualnij:

  azd ext upgrade azure.ai.evaluations
  

• Azure CLI na potrzeby uwierzytelniania.

• Python 3.10 lub nowszy.

• Pakiety Python używane w tej ścieżce:

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

• Istniejący projekt foundry, który zawiera już hostowanego agenta, zarejestrowany zestaw danych i ewaluatora, którego chcesz użyć do optymalizacji.

• Azure CLI na potrzeby uwierzytelniania.

• zestaw SDK platformy .NET 10 lub nowszy.

• Pakiety .NET używane w tej ścieżce.

  dotnet add package Azure.AI.Projects --prerelease
  dotnet add package Azure.Identity
  

• Istniejący projekt foundry, który zawiera już hostowanego agenta, zarejestrowany zestaw danych i ewaluatora, którego chcesz użyć do optymalizacji.

• Visual Studio Code.

• Microsoft Foundry Toolkit for Visual Studio Code w wersji 1.6.4 lub nowszej, z zalogowanym kontem w usłudze Azure. Narzędzie Foundry Toolkit instaluje i aktualizuje umiejętności Microsoft Foundry używane przez ten przepływ pracy.

• GitHub Copilot w Visual Studio Code z dostępem do trybu agenta. Zestaw narzędzi Foundry wysyła żądanie optymalizatora agentów do GitHub Copilot po wybraniu obszaru roboczego agenta.

• Azure CLI i interfejs wiersza polecenia dewelopera Azure (AZD) w wersji 1.37.0 lub nowszej, zainstalowano i uwierzytelniono:

  az login
  azd auth login
  

• Rozszerzenie azure.ai.evaluations dla AZD, jeśli chcesz wygenerować zasoby ewaluacyjne za pomocą polecenia azd ai eval generate. Wymaga to AZD 1.33.0 lub nowszego:

  azd ext install azure.ai.evaluations
  

• Host dla agenta kodującego z zainstalowaną funkcją Microsoft Foundry Skill.

• Azure CLI i Azure Developer CLI (AZD) w wersji 1.37.0 lub nowszej, zainstalowane i uwierzytelnione:

  az login
  azd auth login
  

• microsoft.foundry Rozszerzenie AZD. Nie zawiera azd ai eval poleceń. Zainstaluj go przed uruchomieniem przepływu pracy:

  azd ext install microsoft.foundry
  

  Jeśli jest już zainstalowany, uaktualnij go.

  azd ext upgrade microsoft.foundry
  

• Jest to azure.ai.evaluations rozszerzenie dla AZD, które udostępnia polecenia azd ai eval, używane przez przepływ pracy. Wymaga to AZD 1.33.0 lub nowszego:

  azd ext install azure.ai.evaluations
  

  Jeśli jest już zainstalowany, uaktualnij go.

  azd ext upgrade azure.ai.evaluations
  

Krok 1. Tworzenie projektu

Zainicjuj nowy projekt na podstawie przykładowego szablonu optymalizacji:

mkdir my-agent && cd my-agent
azd ai agent init -t https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/responses/optimization-customer-support/azure.yaml .

Ten szablon importuje przykład „Optimization Customer Support” — hostowanego agenta Python gotowego do optymalizacji, który korzysta z podejścia „bring your own” oraz protokołu Responses. Reprezentuje on agenta pomocy technicznej dla elektroniki konsumenckiej, który obsługuje zapytania dotyczące zamówień, zwrotów, oświadczeń gwarancji, rozwiązywania problemów, skarg, zaleceń i eskalacji. Celowo minimalna instrukcja odniesienia sprawia, że ulepszenia optymalizacji instrukcji i odnajdywania umiejętności są łatwe do porównania.

Przykładowe wywołania służą do ładowania konfiguracji bazowej lub konfiguracji kandydata i obejmują .agent_configs/baseline/, zestawy danych pełnej i szybkiej oceny, konfigurację kontenera oraz manifest wdrożenia Foundry. Interaktywny przepływ importuje te pliki i prosi o podanie subskrypcji platformy Azure, regionu oraz ustawień wdrożenia modelu.

Krok 2. Aprowizuj i wdróż

Uwierzytelnij i aprowizuj zasoby platformy Azure:

az login
azd auth login
azd provision

Proces aprowizacji trwa około dwóch minut i tworzy konto Foundry, projekt, usługę Azure Container Registry oraz wdrożenia modeli.

Wdróż agenta:

azd deploy

Przetestuj wdrożenie:

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

Krok 3: Wygeneruj zasoby oceny

Optymalizator ocenia kandydatów przy użyciu zestawu danych i ewaluatorów, które dostarczasz. Aby utworzyć miarę, która odzwierciedla sposób oceniania własnego agenta, wygeneruj zestaw danych i ewaluator rubryki za pomocą poleceń azd ai eval. Użyj nazwy wdrożonego agenta jako celu. To jest name usługi agenta w azure.yaml.

W poniższych poleceniach zastąp wartości <generation-deployment>, <judge-deployment>, <eval-deployment>i <optimization-deployment> nazwami wdrożeń modelu w projekcie Foundry. Ustaw jawnie każdą rolę.

azd ai eval generate \
  --target <agent-name> \
  --from prompt \
  --generation-model <generation-deployment> \
  --dataset-name support-tests \
  --evaluator-name support-rubric \
  --max-samples 15 \
  --agent-instruction "A customer support agent for a consumer electronics company. It handles order inquiries, returns and refunds, warranty claims, device troubleshooting, complaints, product recommendations, and escalation to a human agent."

Polecenie generuje zestaw danych i ewaluator w projekcie Foundry, pobiera je do evals/datasets/support-tests.jsonl i evals/evaluators/support-rubric.json oraz rejestruje oba w evals/azure.eval.yaml.

Otwórz wygenerowane pliki i przejrzyj je przed kontynuowaniem. Jeśli generate wyświetla ostrzeżenie dotyczące jakości danych wejściowych, przejrzyj wygenerowane pliki z dodatkową starannością. Edytuj wiersze lub kryteria, które nie pasują do sposobu zachowania agenta.

Krok 4. Zmierz linię bazową

Skonfiguruj ewaluację wdrożonego agenta, aby można było później porównać zoptymalizowanego agenta według tej samej miary. Polecenie generate wyświetla odpowiadające polecenie init. Optymalizator ponownie używa tej oceny w kroku 5. Dodaj model sędziego i imię:

azd ai eval init \
  --target <agent-name> \
  --source dataset \
  --dataset support-tests \
  --evaluation-level turn \
  --evaluator builtin.task_completion \
  --evaluator support-rubric \
  --path ./evals \
  --judge-model <judge-deployment> \
  --name optimize-check

azd ai eval create optimize-check
azd ai eval run start --eval optimize-check --name baseline --wait

Polecenie init dodaje usługę oceny do azure.yaml. Polecenie create rejestruje ocenę w projekcie Foundry. Przebieg wyświetla wskaźnik zdawalności i podsumowanie dla poszczególnych ewaluatorów:

TEST CASE RESULTS
Total        15
Passed        <n>
Failed        <n>
Errored       <n>
Skipped       <n>
Pass rate  <percent> (<n> passed / 15 total test cases)

EVALUATOR RESULTS
EVALUATOR       PASS  FAIL  SKIP  ERROR   SCORED  PASS RATE  MEAN SCORE
...

Krok 5: Uruchom optymalizator

Uruchom optymalizator z ewaluacją, którą skonfigurowałeś w kroku 4:

azd ai agent optimize \
  --eval optimize-check \
  --max-candidates 2 \
  --eval-model <eval-deployment> \
  --optimize-model <optimization-deployment>

Opcja --eval ponownie używa oceny dodanej optimize-checkazd ai eval init do projektu. Optymalizator pobiera zestaw danych i ewaluatorów z tej oceny, więc nie przekazujesz --dataset ani --evaluator. Ponownie używa tylko oceny, która jest przeznaczona dla agenta i jest uruchamiana na poziomie włączania zestawu danych, jak wykonuje ocena kroku 4.

Jeśli pominiesz --eval, interfejs wiersza polecenia użyje oceny z projektu, która jest przeznaczona dla agenta. Jeśli więcej niż jedna ocena dotyczy agenta, CLI poprosi Cię o wybranie jednej. Z parametrem --no-prompt kończy się niepowodzeniem, więc przekaż --eval. Aby wybrać ewaluację z pliku konfiguracji, przekaż --eval-config ścieżkę do pliku, na przykład evals/azure.eval.yaml.

Aby ocenić kandydatów na innym zestawie danych, przekaż w --dataset ścieżkę do lokalnego pliku JSONL lub zarejestrowany zestaw danych jako name:version. Aby dodać ewaluatorów, przekaż element --evaluator osobno dla każdego ewaluatora.

Jeśli pominiesz --optimize-model, interfejs wiersza polecenia wyświetli monit o wybranie modelu. W trybie nienadzorowanym przekaż --eval-model i --optimize-model. CLI wykrywa Twojego agenta na podstawie azure.yaml. Praca z dwoma kandydatami może potrwać od 15 do 20 minut. Interfejs wiersza polecenia pokazuje postęp podczas uruchamiania zadania:

  Note: Optimization creates candidate agents as draft versions.
  Your live agent versions are not affected until you explicitly deploy a candidate.

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

Użyj adresu URL portalu, aby monitorować swoje zadanie w portalu Foundry. Wiersz Config pokazuje źródło i nazwę oceny, którą optymalizator wykorzystuje ponownie. Źródłem jest usługa ewaluacyjna lub plik konfiguracji, gdy przekażesz --eval-config. Aby sprawdzić zadanie z terminalu, uruchom polecenie azd ai agent optimize status <job-id>.

Model oceny ocenia każdą odpowiedź (działa dowolny model uzupełniania czatów). Model optymalizacji (--optimize-model) generuje ulepszonych kandydatów i musi pochodzić z listy obsługiwanych (rodzina gpt-5 lub DeepSeek).

Krok 6. Wdróż zwycięzcę

Gwiazdka (★) w danych wyjściowych wskazuje najlepszego kandydata.

azd env get-values

azd env set AGENT_<service-key>_OPTIMIZATION_JOB_ID <job-id>

Zastosuj zoptymalizowaną konfigurację lokalnie, a następnie wdróż:

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

Polecenie apply pobiera zoptymalizowaną konfigurację do .agent_configs/<candidate_id>/, dodaje OPTIMIZATION_CANDIDATE_ID do środowiska usługi azure.yaml i wyświetla różnice w instrukcjach. Polecenie deploy wdraża zoptymalizowanego agenta na środowisko produkcyjne za pomocą usługi CodeDeploy.

Uruchom agenta, aby sprawdzić nowe zachowanie:

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

Krok 7: Zweryfikuj przy użyciu niezależnej oceny

Optymalizator ocenia kandydatów za pomocą własnych ewaluatorów w ramach własnego uruchomienia. Upewnij się, że wdrożony agent został ulepszony, uruchamiając tę samą ocenę uruchomioną w kroku 4:

azd ai eval run start --eval optimize-check --name optimized --wait

Porównaj wskaźnik zaliczenia i wyniki każdego ewaluatora z uruchomieniem punktu odniesienia. Aby zobaczyć, dlaczego wiersze zakończyły się niepowodzeniem, uruchom azd ai eval run output list ... --failed-only polecenie, które przebieg wyświetla w obszarze Zbadaj.

Wzrost wyniku optymalizatora nie gwarantuje wzrostu wyniku w niezależnej ocenie. Jeśli zoptymalizowany agent nie poprawi planu bazowego, nie zachowaj go. Przejrzyj wiersze zakończone niepowodzeniem, dostosuj zestaw danych lub kryteria oceny i ponownie uruchom optymalizator.

Aby sprawdzić wskaźnik powodzenia w potoku, dodaj element --fail-on pass-rate=<0..1> do elementu azd ai eval run start. Polecenie kończy działanie z kodem 1, gdy wskaźnik zaliczonych testów dla danego uruchomienia jest niższy od tej wartości. Sprawdzenie nie jest porównywane z przebiegiem bazowym.

ścieżka zestawu SDK Python

Wykonaj poniższe kroki, jeśli chcesz uruchomić optymalizator z Python zamiast przepływu pracy interfejsu wiersza polecenia dewelopera Azure opisanego wcześniej.

Ta ścieżka zakłada, że masz już następujące zasoby w istniejącym projekcie Foundry:

• Hostowany agent służący do optymalizacji.
• Zarejestrowany zbiór danych treningowych.
• Zarejestrowany ewaluator.

W przeciwieństwie do opisanego wcześniej przepływu pracy Azure Developer CLI ścieżka Python SDK nie tworzy za Ciebie struktury projektu ani nie generuje zestawu danych ani modułów oceniających. Jeśli chcesz utworzyć te zasoby przy użyciu narzędzia Azure Developer CLI, zainstaluj rozszerzenie azure.ai.evaluations za pomocą polecenia azd ext install azure.ai.evaluations (wymaga azd w wersji 1.33.0 lub nowszej), a następnie uruchom azd ai eval generate.

1. Tworzenie .env pliku

Utwórz folder roboczy, a następnie dodaj .env plik z następującymi wartościami:

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>

Uruchom skrypt z tego samego folderu roboczego, aby load_dotenv() automatycznie załadować .env plik. Jeśli wolisz uruchomić go z innego katalogu, najpierw ustaw te same wartości w środowisku powłoki.

Użyj dokładnego punktu końcowego projektu na stronie Przegląd projektu Foundry. Skrypt Python natychmiast wysyła swoje pierwsze żądanie. Jeśli FOUNDRY_PROJECT_ENDPOINT jest tylko symbolem zastępczym lub wskazuje na niewłaściwy projekt, uruchomienie kończy się błędem ResourceNotFound: The project does not exist.

Ustaw EVAL_MODEL i OPTIMIZATION_MODEL jako nazwy wdrożeń istniejących już w projekcie Foundry, a nie tylko nazwy rodzin modeli. Jeśli na przykład wdrożenie projektu ma nazwę gpt-4.1-mini lub DeepSeek-V3.2, użyj tej dokładnej nazwy wdrożenia w pliku .env.

2. Uruchamianie zadania optymalizacji

Utwórz plik o nazwie optimize_hosted_agent.py w tym samym folderze co .env:

"""
DESCRIPTION:
    Create an optimization job for a hosted agent using the latest agent
    optimization API, poll the job to completion, and list its candidates.

USAGE:
    python optimize_hosted_agent_v3.py

    Before running the sample:

    pip install azure-ai-projects azure-ai-agentserver-optimization python-dotenv

    Set these environment variables with your own values:
    1) FOUNDRY_PROJECT_ENDPOINT - Required. The Microsoft Foundry project endpoint.
    2) FOUNDRY_AGENT_NAME       - Required. The hosted agent name.
    3) DATASET_NAME             - Required. The registered training dataset name.
    4) EVALUATOR_NAME           - Required. The registered evaluator name.
    5) DATASET_VERSION          - Optional. The dataset version. Defaults to "1".
    6) EVAL_MODEL               - Optional. The evaluation model. Defaults to "gpt-4o".
    7) OPTIMIZATION_MODEL       - Optional. The optimization model. Defaults to "gpt-5".
    8) POLL_INTERVAL_SECONDS    - Optional. Seconds between status polls. Defaults to 10.
    9) OPTIMIZATION_JOB_ID      - Optional. An existing job ID to resume instead of creating a job.
   10) OPTIMIZATION_LOCAL_DIR   - Optional. Path to the local .agent_configs directory.
   11) CREDENTIAL_PROCESS_TIMEOUT_SECONDS
                                - Optional. Credential subprocess timeout. Defaults to 60.
"""

import os
import time
from pathlib import Path

from azure.ai.agentserver.optimization import load_config, load_skills_from_dir
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AgentOptimizationBaselineAgentConfiguration,
    AgentOptimizationCandidateExpand,
    AgentOptimizationCandidateSearchConfiguration,
    AgentOptimizationConfiguration,
    AgentOptimizationEvaluationConfiguration,
    AgentOptimizationEvaluator,
    AgentOptimizationFoundryAgentTargetConfiguration,
    AgentOptimizationJob,
    AgentOptimizationModelConfiguration,
    AgentOptimizationSkill,
    AgentOptimizationSpace,
    AgentOptimizationTargetCompletionDatasetReferenceDataSource,
    AgentOptimizationTargetCompletionEvaluationSet,
    EvaluationModelConfiguration,
    JobStatus,
    TargetAttribute,
)
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"))
existing_job_id = os.environ.get("OPTIMIZATION_JOB_ID")
credential_process_timeout_seconds = int(
    os.environ.get("CREDENTIAL_PROCESS_TIMEOUT_SECONDS", "60")
)

# Reads the hosted agent's baseline config from .agent_configs/baseline/metadata.yaml.
optimization_config = load_config()

target_attributes = [TargetAttribute.INSTRUCTIONS]
baseline_configuration = None
if optimization_config:
    loaded_skills = optimization_config.skills
    if not loaded_skills and optimization_config.skills_dir:
        loaded_skills = load_skills_from_dir(Path(optimization_config.skills_dir))

    skills = [
        AgentOptimizationSkill(
            name=skill.name,
            description=skill.description,
            body=skill.body or None,
        )
        for skill in loaded_skills
    ]

    if skills:
        target_attributes.append(TargetAttribute.SKILLS)
    if optimization_config.tool_definitions:
        target_attributes.append(TargetAttribute.TOOLS)

    baseline_configuration = AgentOptimizationBaselineAgentConfiguration(
        system_prompt=optimization_config.instructions,
        current_model=optimization_config.model,
        skills=skills or None,
        tools=optimization_config.tool_definitions or None,
    )

with (
    DefaultAzureCredential(
        process_timeout=credential_process_timeout_seconds
    ) as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
    job_request = AgentOptimizationJob(
        target_configuration=AgentOptimizationFoundryAgentTargetConfiguration(
            name=agent_name
        ),
        optimization_model_configuration=AgentOptimizationModelConfiguration(
            model=optimization_model
        ),
        optimization_configuration=AgentOptimizationConfiguration(
            evaluation_configuration=AgentOptimizationEvaluationConfiguration(
                training_set=AgentOptimizationTargetCompletionEvaluationSet(
                    source=AgentOptimizationTargetCompletionDatasetReferenceDataSource(
                        name=dataset_name,
                        version=dataset_version,
                    )
                ),
                evaluators=[AgentOptimizationEvaluator(name=evaluator_name)],
                evaluation_model=EvaluationModelConfiguration(model=eval_model),
            ),
            candidate_search_configuration=AgentOptimizationCandidateSearchConfiguration(
                max_candidates=2
            ),
            baseline_agent_configuration=baseline_configuration,
            agent_optimization_space=AgentOptimizationSpace(
                target_attributes=target_attributes
            ),
        ),
    )

    if existing_job_id:
        job_id = existing_job_id
    else:
        poller = project_client.agents.begin_create_optimization_job(
            job=job_request,
            polling=False,
        )
        job_id = poller.details.get("job_id")
        if not isinstance(job_id, str):
            raise RuntimeError(
                "The create operation did not return an optimization job ID."
            )

    print(f"Optimization job ID: {job_id}")

    terminal_statuses = {
        JobStatus.SUCCEEDED,
        JobStatus.FAILED,
        JobStatus.CANCELLED,
    }
    job = project_client.agents.get_optimization_job(job_id=job_id)
    print("Optimization job started, waiting for completion...")
    while job.status not in terminal_statuses:
        print(f"\tstatus=`{job.status}`")
        time.sleep(poll_interval_seconds)
        job = project_client.agents.get_optimization_job(job_id=job_id)
    print(f"\tstatus=`{job.status}`")

    for warning in job.warnings or []:
        print(f"[WARNING] {warning}")

    if job.status == JobStatus.FAILED:
        message = job.error.message if job.error else "<no error message>"
        raise RuntimeError(f"Optimization job `{job.id}` failed: {message}")
    if job.status == JobStatus.CANCELLED:
        raise RuntimeError(f"Optimization job `{job.id}` was cancelled.")
    if job.result is None:
        raise RuntimeError(f"Optimization job `{job.id}` completed without a result.")

    result = job.result
    summary = result.candidate_summary
    if summary:
        print(f"Baseline candidate: {summary.baseline_id}")
        print(f"Best candidate: {summary.best_id}")
        print(f"Completed optimized candidates: {summary.completed_candidate_count}")
        if summary.baseline_score is not None:
            print(f"Baseline score: {summary.baseline_score:.4f}")
        if summary.best_score is not None:
            print(f"Best score: {summary.best_score:.4f}")
    if result.termination_reason:
        print(f"Termination reason: {result.termination_reason}")

    for candidate in project_client.agents.list_optimization_candidates(
        job_id=job_id,
        expand=[AgentOptimizationCandidateExpand.MUTATIONS],
    ):
        details = [
            f"{candidate.name}: candidate_id={candidate.candidate_id}",
            f"status={candidate.status}",
        ]
        if candidate.evaluation:
            if candidate.evaluation.score is not None:
                details.append(f"score={candidate.evaluation.score:.4f}")
            if candidate.evaluation.avg_tokens is not None:
                details.append(f"avg_tokens={candidate.evaluation.avg_tokens:.0f}")
        print(", ".join(details))

Uruchom skrypt:

python optimize_hosted_agent.py

Identyfikator zadania optymalizacji jest drukowany natychmiast po przesłaniu; służy do monitorowania postępu w portalu Foundry.

Gdy zadanie zakończy się pomyślnie, skrypt wyświetli zwycięskiego kandydata i jego candidate_id.

W przeciwieństwie do azd ai agent optimize, przepływ w zestawie SDK języka Python nie tworzy lokalnego pliku .agent_configs/baseline/metadata.yaml. Metadane zadania optymalizacji pozostają dostępne w zwróconym obiekcie job oraz w odpowiedzi usługi Foundry, w tym: kandydat bazowy, najlepszy kandydat oraz lista ocenionych kandydatów.

3. Zastosuj zwycięskiego kandydata

Jeśli pracujesz również w lokalnym projekcie azd, używanym w opisanym powyżej przepływie CLI, zastosuj wybranego kandydata, używając elementu candidate_id zwróconego przez skrypt w Pythonie:

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

Jeśli chcesz tylko sprawdzić wynik, użyj ocen kandydatów i identyfikatorów oceny wypisanych przez skrypt, aby przejrzeć zwycięską konfigurację w Foundry przed jej wdrożeniem.

Ścieżka zestawu SDK języka C#

Wykonaj poniższe kroki, jeśli chcesz uruchomić optymalizator z .NET zamiast korzystać z przepływu pracy interfejsu wiersza polecenia dewelopera Azure opisanego wcześniej.

Ta ścieżka zakłada, że masz już następujące zasoby w istniejącym projekcie Foundry:

• Hostowany agent służący do optymalizacji.
• Zarejestrowany zbiór danych treningowych.
• Zarejestrowany moduł oceniający, taki jak wbudowany moduł oceniający builtin.task_adherence.

W przeciwieństwie do opisanego wcześniej przepływu Azure Developer CLI ścieżka zestawu SDK .NET nie tworzy szkieletu projektu ani nie generuje zestawu danych ani ewaluatorów dla Ciebie. Jeśli chcesz utworzyć te artefakty przy użyciu Azure Developer CLI, zainstaluj rozszerzenie azure.ai.evaluations za pomocą polecenia azd ext install azure.ai.evaluations (wymaga to azd 1.33.0 lub nowszej wersji), a następnie uruchom polecenie azd ai eval generate.

1. Ustawianie zmiennych środowiskowych

Utwórz aplikację konsolową, a następnie ustaw te wartości w powłoce przed jej uruchomieniem:

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

Użyj dokładnego punktu końcowego projektu na stronie Przegląd projektu Foundry.

Ustaw EVAL_MODEL i OPTIMIZATION_MODEL jako nazwy wdrożeń istniejących już w projekcie Foundry, a nie tylko nazwy rodzin modeli. Model optymalizacji musi być modelem rozumowania, który obsługuje optymalizator. Jeśli wybierzesz nieobsługiwane wdrożenie, usługa zwróci błąd, który zawiera listę dozwolonych modeli.

2. Uruchamianie zadania optymalizacji

Zastąp element Program.cs poniższym kodem.

Optymalizacja agenta wymaga nagłówka funkcji AgentsOptimization=V2Preview dla każdego żądania. Klasa FoundryFeaturesPolicy w tym przykładzie dodaje ten nagłówek do każdego żądania wysyłanego przez klienta:

using System.ClientModel.Primitives;
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;

#pragma warning disable AAIP001

// Adds the feature header that agent optimization requires.
public sealed class FoundryFeaturesPolicy(string features) : PipelinePolicy
{
    public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int index)
    {
        message.Request.Headers.Set("Foundry-Features", features);
        ProcessNext(message, pipeline, index);
    }

    public override ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int index)
    {
        message.Request.Headers.Set("Foundry-Features", features);
        return ProcessNextAsync(message, pipeline, index);
    }
}

public static class Program
{
    public static void Main()
    {
        var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")!;
        var agentName = Environment.GetEnvironmentVariable("FOUNDRY_AGENT_NAME")!;
        var datasetName = Environment.GetEnvironmentVariable("DATASET_NAME")!;
        var datasetVersion = Environment.GetEnvironmentVariable("DATASET_VERSION") ?? "1";
        var evaluatorName = Environment.GetEnvironmentVariable("EVALUATOR_NAME") ?? "builtin.task_adherence";
        var evalModel = Environment.GetEnvironmentVariable("EVAL_MODEL")!;
        var optimizationModel = Environment.GetEnvironmentVariable("OPTIMIZATION_MODEL")!;

        var options = new AIProjectClientOptions();
        options.AddPolicy(new FoundryFeaturesPolicy("AgentsOptimization=V2Preview"), PipelinePosition.PerCall);

        AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential(), options);
        AgentOptimizationJobs optimizationJobs = projectClient.AgentAdministrationClient.GetAgentOptimizationJobs();

        OptimizationJob job = new()
        {
            Inputs = new OptimizationJobInputs(
                new OptimizationAgentIdentifier(agentName),
                new OptimizationReferenceDatasetInput(datasetName) { Version = datasetVersion },
                new[] { new OptimizationEvaluatorRef(evaluatorName) })
            {
                Options = new OptimizationOptions
                {
                    MaxCandidates = 2,
                    EvalModel = evalModel,
                    OptimizationModel = optimizationModel,
                    // The optimizer needs at least one optimizable target, such as the
                    // baseline system prompt, the tool definitions, or skills.
                    OptimizationConfig =
                    {
                        ["system_prompt"] = BinaryData.FromObjectAsJson(
                            "You are a helpful assistant that answers user requests accurately and concisely."),
                    },
                },
            },
        };

        OptimizationJob created = optimizationJobs.Create(job);
        Console.WriteLine($"Optimization job started: {created.Id}");

        OptimizationJob current = created;
        while (current.Status != AgentsJobStatus.Succeeded
            && current.Status != AgentsJobStatus.Failed
            && current.Status != AgentsJobStatus.Cancelled)
        {
            Thread.Sleep(TimeSpan.FromSeconds(20));
            current = optimizationJobs.Get(created.Id);
            Console.WriteLine($"\tstatus=`{current.Status}`");
        }

        Console.WriteLine($"Final status: {current.Status}");

        if (current.Result is not null)
        {
            Console.WriteLine($"Baseline candidate: {current.Result.Baseline}");
            Console.WriteLine($"Best candidate: {current.Result.Best}");

            foreach (OptimizationCandidate candidate in current.Result.Candidates)
            {
                Console.WriteLine(
                    $"{candidate.Name}: candidate_id={candidate.CandidateId}, " +
                    $"avg_score={candidate.AvgScore:F4}, " +
                    $"avg_tokens={candidate.AvgTokens:F0}");
            }
        }
    }
}

Uruchom aplikację:

dotnet run

Gdy zadanie zakończy się pomyślnie, aplikacja wyświetli zwycięskiego kandydata oraz jego candidate_id:

Optimization job started: opt_<job-id>
        status=`in_progress`
        status=`succeeded`
Final status: succeeded
Baseline candidate: cand_opt_<job-id>_0000
Best candidate: cand_opt_<job-id>_0000
baseline: candidate_id=cand_opt_<job-id>_0000, avg_score=1.0000, avg_tokens=0

W przeciwieństwie do azd ai agent optimize, proces SDK platformy .NET nie tworzy lokalnego pliku .agent_configs/baseline/metadata.yaml. Metadane zadania optymalizacji są zachowywane w zwracanym obiekcie zadania oraz w odpowiedzi usługi Foundry, w tym kandydat bazowy, najlepszy kandydat i lista ocenionych kandydatów.

3. Zastosuj zwycięskiego kandydata

Jeśli pracujesz również na lokalnym projekcie azd używanym w przepływie CLI, zastosuj wybranego kandydata za pomocą wartości candidate_id zwróconej przez aplikację:

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

Jeśli chcesz tylko zweryfikować wynik, użyj ocen kandydatów i identyfikatorów oceny wyświetlanych przez aplikację, aby przejrzeć zwycięską konfigurację w Foundry przed jej promowaniem.

Uruchamianie optymalizacji w programie VS Code

Zestaw narzędzi Foundry Toolkit zawiera natywne środowisko optymalizacji agenta dla wdrożonych hostowanych agentów. Na placu zabaw agenta możesz rozpocząć przebieg optymalizacji, porównać kandydatów z punktem odniesienia, sprawdzić zmiany konfiguracji i wdrożyć najlepszego kandydata.

Krok 1. Wybieranie wdrożonego hostowanego agenta

1. Wybierz pozycję Foundry Toolkit na pasku działań.
2. W obszarze Moje zasoby wybierz pozycję Agenci.
3. Jeśli masz wdrożonego hostowanego agenta, wybierz go, aby otworzyć środowisko testowe hostowanego agenta.
4. Jeśli nie masz wdrożonego agenta hostowanego, ukończ ścieżkę programu VS Code w przewodniku Szybki start: wdrażanie pierwszego hostowanego agenta. Po zakończeniu wdrażania wróć do pozycji Agenci i wybierz nowego hostowanego agenta.

Krok 2. Uruchamianie przebiegu optymalizacji

1. Wybierz kartę Optymalizowanie .

1. Wybierz pozycję Nowa optymalizacja.

2. W Wybierz obszar roboczy wybierz obszar roboczy zawierający kod wybranego agenta hostowanego:

   • Wybierz Bieżący obszar roboczy, jeśli bieżący obszar roboczy zawiera kod agenta i plik azure.yaml.
   • Wybierz pozycję Przeglądaj..., aby otworzyć obszar roboczy zawierający kod agenta.

   Zestaw narzędzi Foundry używa plików obszaru roboczego do przygotowania optymalizacji i zastosowania kandydata do pasującej azure.ai.agent usługi.

1. Foundry Toolkit otwiera czat GitHub Copilot i wysyła żądanie do funkcji Agent Optimizer, uzupełnione o rodzaj i nazwę wybranego agenta oraz punkt końcowy projektu Foundry.

2. Odpowiedz na cztery pytania dotyczące optymalizacji w Copilot Chat:

   Dane wejściowe	Co należy podać
   Metryki oceny	Wprowadź metryki lub ewaluatory do użycia. Jeśli ich nie masz, wybierz, czy chcesz wygenerować je za pomocą azd ai eval generate (użyj --from prompt dla zbioru danych).
   Dataset	Wybierz zestaw danych optymalizacji. Jeśli go nie masz, wybierz, czy chcesz wygenerować go za pomocą azd ai eval generate (użyj --from prompt).
   Maksymalna liczba kandydatów	Wprowadź maksymalną liczbę kandydatów do wygenerowania, na przykład 2.
   Model optymalizacji	Wybierz istniejące wdrożenie z obsługiwanych modeli optymalizacji.

GitHub Copilot czeka na te dane wejściowe przed rozpoczęciem optymalizacji. Wygenerowane żądanie nakazuje Copilotowi korzystanie wyłącznie z przepływu pracy Optymalizatora agenta w Microsoft Foundry Skill oraz z poleceń narzędzia Azure Developer CLI. Nie korzysta z narzędzi McP firmy Foundry. Copilot:

• Sprawdza kod agenta w wybranym obszarze roboczym.
• Inicjuje środowisko AZD na podstawie istniejących wartości azure.yaml i .env, jeśli projekt jeszcze go nie posiada.
• Konfiguruje agenta pod kątem optymalizacji i wdraża zaktualizowanego agenta hostowanego.
• Uruchamia optymalizację po przejrzeniu i zatwierdzeniu proponowanych zmian plików i poleceń.

Po przesłaniu zadania przez aplikację Copilot wróć do karty Optymalizacja. Uruchomienie pojawi się w sekcji Uruchomienia optymalizacji. Tabela przedstawia identyfikator przebiegu, status, liczbę kandydatów, wynik bazowy, najlepszy wynik i czas utworzenia.

Krok 3. Porównanie i wdrażanie najlepszego kandydata

1. Gdy przebieg zakończy się pomyślnie, wybierz go w obszarze Przebiegi optymalizacji.
2. Porównaj wyniki bazowe i najlepsze. Przejrzyj szczegóły oceny dla każdego kandydata i wybierz pozycję Wyświetl zmiany , aby sprawdzić zmiany konfiguracji.
3. Jeśli najlepszy kandydat poprawi się w punkcie odniesienia, wybierz pozycję Wdróż najlepszego kandydata , aby zaktualizować bieżącego agenta. Aby wdrożyć go jako nowego agenta lub zmienić ustawienia wdrożenia, wybierz zamiast tego pozycję Wdrożenie niestandardowe.

Uruchamianie optymalizacji za pomocą umiejętności Microsoft Foundry

Użyj tej ścieżki w dowolnym hoście agenta kodującego, który obsługuje Microsoft Foundry Skill, takim jak GitHub Copilot w Visual Studio Code, Copilot CLI lub Claude Code. Funkcja ustala kontekst agenta na podstawie azure.yaml, ładuje jego przepływ pracy Agent Optimizer oraz utrzymuje kandydującą wersję aplikacji i wdrożenie na etapach weryfikacji.

Krok 1. Otwieranie obszaru roboczego agenta

Otwórz pusty folder na hoście agenta kodowania. Upewnij się, że umiejętność microsoft-foundry jest dostępna. Jeśli umiejętności nie są dostępne, wykonaj czynności opisane w temacie Use the Microsoft Foundry Skill in coding agents (Używanie umiejętności Microsoft Foundry w agentach kodowania).

Krok 2: Poproś funkcję o uruchomienie Agent Optimizer

Prześlij ten monit do agenta kodowania:

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. If the azd ai eval
commands aren't available, run azd ext install azure.ai.evaluations first (it
requires azd 1.33.0 or later). Generate the evaluation
dataset and evaluators by using azd ai eval generate, with --from prompt for the
dataset, and show me them. Set up the evaluation by using azd ai eval init and
azd ai eval create, and run a baseline evaluation by using azd ai eval run
start. Verify that the project has a supported optimization model deployment,
then run Agent Optimizer with two candidates by reusing that evaluation with
azd ai agent optimize --eval. Stop after reporting the operation ID,
portal URL, candidate IDs, and scores. Don't apply or deploy a candidate yet.

Agent kodowania może poprosić o wybranie subskrypcji, regionu, projektu Foundry, usługi agenta, modelu oceny lub modelu optymalizacji, gdy nie może rozpoznać tych wartości z obszaru roboczego. Przed zatwierdzeniem jakichkolwiek zmian lub poleceń przejrzyj wygenerowane pliki i zasoby generujące koszty.

Krok 3. Stosowanie i wdrażanie zatwierdzonego kandydata

Po przejrzeniu wyników optymalizacji prześlij następujący monit:

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 same azd ai eval evaluation with a
new run name. Compare it with the baseline run to confirm the improvement.

Umiejętność używa azd ai agent optimize apply --candidate <candidate-id>, aby można było lokalnie przejrzeć zoptymalizowaną konfigurację. System wdraża go dopiero po zatwierdzeniu, a następnie wywołuje zaktualizowanego hostowanego agenta i ponownie uruchamia ocenę.