Visual Studio Code 호스트된 에이전트 워크플로 만들기(미리 보기)

Visual Studio Code 확장용 Microsoft Foundry를 사용하여 hosted Foundry 에이전트 워크플로를 만들고 테스트하고 배포합니다. 호스트된 워크플로를 사용하면 여러 에이전트가 각각 고유한 모델, 도구 및 지침을 사용하여 순차적으로 공동 작업할 수 있습니다.

시작하기 전에 확장을 사용하여 Foundry 에이전트 서비스 에이전트를 빌드합니다. 그런 다음 호스트된 워크플로를 해당 에이전트에 추가할 수 있습니다.

이 문서에서는 워크플로 project 만들고, 로컬로 실행하고, 실행을 시각화하고, Foundry 작업 영역에 배포하는 방법을 설명합니다.

필수 조건

배포된 모델을 사용하는 Foundry 프로젝트 또는 Azure OpenAI 리소스입니다.
Visual Studio Code 확장용 Microsoft Foundry 설치되어 있습니다.
Azure AI 사용자 및 AcrPull 역할이 할당된 프로젝트의 관리 ID입니다. 또한 호스트된 에이전트를 배포하려는 Foundry project 관리 ID에 acrPull 역할을 할당합니다.
호스트된 에이전트에 대해 지원되는 지역 입니다.

Python 3.12 이상.

.NET 9 SDK 이상

호스트된 에이전트 워크플로 만들기

Visual Studio Code 확장용 Foundry를 사용하여 호스트된 에이전트 워크플로를 만들 수 있습니다. 호스트된 에이전트 워크플로는 작업을 수행하기 위해 함께 작동하는 에이전트의 시퀀스입니다. 워크플로의 각 에이전트에는 고유한 모델, 도구 및 지침이 있을 수 있습니다.

명령 팔레트를 엽니다(Ctrl+Shift+P).
다음 명령을 실행합니다. >Microsoft Foundry: Create a New Hosted Agent.
Microsoft 에이전트 프레임워크와 LangGraph 중 하나를 선택하세요.
단일 에이전트 호텔 어시스턴트 또는 Writer-Reviewer 에이전트 워크플로(다중 에이전트) 중에서 템플릿을 선택하십시오.
프로그래밍 언어를 선택합니다.
프로젝트에 이미 배포한 모델을 선택하거나 모델 카탈로그를 찾아봅니다.
새 워크플로를 저장할 폴더를 선택합니다.

호스트된 에이전트 프로젝트에 대한 파일은 시작하기 위해 선택한 프레임워크, 템플릿 및 언어에 따라 선택한 폴더에 생성됩니다. 필요에 따라 해당 코드를 제거하거나 수정할 수 있습니다.

종속성 설치

호스팅된 에이전트 프로젝트에 필요한 종속성을 설치합니다. 종속성은 project 만들 때 선택한 프로그래밍 언어에 따라 달라집니다.

가상 환경을 만듭니다.
```
 python -m venv .venv
```

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

# PowerShell
./.venv/Scripts/Activate.ps1

# Windows cmd
.venv\Scripts\activate.bat

# Unix/MacOS
source .venv/bin/activate

다음 패키지를 설치합니다.

pip install azure-ai-agentserver-agentframework

project 디렉터리로 이동하여 이 명령을 실행하여 필요한 NuGet 패키지를 가져옵니다.
```
dotnet restore
```

호스트된 워크플로를 로컬로 실행

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

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

MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>

중요합니다

.env 파일을 버전 제어에 커밋하지 마세요. 파일의 .gitignore에 추가합니다.

호스팅 에이전트를 인증하십시오.

호스트된 에이전트 샘플은 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 명령을 실행하여 로컬로 인증을 확인합니다.

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

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

호스트된 에이전트를 Visual Studio Code 로컬로 실행하려면 F5 키를 선택합니다. 그러면 에이전트 검사자가 열리고 애플리케이션이 실행됩니다.

이렇게 하면:

에이전트 서버를 시작합니다 . CLI는 agentdev 포트 5679에 디버그피가 연결된 포트 8087에서 에이전트를 HTTP 서버로 래핑합니다.
에이전트 검색: UI는 .에서 /agentdev/entities사용 가능한 에이전트/워크플로를 가져옵니다.
스트림 실행: 채팅 입력은 /v1/responses을(를) 통해 입력되고, SSE를 통해 이벤트가 실시간 시각화를 위해 다시 스트리밍됩니다.
코드 탐색 사용: 워크플로 노드를 두 번 클릭하여 편집기에서 해당 원본 파일을 엽니다.
로컬 에이전트와의 채팅을 사용하도록 하고 응답을 보거나 디버깅을 위해 중단점을 적중하는 등의 기능을 설정합니다.

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

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

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

set AZURE_AI_PROJECT_ENDPOINT=https://your-resource-name.openai.azure.com/
set AZURE_AI_MODEL_DEPLOYMENT_NAME=your-deployment-name

export AZURE_AI_PROJECT_ENDPOINT="https://your-resource-name.openai.azure.com/"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="your-deployment-name"

호스팅 에이전트를 인증하십시오.

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

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

팁 (조언)

컨테이너 에이전트를 시작하기 전에 로컬 플레이그라운드를 열어 시각화가 제대로 작동하는지 확인합니다.

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

Visual Studio Code 명령 팔레트를 열고 Microsoft Foundry: Open Container Agent Playground Locally 명령을 실행합니다.
다음 명령을 사용하여 컨테이너화된 호스트 에이전트를 초기화합니다.
```
dotnet restore
dotnet build
dotnet run
```
플레이그라운드 인터페이스를 통해 에이전트에 요청을 제출합니다. 예를 들어 "운전하기에 저렴하고 재미있는 새로운 전기 SUV를 위한 슬로건 만들기"와 같은 프롬프트를 입력합니다.
플레이그라운드 인터페이스에서 에이전트의 응답을 검토합니다.

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

Visual Studio Code 확장용 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();

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

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

명령 팔레트를 엽니다(Ctrl+Shift+P).
다음 명령을 실행합니다. >Microsoft Foundry: Open Visualizer for Hosted Agents.

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

포트 충돌

포트 충돌의 경우 Foundry 확장 설정에서 시각화 포트를 설정하여 변경할 수 있습니다. 이를 위해, 다음 단계를 수행합니다.

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

코드의 포트 변경

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

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

  $env:FOUNDRY_OTLP_PORT="4318"

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

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

호스트된 에이전트를 배포하기

호스트된 에이전트를 로컬로 테스트한 후 다른 팀 구성원과 애플리케이션에서 사용할 수 있도록 Foundry 작업 영역에 배포합니다.

중요합니다

필수 구성 요소에 설명된 대로 Foundry 작업 영역에서 호스트된 에이전트를 배포하는 데 필요한 권한을 부여해야 합니다. 필요한 역할 할당을 얻으려면 Azure 관리자와 협력해야 할 수 있습니다.

Visual Studio Code 명령 팔레트를 열고 Microsoft Foundry: Deploy Hosted Agent 명령을 실행합니다.
대상 작업 영역을 선택하고, 컨테이너 에이전트 파일()container.py을 지정하고, 필요에 따라 다른 배포 매개 변수를 정의하여 배포 설정을 구성합니다.
배포에 성공하면 호스트된 에이전트가 Microsoft Foundry 확장 트리 뷰의 Hosted Agents (Preview) 섹션에 표시됩니다.
배포된 에이전트를 선택하여 통합된 플레이그라운드 인터페이스를 사용해 자세한 정보에 접근하고 기능을 테스트합니다.

Visual Studio Code 명령 팔레트를 열고 Microsoft Foundry: Deploy Hosted Agent 명령을 실행합니다.
대상 작업 영역을 선택하고, 컨테이너 에이전트 파일()<your-project-name>.csproj을 지정하고, 필요에 따라 다른 배포 매개 변수를 정의하여 배포 설정을 구성합니다.
배포에 성공하면 호스트된 에이전트가 Microsoft Foundry 확장 트리 뷰의 Hosted Agents (Preview) 섹션에 표시됩니다.
배포된 에이전트를 선택하여 통합된 플레이그라운드 인터페이스를 사용해 자세한 정보에 접근하고 기능을 테스트합니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-04-16

다음을 통해 공유

Visual Studio Code 호스트된 에이전트 워크플로 만들기(미리 보기)

필수 조건

호스트된 에이전트 워크플로 만들기

종속성 설치

호스트된 워크플로를 로컬로 실행

호스팅 에이전트를 인증하십시오.

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

호스팅 에이전트를 인증하십시오.

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

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

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

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

포트 충돌

코드의 포트 변경

호스트된 에이전트를 배포하기

관련 콘텐츠

피드백

추가 리소스