Visual Studio Code 확장용 Microsoft Foundry 도구 키트에서 호스트된 에이전트 워크플로 만들기

• Python 3.13 이상.

• .NET 10 SDK 이상

1. 가상 환경을 만듭니다.

    python -m venv .venv
   

2. 가상 환경을 활성화합니다.

   # PowerShell
   ./.venv/Scripts/Activate.ps1
   
   # Windows cmd
   .venv\Scripts\activate.bat
   
   # Unix/MacOS
   source .venv/bin/activate
   

3. 필요한 패키지를 설치합니다.

   pip install -r requirements.txt
   

1. 프로젝트 디렉터리로 이동하여 이 명령을 실행하여 필요한 NuGet 패키지를 가져옵니다.

   dotnet restore
   

샘플 워크플로 프로젝트는 필요한 환경 변수를 사용하여 .env 파일을 만듭니다. Foundry 자격 증명으로 .env 파일을 만들거나 업데이트합니다.

FOUNDRY_PROJECT_ENDPOINT=https://<your-resource-name>.services.ai.azure.com/api/projects/<your-project-name>

AZURE_AI_MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>

호스팅된 에이전트를 인증하세요

호스트된 에이전트 샘플은 DefaultAzureCredential을 사용하여 인증합니다. 지원되는 원본 중 하나를 통해 자격 증명을 제공하도록 개발 환경을 구성합니다. 예를 들면 다음과 같습니다.

• Azure CLI(az login)
• Visual Studio Code 계정 로그인
• Visual Studio 계정 로그인
• 서비스 주체에 대한 환경 변수(AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

샘플을 실행하기 전에 Azure CLI az account show 또는 az account get-access-token 명령을 실행하여 로컬로 인증을 확인합니다.

호스트된 에이전트는 대화형 모드 또는 컨테이너 모드에서 실행할 수 있습니다.

에이전트 검사기에서 호스트된 에이전트 실행

F5 키를 눌러 디버깅을 사용하도록 설정된 로컬 HTTP 서버를 시작합니다. 대화형 테스트를 위해 Foundry 도구 키트 에이전트 검사기가 열리고 코드에서 중단점을 설정할 수 있습니다.

디버깅하지 않고 서버를 실행하려면 다음을 수행합니다.

python main.py

에이전트는 http://localhost:8088/에서 수신 대기합니다. curl(또는 HTTP 클라이언트)을 사용하여 테스트 프롬프트를 보냅니다.

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
    -d '{"input": "Write a haiku about deploying cloud applications.", "stream": false}'

샘플 워크플로 프로젝트는 필요한 환경 변수를 사용하여 .env 파일을 만듭니다. Foundry 자격 증명으로 .env 파일을 만들거나 업데이트합니다.

1. 운영 체제에 따라 환경 변수를 설정합니다.

   • Windows(PowerShell)
   • Windows(명령 프롬프트)
   • macOS/Linux(Bash)

   $env:FOUNDRY_PROJECT_ENDPOINT="https://<your-resource-name>.services.ai.azure.com/api/projects/<your-project-name>"
   $env:AZURE_AI_MODEL_DEPLOYMENT_NAME="your-deployment-name"
   

호스팅된 에이전트를 인증하세요

호스트된 에이전트 샘플은 DefaultAzureCredential을 사용하여 인증합니다. 지원되는 원본 중 하나를 통해 자격 증명을 제공하도록 개발 환경을 구성합니다. 예를 들면 다음과 같습니다.

• Azure CLI(az login)
• Visual Studio Code 계정 로그인
• Visual Studio 계정 로그인
• 서비스 주체에 대한 환경 변수(AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

샘플을 실행하기 전에 Azure CLI az account show 또는 az account get-access-token 명령을 실행하여 로컬로 인증을 확인합니다.

호스트된 에이전트는 대화형 모드 또는 컨테이너 모드에서 실행할 수 있습니다.

대화형 모드에서 호스트된 에이전트 실행

개발 및 테스트를 위해 호스트된 에이전트를 직접 실행합니다.

dotnet restore
dotnet build
dotnet run

컨테이너 모드에서 호스트된 에이전트 실행

컨테이너 모드에서 에이전트를 실행하려면 다음을 수행합니다.

1. Visual Studio Code 명령 팔레트를 열고 Foundry Toolkit: Open Container Agent Playground Locally 명령을 실행합니다.
2. 다음 명령을 사용하여 컨테이너화된 호스트 에이전트를 초기화합니다.

   dotnet restore
   dotnet build
   dotnet run
   

3. 플레이그라운드 인터페이스를 통해 에이전트에 요청을 제출합니다. 예를 들어 "운전하기에 저렴하고 재미있는 새로운 전기 SUV를 위한 슬로건 만들기"와 같은 프롬프트를 입력합니다.
4. 플레이그라운드 인터페이스에서 에이전트의 응답을 검토합니다.

호스트된 에이전트 워크플로 실행 시각화

Visual Studio Code 확장용 Microsoft Foundry 도구 키트는 워크플로의 에이전트가 상호 작용하고 공동 작업하는 방법을 보여주는 실시간 실행 그래프를 제공합니다. 프로젝트에서 이 시각화를 사용하기 위해 가시성을 활성화하세요.

csproj 파일에 다음 참조를 추가합니다.

<ItemGroup>
    <PackageReference Include="OpenTelemetry" Version="1.12.0" />
    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.12.0" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.12.0" />
    <PackageReference Include="System.Diagnostics.DiagnosticSource" Version="9.0.10" />
</ItemGroup>

다음 코드 조각을 포함하도록 프로그램을 업데이트합니다.

using System.Diagnostics;
using OpenTelemetry;
using OpenTelemetry.Logs;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

var otlpEndpoint =
    Environment.GetEnvironmentVariable("OTLP_ENDPOINT") ?? "http://localhost:4319";

var resourceBuilder = OpenTelemetry
    .Resources.ResourceBuilder.CreateDefault()
    .AddService("WorkflowSample");

var s_tracerProvider = OpenTelemetry
    .Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource("Microsoft.Agents.AI.*") // All agent framework sources
    .SetSampler(new AlwaysOnSampler()) // Ensure all traces are sampled
    .AddOtlpExporter(options =>
    {
        options.Endpoint = new Uri(otlpEndpoint);
        options.Protocol = OpenTelemetry.Exporter.OtlpExportProtocol.Grpc;
    })
    .Build();

호스트된 에이전트 워크플로 모니터링 및 시각화

호스트된 에이전트 워크플로 실행을 실시간으로 모니터링하고 시각화하려면 다음을 수행합니다.

1. 명령 팔레트를 엽니다(Ctrl+Shift+P).

2. 다음 명령을 실행합니다. >Foundry Toolkit: Open Visualizer for Hosted Agents.

VS Code에서 실행 그래프를 표시하는 새 탭이 열립니다. 시각화는 워크플로가 진행됨에 따라 자동으로 업데이트되어 에이전트와 해당 상호 작용 간의 흐름을 표시합니다.

포트 충돌

포트 충돌의 경우 Visual Studio Code 확장 설정에 대한 Microsoft Foundry 도구 키트에서 시각화 포트를 설정하여 시각화 포트를 변경할 수 있습니다. 이렇게 하려면 다음 단계를 수행합니다.

1. VS Code의 왼쪽 사이드바에서 기어 아이콘을 선택하여 설정 메뉴를 엽니다.
2. Extensions > Microsoft Foundry Configuration 선택합니다.
3. Hosted Agent Visualization Port 설정을 찾아 사용 가능한 포트 번호로 변경합니다.
4. VS Code를 다시 시작하여 변경 내용을 적용합니다.

코드의 포트 변경

모든 포트 충돌의 경우 환경 변수를 설정하여 시각화 포트를 FOUNDRY_OTLP_PORT 변경합니다. 그에 따라 프로그램에서 OTLP 엔드포인트를 업데이트합니다.

예를 들어 포트를 4318로 변경하려면 다음 명령을 사용합니다.

  $env:FOUNDRY_OTLP_PORT="4318"

프로그램에서 새 포트 번호를 사용하도록 OTLP 엔드포인트를 업데이트합니다.

var otlpEndpoint =
    Environment.GetEnvironmentVariable("OTLP_ENDPOINT") ?? "http://localhost:4318";

1. 명령 팔레트를 열고 Foundry 도구 키트: 호스트된 에이전트 배포를 선택합니다. 배포 웹 보기가 열립니다.
2. "배포 방법"에 대해 코드 또는 컨테이너를 선택합니다.
3. "코드"를 사용하여 배포하는 경우 "패키지 모드"에 대해 원격 또는 로컬을 선택합니다.
4. "컨테이너"를 사용하여 배포하는 경우 기본 ACR, 사용자 지정 ACR 또는 고객 ACR 이미지를 선택합니다.
5. "에이전트 이름"이 자동으로 채워집니다.
6. "다음" 단추를 선택합니다.
7. 이 "검토 및 배포" 페이지는 모두 자동으로 채워집니다.
8. "배포" 단추를 선택합니다.
9. Visual Studio Code 명령 팔레트를 열고 Foundry Toolkit: Deploy Hosted Agent 명령을 실행합니다.

1. Visual Studio Code 명령 팔레트를 열고 Foundry Toolkit: Deploy Hosted Agent 명령을 실행합니다.
2. "배포 방법"에 대해 코드 또는 컨테이너를 선택합니다.
3. "코드"를 사용하여 배포하는 경우 "패키지 모드"에 대해 원격 또는 로컬을 선택합니다.
4. "컨테이너"를 사용하여 배포하는 경우 기본 ACR, 사용자 지정 ACR 또는 고객 ACR 이미지를 선택합니다.
5. "에이전트 이름"이 자동으로 채워집니다.
6. "다음" 단추를 선택합니다.
7. 이 "검토 및 배포" 페이지는 모두 자동으로 채워집니다.
8. "배포" 단추를 선택합니다.