Important
에이전트 최적화 프로그램은 현재 미리 보기로 제공됩니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며 프로덕션 워크로드에는 권장되지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 Microsoft Azure Preview에 대한 추가 사용 약관을 참조하세요.
이 빠른 시작에서는 최적화 샘플 에이전트를 배포하고, 에이전트 최적화 관리자를 실행하여 지침을 개선하고, 성공한 후보를 배포합니다.
각 단계의 개념과 전체 엔드 투 엔드 경로는 최적화 워크플로를 참조하세요.
사전 요구 사항
이 작업을 시작하려면 다음이 필요합니다.
- Azure 구독--무료로 하나 만들기.
인증에 대한 Azure CLI.
Python 3.10 이상.
이 경로에 사용되는 Python 패키지:
pip install "azure-ai-projects>=2.5.0" azure-ai-agentserver-optimization azure-identity python-dotenv최적화에 사용할 호스트된 에이전트, 등록된 데이터 세트 및 계산기가 이미 포함된 기존 Foundry 프로젝트입니다.
인증에 대한 Azure CLI.
이 경로에 사용되는 .NET 패키지입니다.
dotnet add package Azure.AI.Projects --prerelease dotnet add package Azure.Identity최적화에 사용할 호스트된 에이전트, 등록된 데이터 세트 및 계산기가 이미 포함된 기존 Foundry 프로젝트입니다.
Visual Studio Code용 Microsoft Foundry Toolkit 버전 1.6.4 이상, Azure에 로그인. Foundry 도구 키트는 이 워크플로에서 사용하는 Microsoft Foundry Skill을 설치하고 업데이트합니다.
에이전트 모드에 액세스할 수 있는 Visual Studio Code의 GitHub Copilot Foundry 도구 키트는 에이전트 작업 영역을 선택한 후 에이전트 최적화 프로그램 요청을 GitHub Copilot 보냅니다.
AZD(Azure CLI 및 Azure 개발자 CLI)가 설치 및 인증되었습니다.
az login azd auth login
Tip
Foundry 도구 키트가 없는 경우 Visual Studio Code Marketplace에서 설치합니다. Foundry Toolkit은 Foundry 리소스, 모델 카탈로그, 호스팅된 에이전트 배포와 플레이그라운드, 그리고 에이전트 최적화를 Visual Studio Code로 가져옵니다. 메시지가 표시되면 Visual Studio Code 다시 로드한 다음 Azure 로그인합니다. 확장 기능 둘러보기에 대해서는 Visual Studio Code용 Microsoft Foundry 도구 키트 확장으로 작업을 참조하세요.
Microsoft Foundry Skill이 설치된 코딩 에이전트 호스트입니다.
AZD(Azure CLI 및 Azure 개발자 CLI)가 설치 및 인증되었습니다.
az login azd auth loginAZD용
microsoft.foundry확장입니다. 워크플로를 시작하기 전에 설치합니다.azd ext install microsoft.foundry이미 설치되어 있는 경우 업그레이드합니다.
azd ext upgrade microsoft.foundry
- Azure 구독은 에이전트 최적화 프로그램의 허용 목록에 있어야 합니다. 액세스를 요청하려면 Microsoft 담당자에게 문의하세요.
메모
에이전트 최적화 프로그램은 현재 미리 보기로 제공됩니다.
1단계: 프로젝트 만들기
최적화 샘플 템플릿에서 새 프로젝트를 초기화합니다.
mkdir my-agent && cd my-agent
azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/responses/optimization-customer-support/azure.yaml .
이 템플릿은 사용자 제공 방식과 Responses 프로토콜을 사용하는, 최적화에 바로 사용할 수 있는 Python 호스팅 에이전트인 최적화 고객 지원 샘플을 가져옵니다. 주문 문의, 반품, 보증 청구, 문제 해결, 불만 사항, 권장 사항 및 에스컬레이션을 처리하는 소비자 전자 기술 지원 에이전트를 나타냅니다. 의도적으로 최소한의 기준 명령을 사용하면 명령 최적화 및 기술 검색의 개선 사항을 쉽게 비교할 수 있습니다.
샘플은 베이스라인 또는 후보 구성을 로드하기 위해 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
프로비전하는 데 약 2분이 걸리며 Foundry 계정, 프로젝트, Azure Container Registry 및 모델 배포를 만듭니다.
에이전트를 배포합니다.
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
CLI는 최적화 모델을 선택하라는 메시지를 표시합니다. 프롬프트를 건너뛰려면 이를 직접 전달하세요.
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 명령은 코드 배포를 사용하여 최적화된 에이전트를 라이브로 푸시합니다.
에이전트를 호출하여 개선 사항을 확인합니다.
azd ai agent invoke "What is your return policy?"
평가를 실행하여 점수 향상을 확인할 수도 있습니다.
azd ai agent eval run
Python SDK 경로
앞에서 설명한 Azure Developer CLI 워크플로 대신 Python 최적화 도구를 실행하려면 다음 단계를 사용합니다.
이 경로는 기존 Foundry 프로젝트에 이미 다음 리소스가 있다고 가정합니다.
- 최적화를 위한 호스팅 에이전트
- 등록된 학습 데이터 세트입니다.
- 등록된 평가자
앞에서 설명한 Azure 개발자 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라는 이름의 파일을 만듭니다:
import os
import time
from azure.ai.agentserver.optimization import load_config
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
OptimizedAgentIdentifier,
AgentOptimizationEvaluatorRef,
AgentOptimizationJob,
AgentOptimizationJobInputs,
AgentOptimizationOptions,
AgentOptimizationReferenceDatasetInput,
)
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"))
optimization_config = load_config() # Reads agent optimization config from .agent_configs/baseline/metadata.yaml
with (
DefaultAzureCredential() as credential,
AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
job = AgentOptimizationJob(
inputs=AgentOptimizationJobInputs(
agent=OptimizedAgentIdentifier(agent_name=agent_name),
train_dataset=AgentOptimizationReferenceDatasetInput(
name=dataset_name,
version=dataset_version,
),
evaluators=[AgentOptimizationEvaluatorRef(name=evaluator_name)],
options=AgentOptimizationOptions(
max_candidates=2,
eval_model=eval_model,
optimization_model=optimization_model,
optimization_config={
"system_prompt": optimization_config.instructions,
**({"tools": optimization_config.tool_definitions} if optimization_config.tool_definitions else {}),
**({"skills": optimization_config.skills} if optimization_config.has_skills else {}),
}
),
)
)
poller = project_client.beta.agents.begin_create_optimization_job(job=job)
print(f"Optimization job ID: {poller.details.job_id}")
print(f"Optimization job started, waiting for completion...")
while not poller.done():
print(f"\tstatus=`{poller.status()}`")
time.sleep(poll_interval_seconds)
result = poller.result()
if result:
print(f"Baseline candidate: {result.baseline}")
print(f"Best candidate: {result.best}")
for candidate in result.candidates or []:
print(
f"{candidate.name}: candidate_id={candidate.candidate_id}, "
f"avg_score={candidate.avg_score:.4f}, "
f"avg_tokens={candidate.avg_tokens:.0f}"
)
스크립트를 실행합니다.
python optimize_hosted_agent.py
최적화 작업 ID는 제출 직후에 인쇄됩니다. 이를 사용하여 Foundry 포털에서 진행률을 모니터링합니다.
작업이 성공하면 스크립트는 성공한 후보와 해당 candidate_id후보를 출력합니다.
azd ai agent optimize와 달리 Python SDK 흐름은 로컬 .agent_configs/baseline/metadata.yaml 파일을 생성하지 않습니다. 최적화 작업 메타데이터는 반환된 job 개체 및 Foundry 서비스 응답에 유지됩니다(기준 후보, 최적 후보 및 점수가 매김된 후보 목록 포함).
3. 선정된 후보 적용
위의 CLI 흐름에서 사용한 로컬 azd 프로젝트에서도 작업 중이라면, Python 스크립트가 반환한 candidate_id을 사용하여 선정된 후보를 적용하세요.
azd ai agent optimize apply --candidate <candidate-id>
azd deploy
결과만 확인해야 하는 경우, 스크립트에서 출력되는 후보 점수와 평가 식별자를 사용하여 파운드리에서 최종 선정된 구성을 검토한 후 승격하세요.
C# SDK 경로
앞에서 설명한 Azure 개발자 CLI 워크플로를 사용하는 대신 .NET 최적화 도구를 실행하려면 다음 단계를 사용합니다.
이 경로는 기존 Foundry 프로젝트에 이미 다음 리소스가 있다고 가정합니다.
- 최적화를 위한 호스팅 에이전트
- 등록된 학습 데이터 세트입니다.
- 기본 제공
builtin.task_adherence평가기와 같은 등록된 평가기.
앞에서 설명한 Azure Developer CLI 흐름과 달리, .NET SDK 방식은 프로젝트를 스캐폴딩하거나 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를 다음 코드로 바꿉니다.
에이전트 최적화는 미리 보기 기능이므로 요청에 기능 헤더가 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 preview 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.NET SDK 흐름은 로컬 .agent_configs/baseline/metadata.yaml 파일을 만들지 않습니다. 최적화 작업 메타데이터는 반환된 작업 개체와 초기 계획 후보, 최적 후보 및 점수가 매김된 후보 목록을 포함하여 Foundry 서비스 응답에 유지됩니다.
3. 선정된 후보 적용
CLI 흐름에서 사용하는 로컬 azd 프로젝트로도 작업 중이라면, 앱에서 반환된 candidate_id를 사용해 선정된 후보를 적용하세요.
azd ai agent optimize apply --candidate <candidate-id>
azd deploy
결과만 확인하면 되는 경우, 승격하기 전에 앱에 표시된 후보 점수와 평가 식별자를 사용하여 Foundry에서 선정된 구성을 검토하세요.
VS Code에서 최적화 실행
Foundry 도구 키트에는 배포된 호스트된 에이전트에 대한 네이티브 에이전트 최적화 환경이 포함되어 있습니다. 에이전트 플레이그라운드에서 최적화 실행을 시작하고, 후보와 기준을 비교하고, 구성 변경 내용을 검사하고, 최상의 후보를 배포할 수 있습니다.
1단계: 배포된 호스트된 에이전트 선택
- 작업 표시줄에서 Foundry 도구 키트 를 선택합니다.
- 내 리소스에서 에이전트를 선택합니다.
- 호스트된 에이전트가 배포된 경우 호스트된 에이전트 플레이그라운드를 열려면 선택합니다.
- 배포된 호스트 에이전트가 없는 경우 빠른 시작: 첫 번째 호스팅 에이전트 배포에서 VS Code 경로를 완료합니다. 배포가 완료되면 에이전트 로 돌아가서 호스트된 새 에이전트를 선택합니다.
2단계: 최적화 실행 시작
- 미리 보기로 표시된 최적화 탭을 선택합니다.
새 최적화를 선택합니다.
작업 영역 선택에서 선택한 호스트된 에이전트의 코드가 포함된 작업 영역을 선택합니다.
-
현재 작업 영역에 에이전트 코드와 해당
azure.yaml파일이 포함된 경우 현재 작업 영역을 선택합니다. - 찾아보기를 선택하여 에이전트 코드가 포함된 작업 영역을 엽니다.
Foundry 도구 키트는 작업 영역 파일을 사용하여 최적화를 준비하고 일치하는
azure.ai.agent서비스에 후보를 적용합니다.-
현재 작업 영역에 에이전트 코드와 해당
Foundry 도구 키트는 GitHub Copilot Chat 열고 선택한 에이전트의 종류, 이름 및 Foundry 프로젝트 엔드포인트로 채워진 에이전트 최적화 프로그램 요청을 보냅니다.
Copilot Chat 네 가지 최적화 질문에 답변합니다.
입력 제공할 내용 평가 메트릭 사용할 메트릭 또는 계산기를 입력합니다. 해당 항목이 없는 경우 azd ai agent eval generate을(를) 실행할지, 아니면 최적화 프로그램의 내장 기본값을 사용할지 선택합니다.Dataset 최적화 데이터 세트를 선택합니다. 하나가 없다면 azd ai agent eval generate을(를) 실행할지, 아니면 최적화 프로그램의 내장 기본값을 사용할지 선택하세요.최대 후보 수 생성할 최대 후보 수를 입력합니다(예: 2.).최적화 모델 지원되는 최적화 모델에서 기존 배포를 선택합니다.
GitHub Copilot 최적화를 시작하기 전에 이러한 입력을 기다립니다. 생성된 요청은 Copilot Microsoft Foundry Skill의 에이전트 최적화 프로그램 워크플로 및 Azure 개발자 CLI 명령을 단독으로 사용하도록 지시합니다. Foundry MCP 도구를 사용하지 않습니다. Copilot:
- 선택한 작업 영역에서 에이전트 코드를 검사합니다.
- 프로젝트에 아직 AZD 환경이 없는 경우 기존
azure.yaml및.env값을 사용해 AZD 환경을 초기화합니다. - 최적화를 위해 에이전트를 연결하고 업데이트된 호스트된 에이전트를 배포합니다.
- 에이전트 서비스 폴더에
eval.yaml를 생성합니다. - 제안된 파일 변경 내용 및 명령을 검토하고 승인한 후 최적화를 시작합니다.
Copilot이 작업을 제출한 후 최적화 탭으로 돌아가세요. 실행이 최적화 실행 아래에 표시됩니다. 테이블은 실행 ID, 상태, 후보 수, 기준 점수, 최고 점수 및 생성 시간을 보여 줍니다.
3단계: 최상의 후보 비교 및 배포
- 실행이 성공하면 최적화 실행에서 선택합니다.
- 기준선 점수와 최고 점수를 비교합니다. 각 후보에 대한 점수 세부 정보를 검토하고 변경 내용 보기를 선택하여 구성 변경 내용을 검사합니다.
- 가장 적합한 후보가 기준선에서 개선되면 가장 적합한 후보 배포 를 선택하여 현재 에이전트를 업데이트합니다. 새 에이전트로 배포하거나 배포 설정을 변경하려면 사용자 지정 배포 를 대신 선택합니다.
메모
모든 후보가 기준선보다 낮은 점수를 받는 경우 후보를 배포하지 마세요. 최적화 관리자를 다시 실행하기 전에 현재 에이전트를 유지하고 데이터 세트 또는 최적화 설정을 수정합니다.
Microsoft Foundry 기술로 최적화 실행
Visual Studio Code, Copilot CLI 또는 Claude Code의 GitHub Copilot 같은 Microsoft Foundry 기술을 지원하는 코딩 에이전트 호스트에서 이 경로를 사용합니다. 이 스킬은 azure.yaml로부터 에이전트 컨텍스트를 확인하고, Agent Optimizer 워크플로를 로드하며, 후보 애플리케이션과 배포가 검토 게이트를 거치도록 유지합니다.
1단계: 에이전트 작업 영역 열기
코딩 에이전트 호스트에서 빈 폴더를 엽니다.
microsoft-foundry 스킬을 사용할 수 있는지 확인합니다. 기술을 사용할 수 없는 경우 코딩 에이전트에서 Microsoft Foundry Skill을 사용합니다.
2단계: 스킬에 Agent Optimizer를 실행하도록 요청합니다
이 프롬프트를 코딩 에이전트에 제출합니다.
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을 설정합니다. 대화형 모드에서 CLI는 모델 선택을 묻는 메시지를 표시합니다. |
Python 스크립트가 KeyError: 'DATASET_NAME' 또는 다른 누락된 변수로 인해 실패함 |
스크립트가 사용자의 .env 파일을 로드하지 못했거나 변수가 누락되었습니다. |
동일한 폴더 .env에서 스크립트를 실행하거나 실행 python optimize_hosted_agent.py하기 전에 셸에서 필요한 값을 내보냅니다. |
Python 스크립트가 실패함ResourceNotFound: The project does not exist |
FOUNDRY_PROJECT_ENDPOINT 기존 Foundry 프로젝트를 가리키지 않음 |
Foundry 프로젝트의 개요 페이지에서 프로젝트 엔드포인트를 복사한 다음 FOUNDRY_PROJECT_ENDPOINT에서 .env을 업데이트합니다. |
Python 스크립트가 실패함Optimization model deployment '<name>' not found |
OPTIMIZATION_MODEL 가 Foundry 프로젝트에 배포된 모델의 이름이 아닌 경우 |
빌드>배포에서 프로젝트의 기존 gpt-5 제품군 또는 DeepSeek 배포와 같은 정확한 배포 이름을 사용하세요. |
작업 요청이 실패함 evaluators is required and cannot be empty |
Foundry-Features 요청에서 미리 보기 헤더가 없습니다. |
C# 경로의 AgentsOptimization=V2Preview 클래스와 같이 FoundryFeaturesPolicy 헤더를 추가합니다. |
작업이 실패함 No optimizable element found for the hosted agent |
요청에 최적화 가능한 대상이 포함되어 있지 않습니다. | 기준system_prompt, 도구 정의 또는 기술과 같은 하나 이상의 대상optimization_config을 제공합니다. |
작업이 실패함 AllEvaluatorsFailedError |
계산기가 잘못 구성되었으므로 모든 행의 점수 매기기가 실패합니다. | 오류에서 평가 실행 링크를 열고 평가자가 에이전트의 응답에 점수를 매길지 확인합니다.
builtin.task_adherence와 같은 기본 제공 평가기로 시작합니다. |
| 호스트된 에이전트에 대해 최적화 섹션이 표시되지 않음 | Foundry 도구 키트가 버전 1.6.4보다 오래되었거나 선택한 에이전트가 배포된 호스트된 에이전트가 아닙니다. | Foundry 도구 키트를 업데이트하고, Visual Studio Code 다시 로드하고, 에이전트 탭에서 배포된 에이전트를 다시 엽니다. |
| 작업 영역을 선택한 후 GitHub Copilot Chat 열리지 않음 | GitHub Copilot 설치되지 않았거나, 계정에 사용할 수 없거나, 에이전트 모드를 사용할 수 없습니다. | Visual Studio Code GitHub Copilot 설정하고 에이전트 모드를 사용하도록 설정한 다음 새 최적화를 다시 선택합니다. |
| Foundry 도구 키트는 현재 작업 영역에 가장 적합한 후보를 적용할 수 없습니다. | 작업 영역에는 배포된 호스트된 에이전트와 이름이 일치하는 서비스가 포함되어 azure.yaml 있지 않습니다. |
선택한 에이전트의 코드와 일치하는 azure.ai.agent 서비스가 포함된 작업 영역을 연 다음 다시 시도합니다. |
| 코딩 에이전트가 호스트된 에이전트를 찾을 수 없습니다. | 잘못된 폴더가 열려 있거나 azure.yaml 서비스를 정의 azure.ai.agent 하지 않음 |
포함된 AZD 프로젝트 폴더를 연 다음 코딩 에이전트에 호스트 에이전트 서비스를 다시 확인하도록 요청합니다 azure.yaml. |
| 코딩 에이전트가 후보 버전을 적용하거나 배포하기 전에 중지됨 | 에이전트 최적화 프로그램 기술에는 원본 변경 및 배포 전에 검토가 필요합니다. | 후보 점수 및 로컬 차이 검토한 다음 적용 또는 배포 단계를 명시적으로 승인합니다. |
| 최적화 점수가 0 또는 매우 낮음 | 평가에 많은 오류 행이 있습니다. | 결과에서 Eval 링크를 엽니다. 응답 생성 또는 계산기 오류를 수정한 다음 다시 실행합니다. |
azd provision 할당량 오류와 함께 실패 |
구독에 용량이 부족합니다. | 다른 지역을 시도하거나 할당량 증가를 요청합니다. |
배운 내용
이 빠른 시작에서 당신은 다음을 수행합니다.
- 고객 지원 템플릿을 사용하여 최적화 샘플 에이전트를 배포했습니다.
- Azure Developer CLI, Python SDK, .NET SDK, Visual Studio Code 또는 Microsoft Foundry Skill을 사용하여 에이전트 최적화 도구를 실행했습니다.
- 우승 후보를 배포하고 개선 사항을 확인했습니다.