Краткое руководство: оптимизировать размещённый агент

В этом кратком руководстве вы развернете пример агента для оптимизации, запустите оптимизатор агента, чтобы улучшить его инструкции, и развернете победивший вариант.

Основные понятия каждого шага и полного сквозного пути см. в рабочем процессе оптимизации.

Необходимые условия

Прежде чем начать, вам понадобится следующее:

Подписка Azure — Создайте ее бесплатно.

azd CLI (Azure CLI для разработчиков).
Azure CLI для проверки подлинности.
Расширение microsoft.foundry для azd (зависимости azure.ai.agents версии 0.1.40-preview или более поздней):
```
azd ext install microsoft.foundry
```
Если он уже установлен, обновите:
```
azd ext upgrade microsoft.foundry
```

Azure CLI для проверки подлинности.
Python 3.10 или более поздней версии.

Пакеты Python, используемые в этом пути:

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

Существующий проект Foundry, который уже содержит размещенный агент, зарегистрированный набор данных и средство оценки, которое вы хотите использовать для оптимизации.

Azure CLI для проверки подлинности.
.NET 10 SDK или более поздней версии.

Пакеты .NET, используемые в этом пути.

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

Существующий проект Foundry, который уже содержит размещенный агент, зарегистрированный набор данных и средство оценки, которое вы хотите использовать для оптимизации.

Visual Studio Code.
Microsoft Foundry Toolkit для Visual Studio Code версии 1.6.4 или более поздней, с выполненным входом в Azure. Foundry Toolkit устанавливает и обновляет навык Microsoft Foundry, используемый в этом рабочем процессе.
GitHub Copilot в Visual Studio Code с доступом к режиму агента. Foundry Toolkit отправляет запрос оптимизатора агента в GitHub Copilot после выбора рабочей области агента.
Azure CLI и интерфейс командной строки разработчика Azure (AZD) установлен и прошел проверку подлинности:
```
az login
azd auth login
```

Tip

Если у вас нет набора средств Foundry, установите его из Visual Studio Code Marketplace. Foundry Toolkit переносит ваши ресурсы Foundry, каталог моделей, развертывание размещённых агентов, песочницы и оптимизацию агентов в Visual Studio Code. Перезагрузите Visual Studio Code при появлении запроса, а затем войдите в Azure. Описание расширения см. в статье Работа с расширением Microsoft Foundry Toolkit для Visual Studio Code.

Узел агента программирования с установленным навыком Microsoft Foundry Skill.
Azure CLI и интерфейс командной строки разработчика Azure (AZD) установлен и прошел проверку подлинности:
```
az login
azd auth login
```
Расширение microsoft.foundry для AZD. Установите его перед запуском рабочего процесса:
```
azd ext install microsoft.foundry
```
Если он уже установлен, обновите его:
```
azd ext upgrade microsoft.foundry
```

Подписка Azure должна находиться в списке разрешений для оптимизатора агента. Обратитесь к своему представителю Microsoft, чтобы запросить доступ.

Шаг 1. Создание проекта

Инициализировать новый проект из примера шаблона оптимизации:

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 .

Этот шаблон импортирует образец службы поддержки клиентов для Optimization — размещённый агент на Python, готовый к оптимизации, который использует подход Bring Your Own и протокол Responses. Это агент службы поддержки клиентов в сфере потребительской электроники, который обрабатывает запросы по заказам, возвраты, гарантийные претензии, обращения по устранению неполадок, жалобы, запросы на рекомендации и эскалацию обращений. Намеренно минимальная базовая инструкция позволяет легко сравнить улучшения оптимизации инструкций и обнаружения навыков.

Пример вызовов load_config() для загрузки базовой или кандидатской конфигурации и включает в себя .agent_configs/baseline/eval.yaml, полные и быстрые наборы данных оценки, конфигурацию контейнера и манифест развертывания Foundry. Интерактивный процесс импортирует эти файлы и запрашивает у вас подписку Azure, регион и параметры развертывания модели.

Tip

Если у вас уже есть существующий проект агента, см. статью "Подготовка оптимизатора агента к добавлению поддержки оптимизации".

Если у вас уже есть проект Foundry, добавьте -p <project-resource-id>, чтобы указать существующие ресурсы в качестве целевых.

Чтобы оптимизировать уже развернутый агент, не запуская azd ai agent init и не создавая файлов azure.yaml и .azure, пропустите этот шаг создания проекта и следуйте указаниям в разделе Оптимизация существующего агента без файлов проекта AZD.

Шаг 2. Подготовка и развертывание

Проверка подлинности и подготовка ресурсов Azure:

az login
azd auth login
azd provision

Подготовка ресурсов занимает около двух минут; при этом создаются учетная запись Foundry, проект, Реестр контейнеров Azure и развертывания моделей.

Разверните агент:

azd deploy

Протестируйте развертывание:

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

Шаг 3: Сгенерируйте набор тестов для оценки и оптимизируйте

Создайте оценочный набор данных и средства оценки для вашего агента:

azd ai agent eval generate

На этом этапе создаются eval.yaml, тестовый набор данных и оценщики на основе инструкций вашего агента. Оптимизатор использует эти файлы для измерения улучшения.

Запустите оптимизатор:

azd ai agent optimize --max-candidates 2

Интерфейс командной строки предлагает выбрать модель оптимизации. Чтобы пропустить запрос, передайте его напрямую:

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

CLI обнаруживает ваш агент из azure.yaml и автоматически использует созданный eval.yaml. При использовании двух кандидатов оптимизация обычно завершается около 8 минут. Отображается ход выполнения в режиме реального времени:

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>

Используйте URL-адрес портала для мониторинга задания на портале Foundry.

Модель eval оценивает каждый ответ (любая модель завершения чата работает). Модель оптимизации (--optimize-model) генерирует улучшенные кандидаты и должна входить в поддерживаемый список (семейство GPT-5 или DeepSeek). Вы также можете задать optimization_model в разделе options: в eval.yaml, чтобы не передавать флаг каждый раз.

Шаг 4. Развертывание победителя

Звезда (*) в выходных данных указывает на лучшего кандидата. Примените оптимизированную конфигурацию локально, а затем разверните:

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

Команда apply загружает оптимизированную конфигурацию в .agent_configs/<candidate_id>/ и обновляет ваш azure.yaml, чтобы он использовал новые инструкции. Команда deploy разворачивает оптимизированного агента в рабочей среде с помощью CodeDeploy.

Запустите своего агента, чтобы проверить улучшение:

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

Вы также можете запустить оценку, чтобы подтвердить улучшение оценки:

azd ai agent eval run

Путь к пакету SDK Python

Выполните следующие действия, если вы хотите запустить оптимизатор из Python вместо рабочего процесса командной строки разработчика Azure, описанного ранее.

Этот путь предполагает, что у вас уже есть следующие ресурсы в существующем проекте Foundry:

Размещаемый агент для оптимизации.
Зарегистрированный набор данных для обучения.
Зарегистрированный оценщик.

В отличие от процесса Azure Developer CLI, описанного ранее, вариант с Python SDK не создает структуру проекта и не генерирует для вас eval.yaml, набор данных или оценщики. Если вы хотите, чтобы пример автоматически создавал эти ресурсы, используйте azd ai agent eval generate сначала.

1. Создание `.env` файла

Создайте рабочую .env папку и добавьте файл со следующими значениями:

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>

Запустите скрипт из той же рабочей папки, чтобы load_dotenv() загрузить .env файл автоматически. Если вы предпочитаете запустить его из другого каталога, сначала задайте те же значения в среде оболочки.

Используйте точную конечную точку проекта на странице обзора проекта Foundry. Скрипт Python немедленно отправляет свой первый запрос. Если FOUNDRY_PROJECT_ENDPOINT является лишь заполнителем или указывает на неверный проект, запуск завершается ошибкой ResourceNotFound: The project does not exist.

Укажите для EVAL_MODEL и OPTIMIZATION_MODEL имена развертываний, которые уже существуют в вашем проекте Foundry, а не только имена семейств моделей. Например, если развертывание вашего проекта называется gpt-4.1-mini или DeepSeek-V3.2, используйте это точное имя развертывания в .env.

2. Запуск задания оптимизации

Создайте файл с именем optimize_hosted_agent.py в той же папке, что .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))

Запустите скрипт:

python optimize_hosted_agent.py

Идентификатор задания оптимизации выводится сразу после отправки; используйте его для отслеживания хода выполнения на портале Foundry.

Когда задача завершается успешно, скрипт выводит кандидата-победителя и его candidate_id.

В отличие от azd ai agent optimize, в процессе Python SDK не создается локальный файл .agent_configs/baseline/metadata.yaml. Метаданные задания оптимизации остаются в возвращаемом job объекте и в ответе службы Foundry, включая базовый кандидат, лучший кандидат и список кандидатов с оценкой.

3. Примените выбранного кандидата

Если вы также работаете с локальным проектом azd, используемым в описанном выше процессе CLI, примените кандидата‑победителя, используя candidate_id, возвращённый Python-скриптом:

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

Если вам нужно проверить результат, используйте оценки кандидатов и идентификаторы оценки, напечатанные скриптом, чтобы просмотреть выигрышную конфигурацию в Foundry, прежде чем продвигать ее.

Путь пакета SDK для C#

Выполните следующие действия, если вы хотите запустить оптимизатор из .NET вместо использования рабочего процесса командной строки разработчика Azure, описанного ранее.

Этот путь предполагает, что у вас уже есть следующие ресурсы в существующем проекте Foundry:

Размещаемый агент для оптимизации.
Зарегистрированный набор данных для обучения.
Зарегистрированный вычислитель, например встроенный вычислитель builtin.task_adherence.

В отличие от сценария Azure Developer CLI, описанного ранее, подход с использованием пакета SDK .NET не создает структуру проекта и не генерирует для вас eval.yaml, набор данных или оценщики. Если вы хотите, чтобы пример автоматически создавал эти ресурсы, используйте azd ai agent eval generate сначала.

1. Задайте переменные среды

Создайте консольное приложение и задайте эти значения в оболочке перед запуском:

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>

Используйте точную конечную точку проекта на странице обзора проекта Foundry.

Укажите для EVAL_MODEL и OPTIMIZATION_MODEL имена развертываний, которые уже существуют в вашем проекте Foundry, а не только имена семейств моделей. Модель оптимизации должна быть моделью рассуждений, которую поддерживает оптимизатор. При выборе неподдерживаемого развертывания служба возвращает ошибку, которая перечисляет разрешенные модели.

2. Запуск задания оптимизации

Замените Program.cs на приведенный ниже код.

Для оптимизации агента требуется заголовок feature AgentsOptimization=V2Preview в каждом запросе. Класс FoundryFeaturesPolicy в этом примере добавляет этот заголовок к каждому запросу, который клиент отправляет:

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}");
            }
        }
    }
}

Запустите приложение:

dotnet run

Когда задача выполнена успешно, приложение выводит кандидата-победителя и его 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

В отличие от azd ai agent optimize, процесс SDK .NET не создает локальный файл .agent_configs/baseline/metadata.yaml. Метаданные задания оптимизации остаются в возвращаемом объекте задания и в ответе службы Foundry, в том числе базовый кандидат, лучший кандидат и список кандидатов с оценкой.

3. Примените выбранного кандидата

Если вы также работаете с локальным проектом azd, используемым в процессе CLI, примените победивший вариант с помощью candidate_id, возвращённого приложением:

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

Если вам нужно только проверить результат, используйте оценки кандидатов и идентификаторы оценивания, выведенные приложением, чтобы просмотреть победившую конфигурацию в Foundry перед ее продвижением.

Запуск оптимизации в VS Code

Инструментарий Foundry включает встроенные возможности оптимизации агентов для развернутых хостируемых агентов. На игровой площадке агента можно запустить запуск оптимизации, сравнить кандидатов с базовыми показателями, проверить изменения конфигурации и развернуть лучшего кандидата.

Шаг 1. Выбор развернутого размещенного агента

Выберите "Набор средств Foundry" на панели действий.
В разделе "Мои ресурсы" выберите "Агенты".
Если у вас развернут хостируемый агент, выберите его, чтобы открыть песочницу хостируемого агента.
Если у вас нет развернутого размещенного агента, выполните инструкции для VS Code из Краткое руководство: развертывание первого размещенного агента. После завершения развертывания вернитесь к агентам и выберите новый размещенный агент.

Шаг 2: Запустите процесс оптимизации

Выберите вкладку "Оптимизация ".

Выберите "Новая оптимизация".
В разделе "Выбор рабочей области" выберите рабочую область, содержащую код выбранного размещенного агента:
- Выберите текущую рабочую область , если текущая рабочая область содержит код агента и его azure.yaml файл.
- Нажмите кнопку "Обзор", чтобы открыть рабочую область, содержащую код агента.
Foundry Toolkit использует файлы рабочей области для подготовки оптимизации и применения кандидата к соответствующей службе azure.ai.agent.

Foundry Toolkit открывает GitHub Copilot Chat и отправляет запрос оптимизатора агента, заполненный типом, именем и конечной точкой проекта Foundry выбранного агента.

Ответьте на четыре вопроса оптимизации в Copilot Chat:

Input	Что предоставлять
Метрики оценки	Введите метрики или средства оценки, которые нужно использовать. Если у вас их нет, выберите, следует ли запускать `azd ai agent eval generate` или использовать встроенные значения оптимизатора по умолчанию.
Dataset	Выберите набор данных оптимизации. Если у вас нет одного, выберите, следует ли запускать `azd ai agent eval generate` или использовать встроенные значения оптимизатора по умолчанию.
Максимальное число кандидатов	Введите максимальное число кандидатов, которые нужно создать, например `2`.
Модель оптимизации	Выберите существующее развертывание из поддерживаемых моделей оптимизации.

GitHub Copilot ожидает этих входных данных перед началом оптимизации. Созданный запрос направляет Copilot использовать рабочий процесс оптимизатора агента Microsoft Foundry Skill и Azure команды командной строки разработчика. Он не использует средства Foundry MCP. Copilot:

Проверяет код агента в выбранной рабочей области.
Инициализирует среду AZD на основе существующих значений azure.yaml и .env, если у проекта ее еще нет.
Настраивает агент для оптимизации и развертывает обновленный размещенный агент.
Создает eval.yaml в папке службы агента.
Запускает оптимизацию после проверки и утверждения предлагаемых изменений и команд файла.

После того как Copilot отправит задание, вернитесь на вкладку Оптимизация. Запуск появится в разделе Запуски оптимизации. В таблице показаны его идентификатор запуска, состояние, количество кандидатов, базовая оценка, лучшая оценка и время создания.

Шаг 3. Сравнение и развертывание лучшего кандидата

После успешного завершения запуска выберите его в разделе Запуски оптимизации.
Сравните базовые и лучшие оценки. Просмотрите сведения о оценке для каждого кандидата и выберите "Просмотреть изменения ", чтобы проверить изменения конфигурации.
Если лучший кандидат превосходит базовый уровень, выберите Развернуть лучшего кандидата, чтобы обновить текущего агента. Чтобы развернуть его в качестве нового агента или изменить параметры развертывания, выберите "Настраиваемое развертывание ".

Note

Если каждый кандидат оценивается ниже базового уровня, не развертывайте кандидата. Сохраните текущий агент и проверьте параметры набора данных или оптимизации перед повторной запуском оптимизатора.

Запустите оптимизацию с помощью навыка Microsoft Foundry

Используйте этот путь в любой среде для агентов программирования, которая поддерживает Microsoft Foundry Skill, например, GitHub Copilot в Visual Studio Code, Copilot CLI или Claude Code. Навык определяет контекст агента из azure.yaml, загружает рабочий процесс Agent Optimizer и не допускает приложение-кандидат и развертывание до прохождения этапов проверки.

Шаг 1. Открытие рабочей области агента

Откройте пустую папку в узле агента программирования. Убедитесь, что навык microsoft-foundry доступен. Если навык недоступен, следуйте инструкциям в статье Использование навыка Microsoft Foundry в агентах для программирования.

Шаг 2. Запрос навыка запуска оптимизатора агента

Отправьте этот запрос агенту программирования:

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.

Агент для написания кода может попросить вас выбрать подписку, регион, проект Foundry, службу агента, модель оценки или модель оптимизации, если он не может определить эти значения по рабочей области. Просмотрите сгенерированные файлы и ресурсы, влекущие затраты, прежде чем одобрять любые изменения или команды.

Шаг 3. Применение и развертывание утвержденного кандидата

После просмотра результатов оптимизации отправьте следующий запрос:

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.

Навык использует azd ai agent optimize apply --candidate <candidate-id>, чтобы вы могли локально проверить оптимизированную конфигурацию. Развертывание выполняется только после вашего одобрения, после чего система запускает и оценивает обновлённого размещённого агента.

Очистите ресурсы

Если рабочий процесс создал ресурсы с помощью проекта AZD, удалите подготовленные ресурсы после завершения эксперимента:

azd down --force --purge

Tip

Почему --purge? Для учетных записей Foundry по умолчанию используется мягкое удаление. Без --purge имя ресурса остается зарезервированным в течение 48 часов, и повторное развертывание с тем же именем не удается.

Troubleshooting

Проблема.	Причина	Исправление
Команда `azd ai agent optimize` не найдена	Расширение слишком старое	Выполните команду `azd ext upgrade microsoft.foundry` , чтобы получить версию 0.1.40-preview или более позднюю версию.
`optimization_model is required`	Выполнение в неинтерактивном режиме без настройки модели	Добавьте `--optimize-model gpt-5` в команду или установите `optimization_model: gpt-5` в `options:`разделе `eval.yaml` . В интерактивном режиме интерфейс командной строки запрашивает выбор модели.
Python-скрипт завершается с ошибкой из-за отсутствующей переменной `KeyError: 'DATASET_NAME'` или другой переменной	Скрипт не загружал `.env` файл или переменная отсутствует	Запустите скрипт из той же папки, что и `.env`, или экспортируйте необходимые значения в оболочке командной строки перед запуском `python optimize_hosted_agent.py`.
Сценарий Python завершается сбоем `ResourceNotFound: The project does not exist`	`FOUNDRY_PROJECT_ENDPOINT` Не указывает на существующий проект Foundry	Скопируйте конечную точку проекта со страницы Overview проекта Foundry и обновите `FOUNDRY_PROJECT_ENDPOINT` в `.env`.
Сценарий Python завершается сбоем `Optimization model deployment '<name>' not found`	`OPTIMIZATION_MODEL` не является именем модели, развернутой в вашем проекте Foundry	Используйте точное имя развертывания из Build>Deployments, например существующее семейство `gpt-5` или развертывание DeepSeek в вашем проекте.
Запрос задания завершается сбоем `evaluators is required and cannot be empty`	Заголовок `Foundry-Features` отсутствует в запросе	Добавьте заголовок `AgentsOptimization=V2Preview`, как показывает класс `FoundryFeaturesPolicy` в коде C#.
Задание завершается сбоем `No optimizable element found for the hosted agent`	Запрос не включает оптимизируемый целевой объект	Укажите по крайней мере одну `system_prompt`цель, например `optimization_config`базовый уровень, определения инструментов или навыки.
Задание завершается сбоем `AllEvaluatorsFailedError`	Модуль оценки настроен неправильно, поэтому ни одна строка не получает оценку.	Откройте ссылку на выполнение оценки в сообщении об ошибке и убедитесь, что оценщик выставляет оценки ответам вашего агента. Начните со встроенного оценщика, такого как `builtin.task_adherence`.
Раздел "Оптимизация " не отображается для размещенного агента	Foundry Toolkit старше версии 1.6.4, или выбранный агент не является развернутым размещенным агентом.	Обновите набор средств Foundry, перезагрузите Visual Studio Code и повторно откройте развернутый агент на вкладке "Агенты".
GitHub Copilot Chat не открывается после выбора рабочей области	GitHub Copilot не установлен, недоступен для учетной записи или отключен режим агента.	Настройте GitHub Copilot в Visual Studio Code, включите режим агента и снова нажмите кнопку "Создать оптимизацию".
Foundry Toolkit не может применить наиболее подходящий вариант к текущей рабочей области	Рабочая область не содержит службы `azure.yaml`, имя которой совпадает с именем развёрнутого размещённого агента	Откройте рабочую область, содержащую код выбранного агента и службу сопоставления `azure.ai.agent` , а затем повторите попытку.
Агент программирования не может найти размещенный агент	Неправильная папка открыта или `azure.yaml` не определяет `azure.ai.agent` службу.	Откройте папку проекта AZD, в которой содержится `azure.yaml`, затем попросите агента для написания кода снова устранить проблему со службой hosted-agent.
Агент программирования останавливается перед применением или развертыванием кандидата	Навык Agent Optimizer необходимо проверить перед изменением исходного кода и развертыванием	Просмотрите оценки кандидата и локальный дифф, а затем явным образом утвердите шаг применения или развертывания.
Оценка оптимизации составляет 0 или очень низкая	Оценка содержит много строк с ошибками	Откройте ссылку Eval в результатах. Исправьте ошибки генерации ответов или оценщика, затем повторите.
`azd provision` сбой с ошибкой квоты	В подписке недостаточно емкости	Попробуйте другой регион или запросить увеличение квоты.

Что вы узнали

В этом кратком руководстве вы:

Развернули пример агента оптимизации, используя шаблон службы поддержки.
Средство оптимизации агента было запущено с помощью Azure Developer CLI, пакета SDK для Python, пакета SDK .NET, Visual Studio Code или Microsoft Foundry Skill.
Развернули победившего кандидата и подтвердили улучшение.

Дальнейшие действия

Обратная связь

Были ли сведения на этой странице полезными?

Последнее обновление: 2026-09-11

Краткое руководство: оптимизировать размещённый агент

Необходимые условия

Шаг 1. Создание проекта

Шаг 2. Подготовка и развертывание

Шаг 3: Сгенерируйте набор тестов для оценки и оптимизируйте

Шаг 4. Развертывание победителя

Путь к пакету SDK Python

1. Создание .env файла

2. Запуск задания оптимизации

3. Примените выбранного кандидата

Путь пакета SDK для C#

1. Задайте переменные среды

2. Запуск задания оптимизации

3. Примените выбранного кандидата

Запуск оптимизации в VS Code

Шаг 1. Выбор развернутого размещенного агента

Шаг 2: Запустите процесс оптимизации

Шаг 3. Сравнение и развертывание лучшего кандидата

Запустите оптимизацию с помощью навыка Microsoft Foundry

Шаг 1. Открытие рабочей области агента

Шаг 2. Запрос навыка запуска оптимизатора агента

Шаг 3. Применение и развертывание утвержденного кандидата

Очистите ресурсы

Troubleshooting

Что вы узнали

Дальнейшие действия

Обратная связь

Дополнительные ресурсы

1. Создание `.env` файла